Skip to content

ReadOnlyProperty

Overview

An observable property which notifies listeners when the value changes.

@author Sam Reid (PhET Interactive Simulations) @author Chris Malley (PixelZoom, Inc.)

Class ReadOnlyProperty

Base class for Property, DerivedProperty, DynamicProperty. Set methods are protected/not part of the public interface. Initial value and resetting is not defined here.

import { ReadOnlyProperty } from 'scenerystack/axon';

Constructor

new ReadOnlyProperty( value : T, providedOptions? : PropertyOptions<T> )

Instance Methods

isSettable() : boolean

Returns true if the value can be set externally, using .value= or set()

get() : T

Gets the value. You can also use the es5 getter (property.value) but this means is provided for inner loops or internal code that must be fast.

set( value : T )

(protected)

Sets the value and notifies listeners, unless deferred or disposed. You can also use the es5 getter (property.value) but this means is provided for inner loops or internal code that must be fast. If the value hasn't changed, this is a no-op.

NOTE: For PhET-iO instrumented Properties that are phetioState: true, the value is only set by the PhetioStateEngine and cannot be modified by other code while isSettingPhetioStateProperty === true.

unguardedSet( value : T )

(protected)

For usage by the IOType during PhET-iO state setting.

setPropertyValue( value : T )

(protected)

Sets the value without notifying any listeners. This is a place to override if a subtype performs additional work when setting the value.

equalsValue( value : T ) : boolean

(protected)

Returns true if and only if the specified value equals the value of this property

areValuesEqual( a : T, b : T ) : boolean

Determine if the two values are equal, see TinyProperty.areValuesEqual().

notifyListenersStatic()

Use this method when mutating a value (not replacing with a new instance) and you want to send notifications about the change. This is different from the normal axon strategy, but may be necessary to prevent memory allocations. This method is unsafe for removing listeners because it assumes the listener list not modified, to save another allocation Only provides the new reference as a callback (no oldValue) See https://github.com/phetsims/axon/issues/6

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

When deferred, set values do not take effect or send out notifications. After defer ends, the Property takes its deferred value (if any), and a follow-up action (return value) can be invoked to send out notifications once other Properties have also taken their deferred values.

@param isDeferred - whether the Property should be deferred or not @returns - function to notify listeners after calling setDeferred(false), - null if isDeferred is true, or if the value is unchanged since calling setDeferred(true)

addPhetioStateDependencies( dependencies : Array<TReadOnlyProperty<IntentionalAny>> )

This function registers an order dependency between this Property and another. Basically this says that when setting PhET-iO state, each dependency must take its final value before this Property fires its notifications. See propertyStateHandlerSingleton.registerPhetioOrderDependency and https://github.com/phetsims/axon/issues/276 for more info.

Adds listener and calls it immediately. If listener is already registered, this is a no-op. The initial notification provides the current value for newValue and null for oldValue.

@param listener - a function that takes a new value, old value, and this Property as arguments @param [options]

Add a listener to the Property, without calling it back right away. This is used when you need to register a listener without an immediate callback.

Removes a listener. If listener is not registered, this is a no-op.

unlinkAll()

Removes all listeners. If no listeners are registered, this is a no-op.

linkAttribute( object : IntentionalAny, attributeName : string ) : ( value: T ) => void

Links an object's named attribute to this property. Returns a handle so it can be removed using Property.unlink(); Example: modelVisibleProperty.linkAttribute(view,'visible');

NOTE: Duplicated with TinyProperty.linkAttribute

toString() : string

Provide toString for console debugging, see http://stackoverflow.com/questions/2485632/valueof-vs-tostring-in-javascript

debug( name : string ) : ( value: T ) => void

Convenience function for debugging a Property's value. It prints the new value on registration and when changed. @param name - debug name to be printed on the console @returns - the handle to the linked listener in case it needs to be removed later

isValueValid( value : T ) : boolean

getValidationError( value : T ) : string | null

dispose()

Ensures that the Property is eligible for GC

hasListener( listener : PropertyLinkListener<T> ) : boolean

Checks whether a listener is registered with this Property

forEachListener( callback : ( value: ( ...args: [ T, T | null, TinyProperty<T> | ReadOnlyProperty<T> ] ) => void ) => void )

Invokes a callback once for each listener @param callback - takes the listener as an argument

hasListeners() : boolean

Returns true if there are any listeners.

toStateObject() : ReadOnlyPropertyState<StateType>

(protected)

Implementation of serialization for PhET-iO support. Override this function to customize how this state behaves (but be careful!).

This function is parameterized to support subtyping. That said, it is a bit useless, since we don't want to parameterize ReadOnlyProperty in general to the IOType's state type, so please bear with us.

applyState( stateObject : ReadOnlyPropertyState<StateType> )

(protected)

Implementation of serialization for PhET-iO support. Override this function to customize how this state behaves (but be careful!).

getPhetioMouseHitTarget( fromLinking ) : PhetioObject | 'phetioNotSelectable'

Support treating ourselves as an autoselectable entity for the "strings" selection mode.

Instance Properties

units : Units | null

(readonly)

(phet-io) Units, if any. See units.js for valid values

validValues : readonly T[]

(readonly)

isDeferred : boolean

while deferred, new values neither take effect nor send notifications. When isDeferred changes from true to false, the final deferred value becomes the Property value. An action is created which can be invoked to send notifications.

deferredValue : T | null

(protected)

the value that this Property will take after no longer deferred

hasDeferredValue : boolean

(protected)

whether a deferred value has been set

valueValidator : Validator<T>

(protected, readonly)

phetioValueType : IOType

(protected, readonly)

The IOType for the values this Property supports.

Static Methods

PropertyIO( parameterType : IOType<T, StateType> ) : IOType

An observable Property that triggers notifications when the value changes. This caching implementation should be kept in sync with the other parametric IOType caching implementations.

Static Properties

CHANGED_EVENT_NAME

(readonly)

Type LinkOptions

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

Type ReadOnlyPropertyOptions

Options that can be passed in

import type { ReadOnlyPropertyOptions } from 'scenerystack/axon';
  • units?: Units | null
    units for the value, see units.js. Should prefer abbreviated units, see https://github.com/phetsims/phet-io/issues/530
  • reentrant?: boolean
    Whether reentrant calls to 'set' are allowed. Use this to detect or prevent update cycles. Update cycles may be due to floating point error, faulty logic, etc. This may be of particular interest for PhET-iO instrumentation, where such cycles may pollute the data stream. See https://github.com/phetsims/axon/issues/179
  • phetioValueType?: IOType
    The IOType for the values this Property supports. At this level, it doesn't matter what the state type is, so it defaults to IntentionalAny.
  • phetioOuterType?: ( parameterType: IOType ) => IOType
    The IOType function that returns a parameterized IOType based on the valueType. There is a general default, but subtypes can implement their own, more specific IOType.
  • hasListenerOrderDependencies?: boolean
    If specified as true, this flag will ensure that listener order never changes (like via ?listenerOrder=random)
  • & Pick<TinyEmitterOptions, "reentrantNotificationStrategy"> & StrictOmit<ParentOptions<T>, "phetioType">

Type ReadOnlyPropertyState

import type { ReadOnlyPropertyState } from 'scenerystack/axon';
  • value: StateType
  • validValues: StateType[] | null
    Only include validValues if specified, so they only show up in PhET-iO Studio when supplied.
  • units: string | null

Source Code

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