API Docs

Class: Parameter

PD. Parameter

Defines a dynamic parameter.

A dynamic parameter is an object that stores a value as well as all the associated metadata required to be able to validate, increment, display and edit it within the user interface. For more information on defining and using them within your own custom elements, see the Dynamic Parameters page.

All dynamic parameters reference a shared PD.ParamType that controls its value range and allows it to be incremented/decremented and displayed.

new Parameter( [config])

Creates a new dynamic parameter.

Parameters:
Name Type Argument Description
config object <optional>

A configuration object.
Properties of config:
Name Type Argument Description
name string <optional>

The name of the instance property for the parameter.
title string <optional>

The human-readable title to show above the parameter.
description string <optional>

A human-readable description of what this parameter does.
callback function <optional>

An optional callback function invoked whenever the value changes.
bidirectional boolean <optional>

Whether to create a bidirectional reactive link with property value, defaults to false.
undoable boolean <optional>

Whether value changes will create a global undo record, defaults to true.
value any <optional>

The current value of the parameter.
units string <optional>

An optional units abbreviation.
paramType PD.ParamType <optional>

The shared parameter type.
Author:
  • drajmarsh

Members

:boolean

active

Whether or not to show this parameter as active/editable.

NOTE: This is intended for use by the UI to mute, dull or fade the DOM input component used to edit the parameter value when active is false.

Type
  • boolean
:boolean

bidirectional

Whether to create a bidirectional reactive link with property value, defaults to false.

Type
  • boolean
:function

callback

A callback function invoked whenever this parameter value is changed.

This is invoked only when the change is actually applied to the host object via the setValueOnHostIfDifferent() or setValueOnHost() methods.

Type
  • function
:string

description

A human-readable description of what this parameter does.

Type
  • string
:boolean

enabled

Whether or not this parameter is enabled.

NOTE: This is intended for use by the UI to enable/disable the DOM input component used to edit the parameter value.

Type
  • boolean
:boolean

isParameter <readonly>

A flag identifying this object as a dynamic parameter.

Type
  • boolean
:string

name

The name of the instance property for the parameter.

This needs to be the exact name of the property on the host object that will be updated when this parameter value changes.

Type
  • string
:PD.ParamType

paramType

Defines the type of stored parameter value.

Type
:string

title

The human-readable title to show above the parameter.

Type
  • string
:boolean

undoable

Whether changes to the parameter value will create a global undo record, defaults to true.

Type
  • boolean
:string

units

A units abbreviation for the value.

Type
  • string
:any

value

The current value of the parameter.

Type
  • any

Methods

getDisplayValue()

Retrieves the formatted display value.

Returns:

Returns a formatted string.

Type
string

getReferenceDimension()

Retrieve the reference for fractional dimensions.

Values with a format of PD.FORMAT.DIMENSION are special in that they can be given as absolute dimensions or as fractional values. Typically the host application will determine between the two, however some UI components offer an option to toggle between fractional and absolute values. To support this, set the PD.Parameter#dimensionCallback property to a function that retrieves the reference dimension.

Returns:
Type
number

getValueFromHost(host)

Retrieve the parameter value from a matching property on the host object.

Parameters:
Name Type Description
host object

The object to check for a matching property to get the value of.
Returns:

Returns the value of the given (nested) property on the host, or undefined if no matching property was found.

Type
any

increment(value, increment [, event])

Increments or decrements the given value based on its type.

Parameters:
Name Type Argument Description
value any

The value to increment/decrement.
increment number

The amount of increment, positive or negative.
event object | PD.KEY <optional>

A mouse wheel/scroll event, or a modifier key code.
Returns:

Returns the incremented/decremented new value.

Type
any

isSwitchableDimension()

Determines if this parameter can toggle to a fractional dimension.

Values with a format of PD.FORMAT.DIMENSION are special in that they can be given as absolute dimensions or as fractional values. This method allows a UI component to offer the option to toggle between them. To support this, set the PD.Parameter#dimensionCallback property to a function that retrieves the reference dimension.

Returns:

Returns true if the param is able to toggle.

Type
boolean

setValue(value)

Sets the current value of the parameter.

This method only sets the parameter value, it does not affect any matching owner property or generate an undo/redo entry.

Parameters:
Name Type Description
value any

The value to set the property to.

setValueOnHost(host)

Sets a matching property on the host object to the current value of the parameter.

This method only checks that a matching property exists on the host before assigning it the parameter value, and does not trigger a model update or undo event. If you only want to set the property if it is different from the value on the host, and trigger a model update and/or undo event, you should use the setValueOnHostIfDifferent() method instead.

Parameters:
Name Type Description
host object

The object to check for a matching property to set the value of.
Returns:

Returns true if a matching property was found and its value was set.

Type
boolean

setValueOnHostIfDifferent(target, group, host)

Sets a matching property on the host object to the current value of the parameter.

This method differs from setValueOnHost() in that it only updates the host property if the parameter value is different. It does this by determining an appropriate tolerance value based on parameter type and its step property.

Parameters:
Name Type Description
target object

The object to check for a matching property to set.
group PD.ParamGroup

The parameter group that this dynamic parameter belongs to.
host object

The host object that the parameter group belongs to.
Returns:

Returns true if there is a matching property and its value was changed.

Type
boolean

updateValueFromHost(host)

Update the value of the parameter from a matching property on the host object.

Parameters:
Name Type Description
host object

The object to check for a matching property to get the value of.
Returns:

Returns true if a matching property was found and the value updated.

Type
boolean