ShapeDiver Viewer - Parameter API
The parameters interface is part of the global API.
It allows to
- get the definition of currently registered parameters, and
- update the values of currently registered parameters, which in turns results in an update of the scene.
Methods
-
addEventListener(type, callback)
-
Add a callback to be invoked when a certain event occurs
Parameters:
Name Type Description type
ParameterEventType Type of event to subscribe to
callback
EventListenerCallback Function to be called when the event fires
Returns:
-
Type Description APIResponse APIResponse with an EventListenerToken object. The event listener token can be used to remove the event listener by calling removeEventListener.
-
-
canGoBackInHistory()
-
Check whether it is possible to go back in history
See:
Returns:
-
Type Description Boolean true if it is possible to go back in history
-
canGoForwardInHistory()
-
Check whether it is possible to go forward in history
See:
Returns:
-
Type Description Boolean true if it is possible to go forward in history
-
get( [filter])
-
Get parameter definitions for some or all parameters
Parameters:
Name Type Argument Description filter
ParameterDefinition <optional>
Definitions for parameters whose definition matches the properties of this filter object will be returned, may be empty in which case all parameter definitions will be returned
Properties
Name Type Argument Description id
String <optional>
id of parameter
name
String <optional>
name of parameter
plugin
String <optional>
runtime id of plugin the parameter belongs to
type
String <optional>
type of parameter
Returns:
-
Type Description APIResponse APIResponse with an array of parameter definitions
-
-
goBackInHistoryAsync( [payload])
-
Go back in history, if this is possible
See:
Parameters:
Name Type Argument Description payload
* <optional>
Payload which will be passed through to the response and events related to a call of this function
Returns:
-
Type Description Promise.<APIResponse> APIResponse with a data array of ParameterUpdateObject objects, corresponding to the parameter state after the movement in history. In case the scene update fails or is aborted due to a newer update, the APIResponse will not contain a data array but an err.
-
goForwardInHistoryAsync( [payload])
-
Go forward in history, if this is possible
See:
Parameters:
Name Type Argument Description payload
* <optional>
Payload which will be passed through to the response and events related to a call of this function
Returns:
-
Type Description Promise.<APIResponse> APIResponse with a data array of ParameterUpdateObject objects, corresponding to the parameter state after the movement in history. In case the scene update fails or is aborted due to a newer update, the APIResponse will not contain a data array but an err.
-
removeEventListener(token)
-
Remove an event listener
Parameters:
Name Type Description token
EventListenerToken event listener token for event listener to be removed
Returns:
-
Type Description APIResponse APIResponse with a Boolean data, indicating whether the event listener could be removed.
-
-
updateAsync(values [, payload])
-
Update parameter values and corresponding parts of the scene.
Depending on which parameters are included in the request, the update may involve several plugins. The return value will include a status code for each parameter which was specified in the request.
Parameters:
Name Type Argument Description values
Array.<ParameterUpdateObject> Objects defining the parameters to update and their new values
payload
* <optional>
Payload which will be passed through to the response and events related to a call of this function
Returns:
-
Type Description Promise.<APIResponse> APIResponse with a data array of ParameterUpdateObject objects, each including the result property, for all parameters which had been provided. In case the scene update fails or is aborted due to a newer update, the APIResponse will not contain a data array but an err.
-
-
updateProperties( [definitions])
-
Update properties of registered parameters.
The following properties can be updated: name, order, hidden This function will fail in case no unique parameter can be found for each parameter definition given.
Parameters:
Name Type Argument Description definitions
Array.<ParameterDefinition> <optional>
updated parameter definitions
Returns:
-
Type Description APIResponse APIResponse with its data set to a boolean according to success or error
-
Members
-
<readonly> EVENTTYPE :ParameterEventType
-
Enum for supported parameter event types.
Type:
Properties:
Name Type Default Description REGISTERED
ParameterEventType registered a parameter has been registered
UPDATE
ParameterEventType update the definition of a parameter has been updated, typically one of the properties name or order or hidden
VALUE_UPDATE
ParameterEventType value.update the value of a parameter has been changed
-
<readonly> RESULT :ParameterUpdateResult
-
Enum for parameter update result.
Type:
Properties:
Name Type Default Description PARAM_NOT_FOUND
ParameterUpdateResult param_not_found the parameter was not found
NO_VALUE
ParameterUpdateResult no_value no value was given
VALUE_REJECT
ParameterUpdateResult value_reject the new parameter value was rejected
VALUE_EXISTS
ParameterUpdateResult value_exists the parameter value had already been set
VALUE_OK
ParameterUpdateResult value_ok the new parameter value was accepted
PLUGIN_NOT_FOUND
ParameterUpdateResult plugin_not_found the plugin responsible to handle the parameter update was not found
ERROR
ParameterUpdateResult error the parameter update failed
LIVE
ParameterUpdateResult live the parameter update results in a live update
CACHE
ParameterUpdateResult cache the parameter update results in an update which can be answered from the local cache
LOAD
ParameterUpdateResult load the parameter update results in an update which needs to be loaded from somewhere
ABORT
ParameterUpdateResult abort the parameter update was aborted, it was superseded by another update
-
<readonly> TYPE :ParameterType
-
Enum for parameter type.
Type:
Properties:
Name Type Default Description FLOAT
ParameterType Float floating point number
INT
ParameterType Int integer number
EVEN
ParameterType Even even integer number
ODD
ParameterType Odd odd integer number
STRING
ParameterType String string with maximum length
COLOR
ParameterType Color color string, including opacity (10 digits, e.g. 0xffffffaa)
STRINGLIST
ParameterType StringList choose from a list of strings
BOOL
ParameterType Bool boolean
TIME
ParameterType Time date / time (currently unsupported)
FILE
ParameterType File -
<readonly> VISUALIZATION :ParameterVisualization
-
Enum for parameter visualization.
Type:
Properties:
Name Type Default Description SLIDER
ParameterVisualization slider currently the only choice for numeric types (Float, Int, Even, Odd)
SEQUENCE
ParameterVisualization sequence for type StringList
CYCLE
ParameterVisualization cycle for type StringList
DROPDOWN
ParameterVisualization dropdown for type StringList
CHECKLIST
ParameterVisualization checklist for type StringList
CLOCK
ParameterVisualization clock for type Time
CALENDAR
ParameterVisualization calendar for type Time
Type Definitions
-
ParameterDefinition
-
Parameter definition
Type:
- Object
Properties:
Name Type Argument Description id
String unique id of the parameter (unique within a plugin instance)
name
String <optional>
name of the parameter
_name
String <optional>
original name of the parameter, will be set in case the parameter name got changed from its original value
note
String <optional>
description of the parameter
type
ParameterType <optional>
type of the parameter
decimalplaces
Number <optional>
number of decimal places for type Float
choices
Array.<String> <optional>
choices for type StringList
defval
Number | String | Boolean default value, represented as string
value
Number | String | Boolean current value of the parameter
group
String <optional>
group of the parameter for visualization purposes
max
String <optional>
maximum value for numeric types, max length for type String, max size for type File/Blob
min
String <optional>
minimum value for numeric types
plugin
String <optional>
optional runtime id of plugin the parameter belongs to
hidden
Boolean <optional>
must exist and be true if the parameter should be hidden from the ui
order
Number <optional>
optional number used for ordering parameters in the ui
visualization
ParameterVisualization <optional>
how to visualize the parameter
-
ParameterEventType
-
Export event type, see EVENTTYPE for values
Type:
- String
-
ParameterType
-
Parameter type, see TYPE for values
Type:
- String
-
ParameterUpdateObject
-
Parameter update object, provides the possibility to select parameters by their id or name
Type:
- Object
Properties:
Name Type Argument Description id
String <optional>
id of parameter, takes precedence over idOrName and name
idOrName
String <optional>
id or name of parameter, takes precedence over name
name
String <optional>
name of parameter, last priority after id and idOrName
plugin
String <optional>
optional runtime id of plugin the parameter belongs to, specify this when using several sessions to the same ShapeDiver model
value
* Parameter value to set according to parameter TYPE
result
ParameterUpdateResult <optional>
Result of the parameter update, will be set in response to update
-
ParameterUpdateResult
-
Parameter update result, see RESULT for values
Type:
- String
-
ParameterVisualization
-
Parameter visualization, see VISUALIZATION for values
Type:
- String