Skip to content

PhetioDynamicElementContainer

Overview

Supertype for containers that hold dynamic elements that are PhET-iO instrumented. This type handles common features like creating the archetype for the PhET-iO API, and managing created/disposed data stream events.

"Dynamic" is an overloaded term, so allow me to explain what it means in the context of this type. A "dynamic element" is an instrumented PhET-iO Element that is conditionally in the PhET-iO API. Most commonly this is because elements can be created and destroyed during the runtime of the sim. Another "dynamic element" for the PhET-iO project is when an element may or may not be created based on a query parameter. In this case, even if the object then exists for the lifetime of the sim, we may still call this "dynamic" as it pertains to this type, and the PhET-iO API.

@author Michael Kauzmann (PhET Interactive Simulations)

Class PhetioDynamicElementContainer

import { PhetioDynamicElementContainer } from 'scenerystack/tandem';

Constructor

new PhetioDynamicElementContainer( createElement : ( t: Tandem, ...args: CreateElementArguments ) => T, defaultArguments : CreateElementArguments | ( () => CreateElementArguments ), providedOptions? : PhetioDynamicElementContainerOptions )

Instance Methods

createArchetype( archetypeTandem, createElementArgs : ( CreateElementArguments | ( () => CreateElementArguments ) ) ) : T | null

Archetypes are created to generate the baseline file, or to validate against an existing baseline file. They are PhetioObjects and registered with the phetioEngine, but not send out via notifications from PhetioEngine.phetioElementAddedEmitter(), because they are intended for internal usage only. Archetypes should not be created in production code.

PhetioDynamicElementContainer calls this method internally to create and assign its own archetype, but this method can additionally be called with alternate archetypeTandem and/or createElementArgs to create alternate archetypes. This can be necessary in situations that require archetypes provided to other archetypes, or with other forms of dependency injection, such as in https://github.com/phetsims/tandem/issues/312

createDynamicElement( componentName : string, argsForCreateFunction : CreateElementArguments, containerParameterType : IOType | null ) : T

Create a dynamic PhetioObject element for this container @param componentName @param argsForCreateFunction @param containerParameterType - null in PhET brand

dispose()

disposeElement( element : T )

(protected)

Dispose a contained element

clear( clearOptions? : ClearOptions )

Called when clearing the contents of this container to ready things for setting its state. In general, this class is set up to destroy and then recreate all of its elements instead of mutating them.

notifyElementCreated( createdElement : T )

(protected)

Should be called by subtypes upon element creation, see PhetioGroup as an example.

notifyElementCreatedWhileDeferred( createdElement : T )

Flush a single element from the list of deferred creations that have not yet notified about the disposal. This is only public to support specific order dependencies in the PhetioStateEngine, otherwise see this.notifyElementCreated() (PhetioGroupTests, phet-io) - only the PhetioStateEngine should notify individual elements created.

setNotificationsDeferred( notificationsDeferred : boolean )

When set to true, creation and disposal notifications will be deferred until set to false. When set to false, this function will flush all the notifications for created and disposed elements (in that order) that occurred while this container was deferring its notifications.

getMetadata( object : PhetioObjectMetadataInput ) : PhetioElementMetadata

Add the phetioDynamicElementName for API tracking

Instance Properties

elementCreatedEmitter : TEmitter<[ T, string ]>

(readonly)

elementDisposedEmitter : TEmitter<[ T, string ]>

(readonly)

supportsDynamicState : boolean

(readonly)

phetioDynamicElementName : string

(protected)

createElement : ( t: Tandem, ...args: CreateElementArguments ) => T

(protected)

defaultArguments : CreateElementArguments | ( () => CreateElementArguments )

(protected)

Arguments passed to the archetype when creating it.

Type ClearOptions

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

Type PhetioDynamicElementContainerOptions

import type { PhetioDynamicElementContainerOptions } from 'scenerystack/tandem';
  • supportsDynamicState?: boolean
    By default, a PhetioDynamicElementContainer's elements are included in state such that on every setState call, the elements are cleared out by the phetioStateEngine so elements in the state can be added to the empty group. This option is for opting out of that behavior. When false, this container will not have its elements cleared when beginning to set PhET-iO state. Furthermore, view elements following the "only the models are stateful" pattern must mark this as false, otherwise the state engine will try to create these elements instead of letting the model notifications handle this.
  • containerSuffix?: string
    The container's tandem name must have this suffix, and the base tandem name for elements in the container will consist of the group's tandem name with this suffix stripped off.
  • phetioDynamicElementName?: string
    tandem name for elements in the container is the container's tandem name without containerSuffix
  • & StrictOmit<PhetioObjectOptions, "phetioDynamicElement"> & PickRequired<PhetioObjectOptions, "phetioType">

Source Code

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