DerivedProperty¶

Overview¶

A DerivedProperty is computed based on other Properties. This implementation inherits from Property to (a) simplify implementation and (b) ensure it remains consistent. Note that the setters should not be called directly, so the setters (set, reset and es5 setter) throw an error if used directly.

@author Sam Reid (PhET Interactive Simulations)

Class DerivedProperty¶

T = type of the derived value Parameters[] = types of the callback parameters, e.g. [ Vector2, number, boolean ]

import { DerivedProperty } from 'scenerystack/axon';

Constructor¶

new DerivedProperty( dependencies : RP1<T1>, derivation : ( ...params: [ T1 ] ) => T, providedOptions? : DerivedPropertyOptions<T> )¶

Instance Methods¶

hasDependency( dependency : TReadOnlyProperty<IntentionalAny> ) : boolean¶

Determines whether this DerivedProperty has a specific dependency.

recomputeDerivation()¶

Allows forcing a recomputation (as a possible workaround to listener order). This works well if you have a non-Property event that should trigger a value change for this Property.

For example: myEmitter.addListener( () => myDerivedProperty.recomputeDerivation() ); myObservableArray.addItemAddedListener( () => myDerivedProperty.recomputeDerivation() );

dispose()¶

setDeferred( isDeferred : boolean ) : ( () => void ) | null¶

Support deferred DerivedProperty by only calculating the derivation once when it is time to undefer it and fire notifications. This way we don't have intermediate derivation calls during PhET-iO state setting.

Static Methods¶

valueEquals( firstProperty : TReadOnlyProperty<unknown>, secondProperty : TReadOnlyProperty<unknown>, options? : DerivedPropertyOptions<boolean> ) : TReadOnlyProperty<boolean>¶

Creates a derived boolean Property whose value is true iff firstProperty's value is equal to secondProperty's value.

valueNotEquals( firstProperty : TReadOnlyProperty<unknown>, secondProperty : TReadOnlyProperty<unknown>, options? : DerivedPropertyOptions<boolean> ) : TReadOnlyProperty<boolean>¶

Creates a derived boolean Property whose value is true iff firstProperty's value is not equal to the secondProperty's value.

valueEqualsConstant( firstProperty : TReadOnlyProperty<unknown>, value : unknown, options? : DerivedPropertyOptions<boolean> ) : TReadOnlyProperty<boolean>¶

Creates a derived boolean Property whose value is true iff firstProperty's value is equal to a constant value.

valueNotEqualsConstant( firstProperty : TReadOnlyProperty<unknown>, value : unknown, options? : DerivedPropertyOptions<boolean> ) : TReadOnlyProperty<boolean>¶

Creates a derived boolean Property whose value is true iff firstProperty's value is not equal to a constant value.

and( properties : TReadOnlyProperty<boolean>[], options? : PropertyOptions<boolean> ) : UnknownDerivedProperty<boolean>¶

Creates a derived boolean Property whose value is true iff every input Property value is true.

or( properties : TReadOnlyProperty<boolean>[], options? : PropertyOptions<boolean> ) : UnknownDerivedProperty<boolean>¶

Creates a derived boolean Property whose value is true iff any input Property value is true.

multiply( properties : TReadOnlyProperty<number>[], options? : PropertyOptions<number> ) : UnknownDerivedProperty<number>¶

Creates a derived number Property whose value is the result of multiplying all (number) dependencies together.

add( properties : TReadOnlyProperty<number>[], options? : PropertyOptions<number> ) : UnknownDerivedProperty<number>¶

Creates a derived number Property whose value is the result of adding all (number) dependencies together.

not( propertyToInvert : TReadOnlyProperty<boolean>, options? : DerivedPropertyOptions<boolean> ) : DerivedProperty<boolean, boolean, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown>¶

Creates a derived boolean Property whose value is the inverse of the provided property.

fromRecord( key : TReadOnlyProperty<KeyType>, record : Record<KeyType, ValueType | TReadOnlyProperty<ValueType>>, options? : DerivedPropertyOptions<ValueType | TReadOnlyProperty<ValueType>> ) : UnknownDerivedProperty<ValueType>¶

Creates a derived property based on a record lookup. When evaluated, the DerivedProperty returns the value of the Property in the record corresponding to the key's current value.

Record values can also be non-Property values, in which case the DerivedProperty will return that value.

@param key - A property whose current value corresponds to one of the keys in the record. @param record - A record mapping keys to Properties or values. @param options - Optional settings for the DerivedProperty

toFixed( valueProperty : TReadOnlyProperty<number>, decimalPlaces : number, options? : DerivedPropertyOptions<string> ) : DerivedProperty<string, number, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown>¶

Creates a derived property that formats the numeric value from the provided property with a fixed number of decimal places.

@param valueProperty @param decimalPlaces @param options

deriveAny( dependencies : Array<TReadOnlyProperty<unknown>>, derivation : () => T, providedOptions? : DerivedPropertyOptions<T> ) : UnknownDerivedProperty<T>¶

Create a DerivedProperty from any number of dependencies. This is parallel to Multilink.multilinkAny

Static Properties¶

DerivedPropertyIO : ( parameterType: IOType ) => IOType¶

Class DerivedProperty1¶

Convenience classes for subclassing DerivedProperty

import { DerivedProperty1 } from 'scenerystack/axon';

Class DerivedProperty2¶

import { DerivedProperty2 } from 'scenerystack/axon';

Class DerivedProperty3¶

import { DerivedProperty3 } from 'scenerystack/axon';

Class DerivedProperty4¶

import { DerivedProperty4 } from 'scenerystack/axon';

Class DerivedProperty5¶

import { DerivedProperty5 } from 'scenerystack/axon';

Type DerivedPropertyOptions¶

import type { DerivedPropertyOptions } from 'scenerystack/axon';

• phetioLinkDependencies?: boolean
  When true, if this DerivedProperty is PhET-iO instrument, add a LinkedElement for each PhET-iO instrumented dependency.
• & StrictOmit<PropertyOptions<T>, "phetioReadOnly">

Type UnknownDerivedProperty¶

Convenience type for a Derived property that has a known return type but unknown dependency types.

import type { UnknownDerivedProperty } from 'scenerystack/axon';

DerivedProperty<T, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown>

Source Code¶

See the source for DerivedProperty.ts in the axon repository.