You are reading the documentation for the version 2 of the ShapeDiver viewer API. Free support for this viewer version will be discontinued on June 1st, 2024.

Please refer to the version 3 documentation here. See also the migration guide from version 2 to version 3 here.

Interface: ApiParameterInterface

api.parameters

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

JavaScript File or Blob

<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
ShapeDiver 3D Viewer, Copyright © 2015-2019 ShapeDiver GmbH. Documentation generated by JSDoc 3.5.5 on Wed Jul 3rd 2019 using the DocStrap template.