Skip to content

PhetioCapsule

Overview

A PhET-iO class that encapsulates a PhetioObject that is not created during sim startup to provide PhET-iO API validation, API communication (like to view in studio before creation), and to support PhET-iO state if applicable.

Constructing a PhetioCapsule creates a container encapsulating a wrapped element that can be of any type.

Clients should use myCapsule.getElement() instead of storing the element value itself.

NOTE: Be careful about treating the dynamic element as a singleton. When creating the archetype, problems can arise because the capsule creates two instances of the element: one as the archetype and one as the instance. This can result in trouble like in https://github.com/phetsims/joist/issues/821.

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

Class PhetioCapsule

import { PhetioCapsule } from 'scenerystack/tandem';

Constructor

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

Instance Methods

disposeElement()

Dispose the underlying element. Called by the PhetioStateEngine so the capsule element can be recreated with the correct state.

hasElement() : boolean

getElement( ...argsForCreateFunction : P ) : T

Creates the element if it has not been created yet, and returns it.

clear( providedOptions? : ClearOptions )

PhetioCapsule will dispose its element, clearing things up and getting ready for setState, unless this.disposeOnClear opts out of this behavior, in which case the element should fully support mutating itself during state setting.

create( argsForCreateFunction : P, fromStateSetting ) : T

Primarily for internal use, clients should usually use getElement(). @param argsForCreateFunction @param [fromStateSetting] - used for validation during state setting, see PhetioDynamicElementContainer.disposeElement() for documentation (phet-io)

Static Properties

PhetioCapsuleIO

Parametric IOType constructor. Given an element type, this function returns a PhetioCapsule IOType. This caching implementation should be kept in sync with the other parametric IOType caching implementations. @param parameterType @constructor

Type PhetioCapsuleOptions

The container suffix has to be "Capsule" or we need to change some logic in PhetioIDUtils.getArchetypalPhetioID

import type { PhetioCapsuleOptions } from 'scenerystack/tandem';
  • disposeOnClear?: boolean
    Some elements like AboutDialog and PreferencesDialog persist for the lifetime of the sim, and once created are never disposed. This allows us to avoid extensive unnecessary work implementing dispose for these elements. If true, dispose the element when cleared. If set to false, clear() will basically be a no-op, which can be useful if you want to support lazy creation, but if this is not a true "dynamic element". This will also cause an assertion if ever trying to call disposeElement on this. https://github.com/phetsims/phet-io/issues/1810
  • disposeCreatedOnStateSet?: boolean
    Only applicable if disposing during clear. This is an optimization to prevent the need to recreate the element each time PhET-iO state is set. Defaults to false. This should only be true if your dynamic element can be mutated with state, and doesn't need construction to be run during state set. This should be set to true when supporting heterogeneous capsules. https://github.com/phetsims/phet-io/issues/1810
  • & StrictOmit<PhetioDynamicElementContainerOptions, "containerSuffix">

Source Code

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