Skip to content

PhetioGroup

Overview

Provides a placeholder in the static API for where dynamic elements may be created. Checks that elements of the group match the approved schema.

In general when creating an element, any extra wiring or listeners should not be added. These side effects are a code smell in the createElement parameter. Instead attach a listener for when elements are created, and wire up listeners there. Further documentation about using PhetioGroup can be found at https://github.com/phetsims/phet-io/blob/main/doc/phet-io-instrumentation-technical-guide.md#dynamically-created-phet-io-elements

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

Class PhetioGroup

import { PhetioGroup } from 'scenerystack/tandem';

Constructor

new PhetioGroup( createElement : ( t: Tandem, ...p: P ) => T, defaultArguments : P | ( () => P ), providedOptions? : PhetioGroupOptions )

Instance Methods

dispose()

disposeElement( element : T )

Remove an element from this Group, unregistering it from PhET-iO and disposing it. The order is guaranteed to be: 1. remove from internal array 2. update countProperty 3. element.dispose 4. fire elementDisposedEmitter

@param element

getArray() : T[]

Gets a reference to the underlying array. DO NOT create/dispose elements while iterating, or otherwise modify the array. If you need to modify the array, use getArrayCopy.

getArrayCopy() : T[]

Gets a copy of the underlying array. Use this method if you need to create/dispose elements while iterating, or otherwise modify the group's array.

getElement( index : number ) : T

Returns the element at the specified index

getLastElement() : T

filter( predicate : ( t: T ) => boolean ) : T[]

Returns an array with elements that pass the filter predicate.

includes( element : T ) : boolean

Does the group include the specified element?

indexOf( element : T ) : number

Gets the index of the specified element in the underlying array.

forEach( action : ( t: T ) => void )

Runs the function on each element of the group.

find( predicate : ( t: T ) => boolean ) : T | undefined

Use the predicate to find the first matching occurrence in the array.

map( f : ( t: T ) => U ) : U[]

Returns an array with every element mapped to a new one.

clear( providedOptions? : PhetioGroupClearOptions )

Remove and dispose all registered group elements

createCorrespondingGroupElement( tandemName : string, ...argsForCreateFunction : P ) : T

When creating a view element that corresponds to a specific model element, we match the tandem name index suffix so that electron_0 corresponds to electronNode_0 and so on. @param tandemName - the tandem name of the model element @param argsForCreateFunction - args to be passed to the create function, specified there are in the IOType stateObjectToCreateElementArguments method

createNextElement( ...argsForCreateFunction : P ) : T

Creates the next group element. @param argsForCreateFunction - args to be passed to the create function, specified there are in the IOType stateObjectToCreateElementArguments method

createIndexedElement( index : number, argsForCreateFunction : P, fromStateSetting ) : T

Primarily for internal use, clients should usually use createNextElement. The order is guaranteed to be: 1. instantiate element 2. add to internal array 3. update countProperty 4. fire elementCreatedEmitter

@param index - the number of the individual element @param argsForCreateFunction @param [fromStateSetting] - Used for validation during state setting. (PhetioGroupIO)

Instance Properties

countProperty : NumberProperty

(readonly)

Static Properties

PhetioGroupIO

Parametric IOType constructor. Given an element type, this function returns a PhetioGroup IOType.

Type PhetioGroupOptions

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

Source Code

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