Tandem¶

Overview¶

Tandem defines a set of trees that are used to assign unique identifiers to PhetioObjects in PhET simulations and notify listeners when the associated PhetioObjects have been added/removed. It is used to support PhET-iO.

@author Sam Reid (PhET Interactive Simulations) @author Michael Kauzmann (PhET Interactive Simulations)

Class Tandem¶

import { Tandem } from 'scenerystack/tandem';

Constructor¶

new Tandem( parentTandem : Tandem | null, name : string, providedOptions? : TandemOptions )¶

Instance Methods¶

addPhetioObject( phetioObject : PhetioObject )¶

Adds a PhetioObject. For example, it could be an axon Property, SCENERY/Node or SUN/RoundPushButton. phetioEngine listens for when PhetioObjects are added and removed to keep track of them for PhET-iO.

hasAncestor( ancestor : Tandem ) : boolean¶

Returns true if this Tandem has the specified ancestor Tandem.

removePhetioObject( phetioObject : PhetioObject )¶

Removes a PhetioObject and signifies to listeners that it has been removed.

getExtendedOptions( options? : TandemOptions ) : TandemOptions¶

Used for creating new tandems, extends this Tandem's options with the passed-in options.

createTandem( name : string, options? : TandemOptions ) : Tandem¶

Create a new Tandem by appending the given id, or if the child Tandem already exists, return it instead.

createTandem1Indexed( name : string, index : number, options? : TandemOptions ) : Tandem¶

Create a new Tandem by indexing with the specified index. Note that it increments by 1 so that index 0 is "1" in the tandem name. For example: - createTandem( 'foo', 0 ) => 'foo1'

hasChild( name : string ) : boolean¶

addChild( name : string, tandem : Tandem )¶

iterateDescendants( callback : ( t: Tandem ) => void )¶

Fire a callback on all descendants of this Tandem

getArchetypalPhetioID() : PhetioID¶

For API validation, each PhetioObject has a corresponding archetype PhetioObject for comparison. Non-dynamic PhetioObjects have the trivial case where its archetypal phetioID is the same as its phetioID.

createGroupTandem( name : string ) : GroupTandem¶

Creates a group tandem for creating multiple indexed child tandems, such as: sim.screen.model.electron0 sim.screen.model.electron1

In this case, 'sim.screen.model.electron' is the string passed to createGroupTandem.

Used for arrays, observable arrays, or when many elements of the same type are created and they do not otherwise have unique identifiers.

equals( tandem : Tandem ) : boolean¶

createTandemFromPhetioID( phetioID : PhetioID ) : Tandem¶

Instance Properties¶

parentTandem : Tandem | null¶

Treat as readonly. Only marked as writable so it can be eliminated on dispose

name : string¶

(readonly)

the last part of the tandem (after the last .), used e.g., in Joist for creating button names dynamically based on screen names

phetioID : PhetioID¶

(readonly)

children : Record<string, Tandem>¶

(readonly)

phet-io internal, please don't use this. Please.

required : boolean¶

(readonly)

supplied : boolean¶

(readonly)

Static Methods¶

getRegexFromCharacterClass( tandemCharacterClass : string ) : RegExp¶

(protected)

Get the regex to test for a valid tandem name, given the char class for your specific tandem. In the regex language. In this function we will wrap it in []+ brackets forming the actual "class".

onMissingTandem( tandem : Tandem )¶

If the provided tandem is not supplied, support the ?printMissingTandems query parameter for extra logging during initial instrumentation.

addPhetioObjectListener( phetioObjectListener : PhetioObjectListener )¶

Adds a listener that will be notified when items are registered/deregistered

launch()¶

After all listeners have been added, then Tandem can be launched. This registers all of the buffered PhetioObjects and subsequent PhetioObjects will be registered directly.

unlaunch()¶

ONLY FOR TESTING!!!! This was created to "undo" launch so that tests can better expose cases around calling Tandem.launch()

addLaunchListener( listener : () => void )¶

Add a listener that will fire when Tandem is launched

getStringsTandem( moduleName : string ) : Tandem¶

Get the Tandem location for model strings. Provide the camelCased repo name for where the string should be organized. This will default to the sim's name. See https://github.com/phetsims/tandem/issues/298

getDerivedStringsTandem( moduleName : string ) : Tandem¶

Get the Tandem location for derived model strings. Provide the camelCased repo name for where the string should be organized. This will default to the sim's name. See https://github.com/phetsims/tandem/issues/298

Static Properties¶

SCREEN_TANDEM_NAME_SUFFIX¶

(readonly)

missingTandems¶

(readonly)

Expose collected missing tandems only populated from specific query parameter, see phetioPrintMissingTandems (phet-io internal)

PHET_IO_ENABLED¶

(readonly)

If PhET-iO is enabled in this runtime.

VALIDATION¶

(readonly)

If PhET-iO is running with validation enabled.

apiValidationEnabled¶

If phetioAPIValidation is enabled, this is mostly just readonly, except some internal logic for phet-io startup and qunit testing

METADATA_KEY¶

(readonly)

For the API file, the key name for the metadata section.

DATA_KEY¶

(readonly)

For the API file, the key name for the data section.

launched¶

Before listeners are wired up, tandems are buffered. When listeners are wired up, Tandem.launch() is called and buffered tandems are flushed, then subsequent tandems are delivered to listeners directly

bufferedPhetioObjects : PhetioObject[]¶

(readonly)

a list of PhetioObjects ready to be sent out to listeners, but can't because Tandem hasn't been launched yet.

ROOT : Tandem¶

(readonly)

The root tandem for a simulation

ROOT_TEST¶

(readonly)

Used in unit tests

GENERAL_MODEL¶

(readonly)

Tandem for model simulation elements that are general to all sims.

GENERAL_VIEW¶

(readonly)

Tandem for view simulation elements that are general to all sims.

GENERAL_CONTROLLER¶

(readonly)

Tandem for controller simulation elements that are general to all sims.

GLOBAL_MODEL¶

(readonly)

Model simulation elements that don't belong in specific screens should be nested under this Tandem. Note that this tandem should only have simulation specific elements in them.

GLOBAL_VIEW¶

(readonly)

View simulation elements that don't belong in specific screens should be nested under this Tandem. Note that this tandem should only have simulation specific elements in them.

COLORS¶

(readonly)

Colors used in the simulation.

STRINGS¶

(readonly)

Colors used in the simulation.

OPTIONAL¶

(readonly)

In TypeScript, optionize already knows that tandem may be undefined, just use options.tandem? See https://github.com/phetsims/tandem/issues/289 Used to indicate a common code component that supports tandem, but doesn't require it. If a tandem is not passed in, then it will not be instrumented.

OPT_OUT¶

(readonly)

To be used exclusively to opt out of situations where a tandem is required, see https://github.com/phetsims/tandem/issues/97.

REQUIRED¶

(readonly)

Some common code (such as Checkbox or RadioButton) must always be instrumented.

PREFERENCES¶

(readonly)

Use this as the parent tandem for Properties that are related to sim-specific preferences.

Type TandemOptions¶

import type { TandemOptions } from 'scenerystack/tandem';

• required?: boolean
• supplied?: boolean
• isValidTandemName?: ( name: string ) => boolean

Source Code¶

See the source for Tandem.ts in the tandem repository.