API Docs

Class: ParamType

PD. ParamType

Defines a dynamic parameter type.

A dynamic parameter type specifies the type of a value, its display format, allowable range, incremental steps, large and small steps, as well as clamping and wrapping options.

A parameter can be one of four different primitive types, and have a range of possible values depending on its type:

  • 'number': An arbitrary-precision, base-10 decimal number value, from the JSON 'number' value.
  • 'boolean': A 'true' or 'false' value, from the JSON 'true' or 'false' value.
  • 'string': A string of Unicode code points, from the JSON 'string' value.
  • 'function': A callback function typically invoked using a button.

new ParamType( [config])

Creates a new dynamic parameter type.

Parameters:
Name Type Argument Description
config object <optional>

An optional configuration object.
Properties of config:
Name Type Argument Description
valueType string <optional>

The type of primitive value ('number', 'boolean' or 'string').
format PD.FORMAT <optional>

The display format of a numerical value.
decimals number <optional>

The number of decimal places for displaying decimal values, defaults to 2.
step number <optional>

The smallest incremental step, defaults to 0.01.
minor number <optional>

An appropriate small incremental step, defaults to 5 * step.
major number <optional>

An appropriate larger incremental step, defaults to 50 * step.
min number <optional>

The minimum allowable value, defaults to -Infinity.
max number <optional>

The maximum allowable value, defaults to +Infinity.
options Array | null <optional>

An optional array of selectable values, defaults to null.
clamp boolean <optional>

Whether or not to constrain the value to between the min and max range, defaults to true.
wrap boolean <optional>

Whether or not to wrap around the value at the min/max thresholds, defaults to false.
Author:
  • drajmarsh

Members

:boolean

clamp

Whether or not to constrain the value to between the min and max range, default to true.

Type
  • boolean
:number

decimals

The number of decimal places for displaying decimal values.

Type
  • number
:PD.FORMAT

format

The format to display the value in.

Type
:number

id

A unique identifier for identifying equality.

Type
  • number
:boolean

isParamType <readonly>

A flag identifying this object as a dynamic parameter.

Type
  • boolean
:number

major

An appropriate larger incremental step, defaults to 50 * step.

Type
  • number
:number

max

The maximum allowable value, defaults to +Infinity.

Type
  • number
:number

min

The minimum allowable value, defaults to -Infinity.

Type
  • number
:number

minor

An appropriate smaller incremental step, defaults to 5 * step.

Type
  • number
:Array|null

options

An optional array of selectable values, defaults to null.

If an array of options are defined, then the parameter value must match one of those options.

Selectable options can be given as either an array of strings, in which case the value of each option will be an integer equal to their ordinal index in the array, or an array of objects with name and value properties.

If using options with non-numeric values, you must set the valueType property appropriately.

Type
  • Array | null
:number

step

The smallest incremental step in the value, defaults to 0.01.

Type
  • number
:string

valueType

The value type ('number', 'boolean' or 'string').

Type
  • string
:boolean

wrap

Whether or not to wrap around the value at the min/max thresholds, default to false.

Type
  • boolean
:PD.ParamType

Align <static>

Defines a PD.ALIGN value.

Type
:PD.ParamType

Animation <static>

Defines an animation value.

Type
:PD.ParamType

Boolean <static>

Defines a boolean checkbox value.

Type
:PD.ParamType

Button <static>

Defines a button with a callback.

Type
:PD.ParamType

Color <static>

Defines a numeric hexadecimal color value.

Type
:PD.ParamType

Decimal <static>

Defines a decimal value in the range 0 to 100.

Type
:PD.ParamType

Dimension <static>

Defines a dimension or value as a fraction or in the current units.

NOTE: Dimensions are different to distances in that they can be given as either an absolute value in the current dimension units or as fractional value relative to another known dimension.

Type
:PD.ParamType

Distance <static>

Defines a distance or length value in the current model units.

Type
:PD.ParamType

Fraction <static>

Defines a fractional value in the range 0 to 1.

Type
:PD.ParamType

Integer <static>

Defines an integer value.

Type
:PD.ParamType

Message <static>

Defines a simple test message.

Type
:PD.ParamType

Metres <static>

Defines a distance always displayed as metres or feet.

Type
:PD.ParamType

Percentage <static>

Defines a percentage value in the range 0 to 1, but displayed as 0 to 100.

Type
:PD.ParamType

SmallDimension <static>

Defines a small dimension or value as a fraction or in the current units.

NOTE: Dimensions are different to distances in that they can be given as either an absolute value in the current dimension units or as fractional value relative to another known dimension.

Type
:PD.ParamType

SmallDistance <static>

Defines a small distance or length value in the current model units.

Type
:PD.ParamType

Switch <static>

Defines a boolean switch value.

Type
:PD.ParamType

Text <static>

Defines a a single-line text input.

Type
:PD.ParamType

TextBlock <static>

Defines a a multi-line text input.

Type
:PD.ParamType

TinyDistance <static>

Defines a tiny distance or length value in the current model units.

Type

Methods

clone( [config])

Creates a copy of the dynamic parameter type with some configuration changes.

Parameters:
Name Type Argument Description
config object <optional>

An optional configuration object.
Properties of config:
Name Type Argument Description
valueType string <optional>

The type of primitive value ('number', 'boolean' or 'string').
format PD.FORMAT <optional>

The display format of a numerical value.
decimals number <optional>

The number of decimal places for displaying decimal values, defaults to 2.
step number <optional>

The smallest incremental step, defaults to 0.01.
minor number <optional>

An appropriate small incremental step, defaults to 5 * step.
major number <optional>

An appropriate larger incremental step, defaults to 50 * step.
min number <optional>

The minimum allowable value, defaults to -Infinity.
max number <optional>

The maximum allowable value, defaults to +Infinity.
options Array | null <optional>

An optional array of selectable values, defaults to null.
clamp boolean <optional>

Whether or not to constrain the value to between the min and max range, defaults to true.
wrap boolean <optional>

Whether or not to wrap around the value at the min/max thresholds, defaults to false.
Returns:

Returns a new cloned parameter type with the given configuration changes.

Type
PD.ParamType

fromJSON(data)

Safely copy properties from a source object.

See the PD.Base#fromJSON method for more details.

Parameters:
Name Type Description
data object

The source object containing data to copy.
Returns:

Returns this instance to support method chaining.

Type
PD.ParamType

getDisplayValue(value)

Retrieves the formatted display value.

Parameters:
Name Type Description
value any

The value to display.
Returns:

Returns a formatted string.

Type
string

increment(value, increment [, event])

Increments or decrements the given value based on its type.

Parameters:
Name Type Argument Default Description
value any

The value to increment/decrement.
increment number 1

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

toJSON( [data])

Converts the object instance to a simple POJO for JSON storage.

This method is used to copy, store and save the data for ths object, so the returned object must have all the properties required be able to rebuild this instance in its entirety when passed to the class constructor.

See the PD.Base#toJSON method for more details.

Parameters:
Name Type Argument Description
data object <optional>

An optional parent object to append this data to.
Returns:

Returns a JSON object.

Type
object

update()

Updates the range of distance values relative to the model.

validate(value)

Retrieve a valid value for this parameter type based on the given value.

Parameters:
Name Type Description
value any

The value to validate.
Returns:

Return a valid value.

Type
any

addCachedType(name, config) <static>

Adds a custom parameter type to a static cache.

Having each component instance create their own parameter types within the getDynamicParameters() method is not usually a problem as both parameters and parameter types are transitory and only stored whilst the host element is selected within the user interface.

However, some elements create and maintain their own persistent parameters, so it makes sense to be able to cache commonly used parameter types so they can be shared.

Parameters:
Name Type Description
name string

The name of the parameter type.
config PD.ParamType | object

A parameter type or parameter type configuration object.
Returns:

Returns the given parameter type or a newly created one.

Type
PD.ParamType

clearCachedTypes() <static>

Empties the global cache of custom parameter types.

getCachedType(name) <static>

Accesses a static cache to retrieve a custom parameter type.

Having each component instance create their own parameter types within the getDynamicParameters() method is not usually a problem as both parameters and parameter types are transitory and only stored whilst the host element is selected within the user interface.

However, some elements share non-core custom parameter types whilst others create and maintain their own persistent parameters, so it makes sense to be able to cache commonly used parameter types so they can be reused and shared.

Parameters:
Name Type Description
name string

The name of the parameter type.
Returns:

Returns the cached parameter type with that name, or null if it is an unrecognised name.

Type
PD.ParamType

getCoreType(name) <static>

A cache for lazily creating shared parameter types used by core classes.

Parameters:
Name Type Description
name string

The name of the shared parameter type.
Returns:

Returns the shared parameter type with that name, or a decimal value (0 to 100) if it is an unrecognised name.

Type
PD.ParamType