Node¶

Overview¶

A Node for the Scenery scene graph. Supports general directed acyclic graphics (DAGs). Handles multiple layers with assorted types (Canvas 2D, SVG, DOM, WebGL, etc.).

General description of Nodes¶

In Scenery, the visual output is determined by a group of connected Nodes (generally known as a scene graph). Each Node has a list of 'child' Nodes. When a Node is visually displayed, its child Nodes (children) will also be displayed, along with their children, etc. There is typically one 'root' Node that is passed to the Scenery Display whose descendants (Nodes that can be traced from the root by child relationships) will be displayed.

For instance, say there are Nodes named A, B, C, D and E, who have the relationships: - B is a child of A (thus A is a parent of B) - C is a child of A (thus A is a parent of C) - D is a child of C (thus C is a parent of D) - E is a child of C (thus C is a parent of E) where A would be the root Node. This can be visually represented as a scene graph, where a line connects a parent Node to a child Node (where the parent is usually always at the top of the line, and the child is at the bottom): For example:

A / \ B C / \ D E

Additionally, in this case: - D is a 'descendant' of A (due to the C being a child of A, and D being a child of C) - A is an 'ancestor' of D (due to the reverse) - C's 'subtree' is C, D and E, which consists of C itself and all of its descendants.

Note that Scenery allows some more complicated forms, where Nodes can have multiple parents, e.g.:

A / \ B C / D

In this case, D has two parents (B and C). Scenery disallows any Node from being its own ancestor or descendant, so that loops are not possible. When a Node has two or more parents, it means that the Node's subtree will typically be displayed twice on the screen. In the above case, D would appear both at B's position and C's position. Each place a Node would be displayed is known as an 'instance'.

Each Node has a 'transform' associated with it, which determines how its subtree (that Node and all of its descendants) will be positioned. Transforms can contain: - Translation, which moves the position the subtree is displayed - Scale, which makes the displayed subtree larger or smaller - Rotation, which displays the subtree at an angle - or any combination of the above that uses an affine matrix (more advanced transforms with shear and combinations are possible).

Say we have the following scene graph:

A | B | C

where there are the following transforms: - A has a 'translation' that moves the content 100 pixels to the right - B has a 'scale' that doubles the size of the content - C has a 'rotation' that rotates 180-degrees around the origin

If C displays a square that fills the area with 0 <= x <= 10 and 0 <= y <= 10, we can determine the position on the display by applying transforms starting at C and moving towards the root Node (in this case, A): 1. We apply C's rotation to our square, so the filled area will now be -10 <= x <= 0 and -10 <= y <= 0 2. We apply B's scale to our square, so now we have -20 <= x <= 0 and -20 <= y <= 0 3. We apply A's translation to our square, moving it to 80 <= x <= 100 and -20 <= y <= 0

Nodes also have a large number of properties that will affect how their entire subtree is rendered, such as visibility, opacity, etc.

Creating Nodes¶

Generally, there are two types of Nodes: - Nodes that don't display anything, but serve as a container for other Nodes (e.g. Node itself, HBox, VBox) - Nodes that display content, but ALSO serve as a container (e.g. Circle, Image, Text)

When a Node is created with the default Node constructor, e.g.: var node = new Node(); then that Node will not display anything by itself.

Generally subtypes of Node are used for displaying things, such as Circle, e.g.: var circle = new Circle( 20 ); // radius of 20

Almost all Nodes (with the exception of leaf-only Nodes like Spacer) can contain children.

Connecting Nodes, and rendering order¶

To make a 'childNode' become a 'parentNode', the typical way is to call addChild(): parentNode.addChild( childNode );

To remove this connection, you can call: parentNode.removeChild( childNode );

Adding a child Node with addChild() puts it at the end of parentNode's list of child Nodes. This is important, because the order of children affects what Nodes are drawn on the 'top' or 'bottom' visually. Nodes that are at the end of the list of children are generally drawn on top.

This is generally easiest to represent by notating scene graphs with children in order from left to right, thus:

A / \ B C / \ D E

would indicate that A's children are [B,C], so C's subtree is drawn ON TOP of B. The same is true of C's children [D,E], so E is drawn on top of D. If a Node itself has content, it is drawn below that of its children (so C itself would be below D and E).

This means that for every scene graph, Nodes instances can be ordered from bottom to top. For the above example, the order is: 1. A (on the very bottom visually, may get covered up by other Nodes) 2. B 3. C 4. D 5. E (on the very top visually, may be covering other Nodes)

Trails¶

For examples where there are multiple parents for some Nodes (also referred to as DAG in some code, as it represents a Directed Acyclic Graph), we need more information about the rendering order (as otherwise Nodes could appear multiple places in the visual bottom-to-top order.

A Trail is basically a list of Nodes, where every Node in the list is a child of its previous element, and a parent of its next element. Thus for the scene graph:

A / \ B C / \ D E / F

there are actually three instances of F being displayed, with three trails: - [A,B,D,F] - [A,C,D,F] - [A,C,E,F] Note that the trails are essentially listing Nodes used in walking from the root (A) to the relevant Node (F) using connections between parents and children.

The trails above are in order from bottom to top (visually), due to the order of children. Thus since A's children are [B,C] in that order, F with the trail [A,B,D,F] is displayed below [A,C,D,F], because C is after B.

@author Jonathan Olson <jonathan.olson@colorado.edu>

Class Node¶

import { Node } from 'scenerystack/scenery';

Constructor¶

new Node( options? : NodeOptions )¶

Instance Methods¶

moveChildToIndex( node : Node, index : number ) : this¶

If a child is not at the given index, it is moved to the given index. This reorders the children of this Node so that this.children[ index ] === node.

@param node - The child Node to move in the order @param index - The desired index (into the children array) of the child.

removeAllChildren() : this¶

Removes all children from this Node.

setChildren( children : Node[] ) : this¶

Sets the children of the Node to be equivalent to the passed-in array of Nodes.

NOTE: Meant to be overridden in some cases

getChildren() : Node[]¶

Returns a defensive copy of the array of direct children of this node, ordered by what is in front (nodes at the end of the array are in front of nodes at the start).

Making changes to the returned result will not affect this node's children.

getChildrenCount() : number¶

Returns a count of children, without needing to make a defensive copy.

getParents() : Node[]¶

Returns a defensive copy of our parents. This is an array of parent nodes that is returned in no particular order (as order is not important here).

NOTE: Modifying the returned array will not in any way modify this node's parents.

getParent() : Node | null¶

Returns a single parent if it exists, otherwise null (no parents), or an assertion failure (multiple parents).

getChildAt( index : number ) : Node¶

Gets the child at a specific index into the children array.

indexOfParent( parent : Node ) : number¶

Finds the index of a parent Node in the parents array.

@param parent - Should be a parent of this node. @returns - An index such that this.parents[ index ] === parent

indexOfChild( child : Node ) : number¶

Finds the index of a child Node in the children array.

@param child - Should be a child of this node. @returns - An index such that this.children[ index ] === child

moveToFront() : this¶

Moves this Node to the front (end) of all of its parents children array.

moveChildToFront( child : Node ) : this¶

Moves one of our children to the front (end) of our children array.

@param child - Our child to move to the front.

moveForward() : this¶

Move this node one index forward in each of its parents. If the Node is already at the front, this is a no-op.

moveChildForward( child : Node ) : this¶

Moves the specified child forward by one index. If the child is already at the front, this is a no-op.

moveBackward() : this¶

Move this node one index backward in each of its parents. If the Node is already at the back, this is a no-op.

moveChildBackward( child : Node ) : this¶

Moves the specified child forward by one index. If the child is already at the back, this is a no-op.

moveToBack() : this¶

Moves this Node to the back (front) of all of its parents children array.

moveChildToBack( child : Node ) : this¶

Moves one of our children to the back (front) of our children array.

@param child - Our child to move to the back.

replaceChild( oldChild : Node, newChild : Node ) : this¶

Replace a child in this node's children array with another node. If the old child had DOM focus and the new child is focusable, the new child will receive focus after it is added.

detach() : this¶

Removes this Node from all of its parents.

validateSelfBounds() : boolean¶

Ensures that the cached selfBounds of this Node is accurate. Returns true if any sort of dirty flag was set before this was called.

@returns - Was the self-bounds potentially updated?

validateBounds() : boolean¶

Ensures that cached bounds stored on this Node (and all children) are accurate. Returns true if any sort of dirty flag was set before this was called.

@returns - Was something potentially updated?

invalidateBounds()¶

Marks the bounds of this Node as invalid, so they are recomputed before being accessed again.

invalidateSelf( newSelfBounds? : Bounds2 )¶

Should be called to notify that our selfBounds needs to change to this new value.

updateSelfBounds() : boolean¶

(protected)

Meant to be overridden by Node sub-types to compute self bounds (if invalidateSelf() with no arguments was called).

@returns - Whether the self bounds changed.

hasChild( potentialChild : Node ) : boolean¶

Returns whether a Node is a child of this node.

@returns - Whether potentialChild is actually our child.

getSelfShape() : Shape¶

Returns a Shape that represents the area covered by containsPointSelf.

getSelfBounds() : Bounds2¶

Returns our selfBounds (the bounds for this Node's content in the local coordinates, excluding anything from our children and descendants).

NOTE: Do NOT mutate the returned value!

getSafeSelfBounds() : Bounds2¶

Returns a bounding box that should contain all self content in the local coordinate frame (our normal self bounds aren't guaranteed this for Text, etc.)

Override this to provide different behavior.

getChildBounds() : Bounds2¶

Returns the bounding box that should contain all content of our children in our local coordinate frame. Does not include our "self" bounds.

NOTE: Do NOT mutate the returned value!

getLocalBounds() : Bounds2¶

Returns the bounding box that should contain all content of our children AND our self in our local coordinate frame.

NOTE: Do NOT mutate the returned value!

setLocalBounds( localBounds : Bounds2 | null ) : this¶

Allows overriding the value of localBounds (and thus changing things like 'bounds' that depend on localBounds). If it's set to a non-null value, that value will always be used for localBounds until this function is called again. To revert to having Scenery compute the localBounds, set this to null. The bounds should not be reduced smaller than the visible bounds on the screen.

getTransformedSelfBounds( matrix : Matrix3 ) : Bounds2¶

Meant to be overridden in sub-types that have more accurate bounds determination for when we are transformed. Usually rotation is significant here, so that transformed bounds for non-rectangular shapes will be different.

getTransformedSafeSelfBounds( matrix : Matrix3 ) : Bounds2¶

Meant to be overridden in sub-types that have more accurate bounds determination for when we are transformed. Usually rotation is significant here, so that transformed bounds for non-rectangular shapes will be different.

This should include the "full" bounds that guarantee everything rendered should be inside (e.g. Text, where the normal bounds may not be sufficient).

getSafeTransformedVisibleBounds( matrix? : Matrix3 ) : Bounds2¶

Returns the visual "safe" bounds that are taken up by this Node and its subtree. Notably, this is essentially the combined effects of the "visible" bounds (i.e. invisible nodes do not contribute to bounds), and "safe" bounds (e.g. Text, where we need a larger bounds area to guarantee there is nothing outside). It also tries to "fit" transformed bounds more tightly, where it will handle rotated Path bounds in an improved way.

NOTE: This method is not optimized, and may create garbage and not be the fastest.

@param [matrix] - If provided, will return the bounds assuming the content is transformed with the given matrix.

setTransformBounds( transformBounds : boolean ) : this¶

Sets the flag that determines whether we will require more accurate (and expensive) bounds computation for this node's transform.

If set to false (default), Scenery will get the bounds of content, and then if rotated will determine the on-axis bounds that completely cover the rotated bounds (potentially larger than actual content). If set to true, Scenery will try to get the bounds of the actual rotated/transformed content.

A good example of when this is necessary is if there are a bunch of nested children that each have pi/4 rotations.

@param transformBounds - Whether accurate transform bounds should be used.

getTransformBounds() : boolean¶

Returns whether accurate transformation bounds are used in bounds computation (see setTransformBounds).

getBounds() : Bounds2¶

Returns the bounding box of this Node and all of its sub-trees (in the "parent" coordinate frame).

NOTE: Do NOT mutate the returned value! NOTE: This may require computation of this node's subtree bounds, which may incur some performance loss.

getVisibleLocalBounds() : Bounds2¶

Like getLocalBounds() in the "local" coordinate frame, but includes only visible nodes.

getVisibleBounds() : Bounds2¶

Like getBounds() in the "parent" coordinate frame, but includes only visible nodes

hitTest( point : Vector2, isMouse? : boolean, isTouch? : boolean ) : Trail | null¶

Tests whether the given point is "contained" in this node's subtree (optionally using mouse/touch areas), and if so returns the Trail (rooted at this node) to the top-most (in stacking order) Node that contains the given point.

NOTE: This is optimized for the current input system (rather than what gets visually displayed on the screen), so pickability (Node's pickable property, visibility, and the presence of input listeners) all may affect the returned value.

For example, hit-testing a simple shape (with no pickability) will return null: > new phet.scenery.Circle( 20 ).hitTest( phet.dot.v2( 0, 0 ) ); // null

If the same shape is made to be pickable, it will return a trail: > new phet.scenery.Circle( 20, { pickable: true } ).hitTest( phet.dot.v2( 0, 0 ) ); > // returns a Trail with the circle as the only node.

It will return the result that is visually stacked on top, so e.g.: > new phet.scenery.Node( { > pickable: true, > children: [ > new phet.scenery.Circle( 20 ), > new phet.scenery.Circle( 15 ) > ] > } ).hitTest( phet.dot.v2( 0, 0 ) ); // returns the "top-most" circle (the one with radius:15).

This is used by Scenery's internal input system by calling hitTest on a Display's rootNode with the global-coordinate point.

@param point - The point (in the parent coordinate frame) to check against this node's subtree. @param [isMouse] - Whether mouseAreas should be used. @param [isTouch] - Whether touchAreas should be used. @returns - Returns null if the point is not contained in the subtree.

trailUnderPointer( pointer : Pointer ) : Trail | null¶

Hit-tests what is under the pointer, and returns a {Trail} to that Node (or null if there is no matching node).

See hitTest() for more details about what will be returned.

containsPoint( point : Vector2 ) : boolean¶

Returns whether a point (in parent coordinates) is contained in this node's sub-tree.

See hitTest() for more details about what will be returned.

@returns - Whether the point is contained.

containsPointSelf( point : Vector2 ) : boolean¶

Override this for computation of whether a point is inside our self content (defaults to selfBounds check).

@param point - Considered to be in the local coordinate frame

intersectsBoundsSelf( bounds : Bounds2 ) : boolean¶

Returns whether this node's selfBounds is intersected by the specified bounds.

@param bounds - Bounds to test, assumed to be in the local coordinate frame.

isPhetioMouseHittable( point : Vector2 ) : boolean¶

Determine if the Node is a candidate for phet-io autoselect. 1. Invisible things cannot be autoselected 2. Transform the point in the local coordinate frame, so we can test it with the clipArea/children 3. If our point is outside the local-coordinate clipping area, there should be no hit. 4. Note that non-pickable nodes can still be autoselected

isAnyDescendantAPhetioMouseHitTarget() : boolean¶

If you need to know if any Node in a subtree could possibly be a phetio mouse hit target. SR and MK ran performance on this function in CCK:DC and CAV in 6/2023 and there was no noticeable problem.

getPhetioMouseHit( point : Vector2 ) : PhetioObject | null | 'phetioNotSelectable'¶

Used in Studio Autoselect. Returns a PhET-iO Element (a PhetioObject) if possible, or null if no hit. "phetioNotSelectable" is an intermediate state used to note when a "hit" has occurred, but the hit was on a Node that didn't have a fit target (see PhetioObject.getPhetioMouseHitTarget()) A few notes on the implementation: 1. Prefer the leaf most Node that is at the highest z-index in rendering order 2. Pickable:false Nodes don't prune out subtrees if descendents could still be mouse hit targets (see PhetioObject.getPhetioMouseHitTarget()). 3. First the algorithm finds a Node that is a "hit", and then it tries to find the most fit "target" for that hit. a. Itself, see PhetioObject.getPhetioMouseHitTarget() b. A class defined substitute, Text.getPhetioMouseHitTarget() c. A sibling that is rendered behind the hit d. The most recent descendant that is a usable target.

Adapted originally from Picker.recursiveHitTest, with specific tweaks needed for PhET-iO instrumentation, display and filtering. @returns - null if no hit occurred - A PhetioObject if a hit occurred on a Node with a selectable target - 'phetioNotSelectable' if a hit occurred, but no suitable target was found from that hit (see PhetioObject.getPhetioMouseHitTarget())

isPainted() : boolean¶

Whether this Node itself is painted (displays something itself). Meant to be overridden.

areSelfBoundsValid() : boolean¶

Whether this Node's selfBounds are considered to be valid (always containing the displayed self content of this node). Meant to be overridden in subtypes when this can change (e.g. Text).

If this value would potentially change, please trigger the event 'selfBoundsValid'.

hasParent() : boolean¶

Returns whether this Node has any parents at all.

hasChildren() : boolean¶

Returns whether this Node has any children at all.

isChildIncludedInLayout( child : Node ) : boolean¶

Returns whether a child should be included for layout (if this Node is a layout container).

walkDepthFirst( callback : ( node: Node ) => void )¶

Calls the callback on nodes recursively in a depth-first manner.

addInputListener( listener : TInputListener, options? : DisposerOptions ) : this¶

Adds an input listener.

See Input.js documentation for information about how event listeners are used.

Additionally, the following fields are supported on a listener:

• interrupt {function()}: When a pointer is interrupted, it will attempt to call this method on the input listener
• cursor {string|null}: If node.cursor is null, any non-null cursor of an input listener will effectively "override" it. NOTE: this can be implemented as an es5 getter, if the cursor can change

removeInputListener( listener : TInputListener ) : this¶

Removes an input listener that was previously added with addInputListener.

hasInputListener( listener : TInputListener ) : boolean¶

Returns whether this input listener is currently listening to this node.

More efficient than checking node.inputListeners, as that includes a defensive copy.

interruptInput() : this¶

Interrupts all input listeners that are attached to this node.

interruptSubtreeInput() : this¶

Interrupts all input listeners that are attached to either this node, or a descendant node.

translate( v : Vector2, prependInstead? : boolean )¶

Changes the transform of this Node by adding a transform. The default "appends" the transform, so that it will appear to happen to the Node before the rest of the transform would apply, but if "prepended", the rest of the transform would apply first.

As an example, if a Node is centered at (0,0) and scaled by 2: translate( 100, 0 ) would cause the center of the Node (in the parent coordinate frame) to be at (200,0). translate( 100, 0, true ) would cause the center of the Node (in the parent coordinate frame) to be at (100,0).

Allowed call signatures: translate( x {number}, y {number} ) translate( x {number}, y {number}, prependInstead {boolean} ) translate( vector {Vector2} ) translate( vector {Vector2}, prependInstead {boolean} )

@param x - The x coordinate @param y - The y coordinate @param [prependInstead] - Whether the transform should be prepended (defaults to false)

translate( x : number, y : number, prependInstead? : boolean )¶

translate( x : number | Vector2, y? : number | boolean, prependInstead? : boolean )¶

scale( s : number, prependInstead? : boolean )¶

Scales the node's transform. The default "appends" the transform, so that it will appear to happen to the Node before the rest of the transform would apply, but if "prepended", the rest of the transform would apply first.

As an example, if a Node is translated to (100,0): scale( 2 ) will leave the Node translated at (100,0), but it will be twice as big around its origin at that location. scale( 2, true ) will shift the Node to (200,0).

Allowed call signatures: (s invocation): scale( s {number|Vector2}, [prependInstead] {boolean} ) (x,y invocation): scale( x {number}, y {number}, [prependInstead] {boolean} )

@param x - (s invocation): {number} scales both dimensions equally, or {Vector2} scales independently - (x,y invocation): {number} scale for the x-dimension @param [y] - (s invocation): {boolean} prependInstead - Whether the transform should be prepended (defaults to false) - (x,y invocation): {number} y - scale for the y-dimension @param [prependInstead] - (x,y invocation) Whether the transform should be prepended (defaults to false)

scale( s : Vector2, prependInstead? : boolean )¶

scale( x : number, y : number, prependInstead? : boolean )¶

scale( x : number | Vector2, y? : number | boolean, prependInstead? : boolean )¶

rotate( angle : number, prependInstead? : boolean )¶

Rotates the node's transform. The default "appends" the transform, so that it will appear to happen to the Node before the rest of the transform would apply, but if "prepended", the rest of the transform would apply first.

As an example, if a Node is translated to (100,0): rotate( Math.PI ) will rotate the Node around (100,0) rotate( Math.PI, true ) will rotate the Node around the origin, moving it to (-100,0)

@param angle - The angle (in radians) to rotate by @param [prependInstead] - Whether the transform should be prepended (defaults to false)

rotateAround( point : Vector2, angle : number ) : this¶

Rotates the node's transform around a specific point (in the parent coordinate frame) by prepending the transform.

TODO: determine whether this should use the appendMatrix method https://github.com/phetsims/scenery/issues/1581

@param point - In the parent coordinate frame @param angle - In radians

setX( x : number ) : this¶

Shifts the x coordinate (in the parent coordinate frame) of where the node's origin is transformed to.

getX() : number¶

Returns the x coordinate (in the parent coordinate frame) of where the node's origin is transformed to.

setY( y : number ) : this¶

Shifts the y coordinate (in the parent coordinate frame) of where the node's origin is transformed to.

getY() : number¶

Returns the y coordinate (in the parent coordinate frame) of where the node's origin is transformed to.

setScaleMagnitude( s : number ) : this¶

Typically without rotations or negative parameters, this sets the scale for each axis. In its more general form, it modifies the node's transform so that: - Transforming (1,0) with our transform will result in a vector with magnitude abs( x-scale-magnitude ) - Transforming (0,1) with our transform will result in a vector with magnitude abs( y-scale-magnitude ) - If parameters are negative, it will flip orientation in that direct.

Allowed call signatures: setScaleMagnitude( s ) setScaleMagnitude( sx, sy ) setScaleMagnitude( vector )

@param a - Scale for both axes, or scale for x-axis if using the 2-parameter call @param [b] - Scale for the Y axis (only for the 2-parameter call)

setScaleMagnitude( v : Vector2 ) : this¶

setScaleMagnitude( sx : number, sy : number ) : this¶

setScaleMagnitude( a : number | Vector2, b? : number ) : this¶

getScaleVector() : Vector2¶

Returns a vector with an entry for each axis, e.g. (5,2) for an affine matrix with rows ((5,0,0),(0,2,0),(0,0,1)).

It is equivalent to: ( T(1,0).magnitude(), T(0,1).magnitude() ) where T() transforms points with our transform.

setRotation( rotation : number ) : this¶

Rotates this node's transform so that a unit (1,0) vector would be rotated by this node's transform by the specified amount.

@param rotation - In radians

getRotation() : number¶

Returns the rotation (in radians) that would be applied to a unit (1,0) vector when transformed with this Node's transform.

setTranslation( x : number, y : number ) : this¶

Modifies the translation of this Node's transform so that the node's local-coordinate origin will be transformed to the passed-in x/y.

Allowed call signatures: setTranslation( x, y ) setTranslation( vector )

@param a - X translation - or Vector with x/y translation in components @param [b] - Y translation

setTranslation( v : Vector2 ) : this¶

setTranslation( a : number | Vector2, b? : number ) : this¶

getTranslation() : Vector2¶

Returns a vector of where this Node's local-coordinate origin will be transformed by it's own transform.

appendMatrix( matrix : Matrix3 )¶

Appends a transformation matrix to this Node's transform. Appending means this transform is conceptually applied first before the rest of the Node's current transform (i.e. applied in the local coordinate frame).

prependMatrix( matrix : Matrix3 )¶

Prepends a transformation matrix to this Node's transform. Prepending means this transform is conceptually applied after the rest of the Node's current transform (i.e. applied in the parent coordinate frame).

prependTranslation( x : number, y : number )¶

Prepends an (x,y) translation to our Node's transform in an efficient manner without allocating a matrix. see https://github.com/phetsims/scenery/issues/119

setMatrix( matrix : Matrix3 )¶

Changes this Node's transform to match the passed-in transformation matrix.

getMatrix() : Matrix3¶

Returns a Matrix3 representing our Node's transform.

NOTE: Do not mutate the returned matrix.

getTransform() : Transform3¶

Returns a reference to our Node's transform

resetTransform()¶

Resets our Node's transform to an identity transform (i.e. no transform is applied).

auditMaxDimensions()¶

Scenery-internal method for verifying maximum dimensions are NOT smaller than preferred dimensions NOTE: This has to be public due to mixins not able to access protected/private methods

setMaxWidth( maxWidth : number | null )¶

Sets the maximum width of the Node (see constructor for documentation on how maximum dimensions work).

getMaxWidth() : number | null¶

Returns the maximum width (if any) of the Node.

setMaxHeight( maxHeight : number | null )¶

Sets the maximum height of the Node (see constructor for documentation on how maximum dimensions work).

getMaxHeight() : number | null¶

Returns the maximum height (if any) of the Node.

setLeft( left : number ) : this¶

Shifts this Node horizontally so that its left bound (in the parent coordinate frame) is equal to the passed-in 'left' X value.

NOTE: This may require computation of this node's subtree bounds, which may incur some performance loss.

@param left - After this operation, node.left should approximately equal this value.

getLeft() : number¶

Returns the X value of the left side of the bounding box of this Node (in the parent coordinate frame).

NOTE: This may require computation of this node's subtree bounds, which may incur some performance loss.

setRight( right : number ) : this¶

Shifts this Node horizontally so that its right bound (in the parent coordinate frame) is equal to the passed-in 'right' X value.

NOTE: This may require computation of this node's subtree bounds, which may incur some performance loss.

@param right - After this operation, node.right should approximately equal this value.

getRight() : number¶

Returns the X value of the right side of the bounding box of this Node (in the parent coordinate frame).

NOTE: This may require computation of this node's subtree bounds, which may incur some performance loss.

setCenterX( x : number ) : this¶

Shifts this Node horizontally so that its horizontal center (in the parent coordinate frame) is equal to the passed-in center X value.

NOTE: This may require computation of this node's subtree bounds, which may incur some performance loss.

@param x - After this operation, node.centerX should approximately equal this value.

getCenterX() : number¶

Returns the X value of this node's horizontal center (in the parent coordinate frame)

NOTE: This may require computation of this node's subtree bounds, which may incur some performance loss.

setCenterY( y : number ) : this¶

Shifts this Node vertically so that its vertical center (in the parent coordinate frame) is equal to the passed-in center Y value.

NOTE: This may require computation of this node's subtree bounds, which may incur some performance loss.

@param y - After this operation, node.centerY should approximately equal this value.

getCenterY() : number¶

Returns the Y value of this node's vertical center (in the parent coordinate frame)

NOTE: This may require computation of this node's subtree bounds, which may incur some performance loss.

setTop( top : number ) : this¶

Shifts this Node vertically so that its top (in the parent coordinate frame) is equal to the passed-in Y value.

NOTE: top is the lowest Y value in our bounds. NOTE: This may require computation of this node's subtree bounds, which may incur some performance loss.

@param top - After this operation, node.top should approximately equal this value.

getTop() : number¶

Returns the lowest Y value of this node's bounding box (in the parent coordinate frame).

NOTE: This may require computation of this node's subtree bounds, which may incur some performance loss.

setBottom( bottom : number ) : this¶

Shifts this Node vertically so that its bottom (in the parent coordinate frame) is equal to the passed-in Y value.

NOTE: bottom is the highest Y value in our bounds. NOTE: This may require computation of this node's subtree bounds, which may incur some performance loss.

@param bottom - After this operation, node.bottom should approximately equal this value.

getBottom() : number¶

Returns the highest Y value of this node's bounding box (in the parent coordinate frame).

NOTE: This may require computation of this node's subtree bounds, which may incur some performance loss.

setLeftTop( leftTop : Vector2 ) : this¶

Sets the position of the upper-left corner of this node's bounds to the specified point.

getLeftTop() : Vector2¶

Returns the upper-left corner of this node's bounds.

setCenterTop( centerTop : Vector2 ) : this¶

Sets the position of the center-top location of this node's bounds to the specified point.

getCenterTop() : Vector2¶

Returns the center-top location of this node's bounds.

setRightTop( rightTop : Vector2 ) : this¶

Sets the position of the upper-right corner of this node's bounds to the specified point.

getRightTop() : Vector2¶

Returns the upper-right corner of this node's bounds.

setLeftCenter( leftCenter : Vector2 ) : this¶

Sets the position of the center-left of this node's bounds to the specified point.

getLeftCenter() : Vector2¶

Returns the center-left corner of this node's bounds.

setCenter( center : Vector2 ) : this¶

Sets the center of this node's bounds to the specified point.

getCenter() : Vector2¶

Returns the center of this node's bounds.

setRightCenter( rightCenter : Vector2 ) : this¶

Sets the position of the center-right of this node's bounds to the specified point.

getRightCenter() : Vector2¶

Returns the center-right of this node's bounds.

setLeftBottom( leftBottom : Vector2 ) : this¶

Sets the position of the lower-left corner of this node's bounds to the specified point.

getLeftBottom() : Vector2¶

Returns the lower-left corner of this node's bounds.

setCenterBottom( centerBottom : Vector2 ) : this¶

Sets the position of the center-bottom of this node's bounds to the specified point.

getCenterBottom() : Vector2¶

Returns the center-bottom of this node's bounds.

setRightBottom( rightBottom : Vector2 ) : this¶

Sets the position of the lower-right corner of this node's bounds to the specified point.

getRightBottom() : Vector2¶

Returns the lower-right corner of this node's bounds.

getWidth() : number¶

Returns the width of this node's bounding box (in the parent coordinate frame).

NOTE: This may require computation of this node's subtree bounds, which may incur some performance loss.

getHeight() : number¶

Returns the height of this node's bounding box (in the parent coordinate frame).

NOTE: This may require computation of this node's subtree bounds, which may incur some performance loss.

getLocalWidth() : number¶

Returns the width of this node's bounding box (in the local coordinate frame).

NOTE: This may require computation of this node's subtree bounds, which may incur some performance loss.

getLocalHeight() : number¶

Returns the height of this node's bounding box (in the local coordinate frame).

NOTE: This may require computation of this node's subtree bounds, which may incur some performance loss.

getLocalLeft() : number¶

Returns the X value of the left side of the bounding box of this Node (in the local coordinate frame).

NOTE: This may require computation of this node's subtree bounds, which may incur some performance loss.

getLocalRight() : number¶

Returns the X value of the right side of the bounding box of this Node (in the local coordinate frame).

NOTE: This may require computation of this node's subtree bounds, which may incur some performance loss.

getLocalCenterX() : number¶

Returns the X value of this node's horizontal center (in the local coordinate frame)

NOTE: This may require computation of this node's subtree bounds, which may incur some performance loss.

getLocalCenterY() : number¶

Returns the Y value of this node's vertical center (in the local coordinate frame)

NOTE: This may require computation of this node's subtree bounds, which may incur some performance loss.

getLocalTop() : number¶

Returns the lowest Y value of this node's bounding box (in the local coordinate frame).

NOTE: This may require computation of this node's subtree bounds, which may incur some performance loss.

getLocalBottom() : number¶

Returns the highest Y value of this node's bounding box (in the local coordinate frame).

NOTE: This may require computation of this node's subtree bounds, which may incur some performance loss.

getLocalLeftTop() : Vector2¶

Returns the upper-left corner of this node's localBounds.

getLocalCenterTop() : Vector2¶

Returns the center-top location of this node's localBounds.

getLocalRightTop() : Vector2¶

Returns the upper-right corner of this node's localBounds.

getLocalLeftCenter() : Vector2¶

Returns the center-left corner of this node's localBounds.

getLocalCenter() : Vector2¶

Returns the center of this node's localBounds.

getLocalRightCenter() : Vector2¶

Returns the center-right of this node's localBounds.

getLocalLeftBottom() : Vector2¶

Returns the lower-left corner of this node's localBounds.

getLocalCenterBottom() : Vector2¶

Returns the center-bottom of this node's localBounds.

getLocalRightBottom() : Vector2¶

Returns the lower-right corner of this node's localBounds.

getId() : number¶

Returns the unique integral ID for this node.

setVisibleProperty( newTarget : TReadOnlyProperty<boolean> | null ) : this¶

Sets what Property our visibleProperty is backed by, so that changes to this provided Property will change this Node's visibility, and vice versa. This does not change this._visibleProperty. See TinyForwardingProperty.setTargetProperty() for more info.

NOTE For PhET-iO use: All PhET-iO instrumented Nodes create their own instrumented visibleProperty (if one is not passed in as an option). Once a Node's visibleProperty has been registered with PhET-iO, it cannot be "swapped out" for another. If you need to "delay" setting an instrumented visibleProperty to this node, pass phetioVisiblePropertyInstrumented to instrumentation call to this Node (where Tandem is provided).

getVisibleProperty() : TProperty<boolean>¶

Get this Node's visibleProperty. Note! This is not the reciprocal of setVisibleProperty. Node.prototype._visibleProperty is a TinyForwardingProperty, and is set up to listen to changes from the visibleProperty provided by setVisibleProperty(), but the underlying reference does not change. This means the following: * const myNode = new Node(); const visibleProperty = new Property( false ); myNode.setVisibleProperty( visibleProperty ) => myNode.getVisibleProperty() !== visibleProperty (!!!!!!)

Please use this with caution. See setVisibleProperty() for more information.

setVisible( visible : boolean ) : this¶

Sets whether this Node is visible. DO NOT override this as a way of adding additional behavior when a Node's visibility changes, add a listener to this.visibleProperty instead.

isVisible() : boolean¶

Returns whether this Node is visible.

setPhetioVisiblePropertyInstrumented( phetioVisiblePropertyInstrumented : boolean ) : this¶

Use this to automatically create a forwarded, PhET-iO instrumented visibleProperty internal to Node.

getPhetioVisiblePropertyInstrumented() : boolean¶

swapVisibility( otherNode : Node ) : this¶

Swap the visibility of this node with another node. The Node that is made visible will receive keyboard focus if it is focusable and the previously visible Node had focus.

setOpacity( opacity : number )¶

Sets the opacity of this Node (and its sub-tree), where 0 is fully transparent, and 1 is fully opaque. Values outside of that range throw an Error. @throws Error if opacity out of range

getOpacity() : number¶

Returns the opacity of this node.

setDisabledOpacity( disabledOpacity : number ) : this¶

Sets the disabledOpacity of this Node (and its sub-tree), where 0 is fully transparent, and 1 is fully opaque. Values outside of that range throw an Error. @throws Error if disabledOpacity out of range

getDisabledOpacity() : number¶

Returns the disabledOpacity of this node.

getEffectiveOpacity() : number¶

Returns the opacity actually applied to the node.

setFilters( filters : Filter[] )¶

Sets the non-opacity filters for this Node.

The default is an empty array (no filters). It should be an array of Filter objects, which will be effectively applied in-order on this Node (and its subtree), and will be applied BEFORE opacity/clipping.

NOTE: Some filters may decrease performance (and this may be platform-specific). Please read documentation for each filter before using.

Typical filter types to use are: - Brightness - Contrast - DropShadow (EXPERIMENTAL) - GaussianBlur (EXPERIMENTAL) - Grayscale (Grayscale.FULL for the full effect) - HueRotate - Invert (Invert.FULL for the full effect) - Saturate - Sepia (Sepia.FULL for the full effect)

Filter.js has more information in general on filters.

getFilters() : Filter[]¶

Returns the non-opacity filters for this Node.

setPickableProperty( newTarget : TReadOnlyProperty<boolean | null> | null ) : this¶

Sets what Property our pickableProperty is backed by, so that changes to this provided Property will change this Node's pickability, and vice versa. This does not change this._pickableProperty. See TinyForwardingProperty.setTargetProperty() for more info.

PhET-iO Instrumented Nodes do not by default create their own instrumented pickableProperty, even though Node.visibleProperty does.

getPickableProperty() : TProperty<boolean | null>¶

Get this Node's pickableProperty. Note! This is not the reciprocal of setPickableProperty. Node.prototype._pickableProperty is a TinyForwardingProperty, and is set up to listen to changes from the pickableProperty provided by setPickableProperty(), but the underlying reference does not change. This means the following: const myNode = new Node(); const pickableProperty = new Property( false ); myNode.setPickableProperty( pickableProperty ) => myNode.getPickableProperty() !== pickableProperty (!!!!!!)

Please use this with caution. See setPickableProperty() for more information.

setPickable( pickable : boolean | null ) : this¶

Sets whether this Node (and its subtree) will allow hit-testing (and thus user interaction), controlling what Trail is returned from node.trailUnderPoint().

Pickable can take one of three values: - null: (default) pass-through behavior. Hit-testing will prune this subtree if there are no ancestors/descendants with either pickable: true set or with any input listeners. - false: Hit-testing is pruned, nothing in this node or its subtree will respond to events or be picked. - true: Hit-testing will not be pruned in this subtree, except for pickable: false cases.

Hit testing is accomplished mainly with node.trailUnderPointer() and node.trailUnderPoint(), following the above rules. Nodes that are not pickable (pruned) will not have input events targeted to them.

The following rules (applied in the given order) determine whether a Node (really, a Trail) will receive input events: 1. If the node or one of its ancestors has pickable: false OR is invisible, the Node will not receive events or hit testing. 2. If the Node or one of its ancestors or descendants is pickable: true OR has an input listener attached, it will receive events or hit testing. 3. Otherwise, it will not receive events or hit testing.

This is useful for semi-transparent overlays or other visual elements that should be displayed but should not prevent objects below from being manipulated by user input, and the default null value is used to increase performance by ignoring areas that don't need user input.

NOTE: If you want something to be picked "mouse is over it", but block input events even if there are listeners, then pickable:false is not appropriate, and inputEnabled:false is preferred.

For a visual example of how pickability interacts with input listeners and visibility, see the notes at the bottom of http://phetsims.github.io/scenery/doc/implementation-notes, or scenery/assets/pickability.svg.

isPickable() : boolean | null¶

Returns the pickability of this node.

setEnabledProperty( newTarget : TReadOnlyProperty<boolean> | null ) : this¶

Sets what Property our enabledProperty is backed by, so that changes to this provided Property will change this Node's enabled, and vice versa. This does not change this._enabledProperty. See TinyForwardingProperty.setTargetProperty() for more info.

NOTE For PhET-iO use: All PhET-iO instrumented Nodes create their own instrumented enabledProperty (if one is not passed in as an option). Once a Node's enabledProperty has been registered with PhET-iO, it cannot be "swapped out" for another. If you need to "delay" setting an instrumented enabledProperty to this node, pass phetioEnabledPropertyInstrumented to instrumentation call to this Node (where Tandem is provided).

getEnabledProperty() : TProperty<boolean>¶

Get this Node's enabledProperty. Note! This is not the reciprocal of setEnabledProperty. Node.prototype._enabledProperty is a TinyForwardingProperty, and is set up to listen to changes from the enabledProperty provided by setEnabledProperty(), but the underlying reference does not change. This means the following: const myNode = new Node(); const enabledProperty = new Property( false ); myNode.setEnabledProperty( enabledProperty ) => myNode.getEnabledProperty() !== enabledProperty (!!!!!!)

Please use this with caution. See setEnabledProperty() for more information.

setPhetioEnabledPropertyInstrumented( phetioEnabledPropertyInstrumented : boolean ) : this¶

Use this to automatically create a forwarded, PhET-iO instrumented enabledProperty internal to Node. This is different from visible because enabled by default doesn't not create this forwarded Property.

getPhetioEnabledPropertyInstrumented() : boolean¶

setEnabled( enabled : boolean ) : this¶

Sets whether this Node is enabled

isEnabled() : boolean¶

Returns the enabled of this node.

onEnabledPropertyChange( enabled : boolean )¶

(protected)

Called when enabledProperty changes values. - override this to change the behavior of enabled

setInputEnabledProperty( newTarget : TReadOnlyProperty<boolean> | null ) : this¶

Sets what Property our inputEnabledProperty is backed by, so that changes to this provided Property will change this whether this Node's input is enabled, and vice versa. This does not change this._inputEnabledProperty. See TinyForwardingProperty.setTargetProperty() for more info.

NOTE For PhET-iO use: All PhET-iO instrumented Nodes create their own instrumented inputEnabledProperty (if one is not passed in as an option). Once a Node's inputEnabledProperty has been registered with PhET-iO, it cannot be "swapped out" for another. If you need to "delay" setting an instrumented inputEnabledProperty to this node, pass phetioInputEnabledPropertyInstrumented to instrumentation call to this Node (where Tandem is provided).

getInputEnabledProperty() : TProperty<boolean>¶

Get this Node's inputEnabledProperty. Note! This is not the reciprocal of setInputEnabledProperty. Node.prototype._inputEnabledProperty is a TinyForwardingProperty, and is set up to listen to changes from the inputEnabledProperty provided by setInputEnabledProperty(), but the underlying reference does not change. This means the following: const myNode = new Node(); const inputEnabledProperty = new Property( false ); myNode.setInputEnabledProperty( inputEnabledProperty ) => myNode.getInputEnabledProperty() !== inputEnabledProperty (!!!!!!)

Please use this with caution. See setInputEnabledProperty() for more information.

setPhetioInputEnabledPropertyInstrumented( phetioInputEnabledPropertyInstrumented : boolean ) : this¶

Use this to automatically create a forwarded, PhET-iO instrumented inputEnabledProperty internal to Node. This is different from visible because inputEnabled by default doesn't not create this forwarded Property.

getPhetioInputEnabledPropertyInstrumented() : boolean¶

setInputEnabled( inputEnabled : boolean )¶

Sets whether input is enabled for this Node and its subtree. If false, input event listeners will not be fired on this Node or its descendants in the picked Trail. This does NOT effect picking (what Trail/nodes are under a pointer), but only effects what listeners are fired.

Additionally, this will affect cursor behavior. If inputEnabled=false, descendants of this Node will not be checked when determining what cursor will be shown. Instead, if a pointer (e.g. mouse) is over a descendant, this Node's cursor will be checked first, then ancestors will be checked as normal.

isInputEnabled() : boolean¶

Returns whether input is enabled for this Node and its subtree. See setInputEnabled for more documentation.

setInputListeners( inputListeners : TInputListener[] ) : this¶

Sets all of the input listeners attached to this Node.

This is equivalent to removing all current input listeners with removeInputListener() and adding all new listeners (in order) with addInputListener().

getInputListeners() : TInputListener[]¶

Returns a copy of all of our input listeners.

setCursor( cursor : string | null )¶

Sets the CSS cursor string that should be used when the mouse is over this node. null is the default, and indicates that ancestor nodes (or the browser default) should be used.

@param cursor - A CSS cursor string, like 'pointer', or 'none' - Examples are: auto default none inherit help pointer progress wait crosshair text vertical-text alias copy move no-drop not-allowed e-resize n-resize w-resize s-resize nw-resize ne-resize se-resize sw-resize ew-resize ns-resize nesw-resize nwse-resize context-menu cell col-resize row-resize all-scroll url( ... ) --> does it support data URLs?

getCursor() : string | null¶

Returns the CSS cursor string for this node, or null if there is no cursor specified.

setMouseArea( area : Shape | Bounds2 | null ) : this¶

Sets the hit-tested mouse area for this Node (see constructor for more advanced documentation). Use null for the default behavior.

getMouseArea() : Shape | Bounds2 | null¶

Returns the hit-tested mouse area for this node.

setTouchArea( area : Shape | Bounds2 | null ) : this¶

Sets the hit-tested touch area for this Node (see constructor for more advanced documentation). Use null for the default behavior.

getTouchArea() : Shape | Bounds2 | null¶

Returns the hit-tested touch area for this node.

setClipArea( shape : Shape | null )¶

Sets a clipped shape where only content in our local coordinate frame that is inside the clip area will be shown (anything outside is fully transparent).

getClipArea() : Shape | null¶

Returns the clipped area for this node.

hasClipArea() : boolean¶

Returns whether this Node has a clip area.

setRendererBitmask( bitmask : number )¶

(protected)

Sets what self renderers (and other bitmask flags) are supported by this node.

invalidateSupportedRenderers()¶

Meant to be overridden, so that it can be called to ensure that the renderer bitmask will be up-to-date.

setRenderer( renderer : RendererType )¶

Sets a preferred renderer for this Node and its sub-tree. Scenery will attempt to use this renderer under here unless it isn't supported, OR another preferred renderer is set as a closer ancestor. Acceptable values are: - null (default, no preference) - 'canvas' - 'svg' - 'dom' - 'webgl'

getRenderer() : RendererType¶

Returns the preferred renderer (if any) of this node, as a string.

setLayerSplit( split : boolean )¶

Sets whether or not Scenery will try to put this Node (and its descendants) into a separate SVG/Canvas/WebGL/etc. layer, different from other siblings or other nodes. Can be used for performance purposes.

isLayerSplit() : boolean¶

Returns whether the layerSplit performance flag is set.

setUsesOpacity( usesOpacity : boolean )¶

Sets whether or not Scenery will take into account that this Node plans to use opacity. Can have performance gains if there need to be multiple layers for this node's descendants.

getUsesOpacity() : boolean¶

Returns whether the usesOpacity performance flag is set.

setCSSTransform( cssTransform : boolean )¶

Sets a flag for whether whether the contents of this Node and its children should be displayed in a separate DOM element that is transformed with CSS transforms. It can have potential speedups, since the browser may not have to re-rasterize contents when it is animated.

isCSSTransformed() : boolean¶

Returns whether the cssTransform performance flag is set.

setExcludeInvisible( excludeInvisible : boolean )¶

Sets a performance flag for whether layers/DOM elements should be excluded (or included) when things are invisible. The default is false, and invisible content is in the DOM, but hidden.

isExcludeInvisible() : boolean¶

Returns whether the excludeInvisible performance flag is set.

setExcludeInvisibleChildrenFromBounds( excludeInvisibleChildrenFromBounds : boolean )¶

If this is set to true, child nodes that are invisible will NOT contribute to the bounds of this node.

The default is for child nodes bounds' to be included in this node's bounds, but that would in general be a problem for layout containers or other situations, see https://github.com/phetsims/joist/issues/608.

isExcludeInvisibleChildrenFromBounds() : boolean¶

Returns whether the excludeInvisibleChildrenFromBounds flag is set, see setExcludeInvisibleChildrenFromBounds() for documentation.

setInterruptSubtreeOnInvisible( interruptSubtreeOnInvisible : boolean )¶

If this is set to true, this node will call interruptSubtreeInput() on itself when it is made invisible. See https://github.com/phetsims/scenery/issues/1645.

isInterruptSubtreeOnInvisible() : boolean¶

Returns whether the interruptSubtreeOnInvisible flag is set, see setInterruptSubtreeOnInvisible() for documentation.

setLayoutOptions( layoutOptions : TLayoutOptions | null )¶

Sets options that are provided to layout managers in order to customize positioning of this node.

getLayoutOptions() : TLayoutOptions | null¶

mutateLayoutOptions( layoutOptions? : TLayoutOptions )¶

setPreventFit( preventFit : boolean )¶

Sets the preventFit performance flag.

isPreventFit() : boolean¶

Returns whether the preventFit performance flag is set.

setWebGLScale( webglScale : number | null )¶

Sets whether there is a custom WebGL scale applied to the Canvas, and if so what scale.

getWebGLScale() : number | null¶

Returns the value of the webglScale performance flag.

getUniqueTrail( predicate? : ( node: Node ) => boolean ) : Trail¶

Returns the one Trail that starts from a node with no parents (or if the predicate is present, a Node that satisfies it), and ends at this node. If more than one Trail would satisfy these conditions, an assertion is thrown (please use getTrails() for those cases).

@param [predicate] - If supplied, we will only return trails rooted at a Node that satisfies predicate( node ) == true

getUniqueTrailTo( rootNode : Node ) : Trail¶

Returns a Trail rooted at rootNode and ends at this node. Throws an assertion if the number of trails that match this condition isn't exactly 1.

getTrails( predicate? : ( node: Node ) => boolean ) : Trail[]¶

Returns an array of all Trails that start from nodes with no parent (or if a predicate is present, those that satisfy the predicate), and ends at this node.

@param [predicate] - If supplied, we will only return Trails rooted at nodes that satisfy predicate( node ) == true.

getTrailsTo( rootNode : Node ) : Trail[]¶

Returns an array of all Trails rooted at rootNode and end at this node.

getLeafTrails( predicate? : ( node: Node ) => boolean ) : Trail[]¶

Returns an array of all Trails rooted at this Node and end with nodes with no children (or if a predicate is present, those that satisfy the predicate).

@param [predicate] - If supplied, we will only return Trails ending at nodes that satisfy predicate( node ) == true.

getLeafTrailsTo( leafNode : Node ) : Trail[]¶

Returns an array of all Trails rooted at this Node and end with leafNode.

getUniqueLeafTrail( predicate? : ( node: Node ) => boolean ) : Trail¶

Returns a Trail rooted at this node and ending at a Node that has no children (or if a predicate is provided, a Node that satisfies the predicate). If more than one trail matches this description, an assertion will be fired.

@param [predicate] - If supplied, we will return a Trail that ends with a Node that satisfies predicate( node ) == true

getUniqueLeafTrailTo( leafNode : Node ) : Trail¶

Returns a Trail rooted at this Node and ending at leafNode. If more than one trail matches this description, an assertion will be fired.

getConnectedNodes() : Node[]¶

Returns all nodes in the connected component, returned in an arbitrary order, including nodes that are ancestors of this node.

getSubtreeNodes() : Node[]¶

Returns all nodes in the subtree with this Node as its root, returned in an arbitrary order. Like getConnectedNodes, but doesn't include parents.

getTopologicallySortedNodes() : Node[]¶

Returns all nodes that are connected to this node, sorted in topological order.

canAddChild( child : Node ) : boolean¶

Returns whether this.addChild( child ) will not cause circular references.

canvasPaintSelf( wrapper : CanvasContextWrapper, matrix : Matrix3 )¶

(protected)

To be overridden in paintable Node types. Should hook into the drawable's prototype (presumably).

Draws the current Node's self representation, assuming the wrapper's Canvas context is already in the local coordinate frame of this node.

@param wrapper @param matrix - The transformation matrix already applied to the context.

renderToCanvasSelf( wrapper : CanvasContextWrapper, matrix : Matrix3 )¶

Renders this Node only (its self) into the Canvas wrapper, in its local coordinate frame.

@param wrapper @param matrix - The transformation matrix already applied to the context.

renderToCanvasSubtree( wrapper : CanvasContextWrapper, matrix? : Matrix3 )¶

Renders this Node and its descendants into the Canvas wrapper.

@param wrapper @param [matrix] - Optional transform to be applied

renderToCanvas( canvas : HTMLCanvasElement, context : CanvasRenderingContext2D, callback? : () => void, backgroundColor? : string )¶

@deprecated Render this Node to the Canvas (clearing it first)

toCanvas( callback : ( canvas: HTMLCanvasElement, x: number, y: number, width: number, height: number ) => void, x? : number, y? : number, width? : number, height? : number )¶

Renders this Node to an HTMLCanvasElement. If toCanvas( callback ) is used, the canvas will contain the node's entire bounds (if no x/y/width/height is provided)

@param callback - callback( canvas, x, y, width, height ) is called, where x,y are computed if not specified. @param [x] - The X offset for where the upper-left of the content drawn into the Canvas @param [y] - The Y offset for where the upper-left of the content drawn into the Canvas @param [width] - The width of the Canvas output @param [height] - The height of the Canvas output

toDataURL( callback : ( dataURI: string, x: number, y: number, width: number, height: number ) => void, x? : number, y? : number, width? : number, height? : number )¶

Renders this Node to a Canvas, then calls the callback with the data URI from it.

@param callback - callback( dataURI {string}, x, y, width, height ) is called, where x,y are computed if not specified. @param [x] - The X offset for where the upper-left of the content drawn into the Canvas @param [y] - The Y offset for where the upper-left of the content drawn into the Canvas @param [width] - The width of the Canvas output @param [height] - The height of the Canvas output

toImage( callback : ( image: HTMLImageElement, x: number, y: number ) => void, x? : number, y? : number, width? : number, height? : number )¶

Calls the callback with an HTMLImageElement that contains this Node's subtree's visual form. Will always be asynchronous. @deprecated - Use node.rasterized() for creating a rasterized copy, or generally it's best to get the data URL instead directly.

@param callback - callback( image {HTMLImageElement}, x, y ) is called @param [x] - The X offset for where the upper-left of the content drawn into the Canvas @param [y] - The Y offset for where the upper-left of the content drawn into the Canvas @param [width] - The width of the Canvas output @param [height] - The height of the Canvas output

toImageNodeAsynchronous( callback : ( image: Node ) => void, x? : number, y? : number, width? : number, height? : number )¶

Calls the callback with an Image Node that contains this Node's subtree's visual form. This is always asynchronous, but the resulting image Node can be used with any back-end (Canvas/WebGL/SVG/etc.) @deprecated - Use node.rasterized() instead (should avoid the asynchronous-ness)

@param callback - callback( imageNode {Image} ) is called @param [x] - The X offset for where the upper-left of the content drawn into the Canvas @param [y] - The Y offset for where the upper-left of the content drawn into the Canvas @param [width] - The width of the Canvas output @param [height] - The height of the Canvas output

toCanvasNodeSynchronous( x? : number, y? : number, width? : number, height? : number ) : Node¶

Creates a Node containing an Image Node that contains this Node's subtree's visual form. This is always synchronous, but the resulting image Node can ONLY used with Canvas/WebGL (NOT SVG). @deprecated - Use node.rasterized() instead, should be mostly equivalent if useCanvas:true is provided.

@param [x] - The X offset for where the upper-left of the content drawn into the Canvas @param [y] - The Y offset for where the upper-left of the content drawn into the Canvas @param [width] - The width of the Canvas output @param [height] - The height of the Canvas output

toDataURLImageSynchronous( x? : number, y? : number, width? : number, height? : number ) : Image¶

Returns an Image that renders this Node. This is always synchronous, and sets initialWidth/initialHeight so that we have the bounds immediately. Use this method if you need to reduce the number of parent Nodes.

NOTE: the resultant Image should be positioned using its bounds rather than (x,y). To create a Node that can be positioned like any other node, please use toDataURLNodeSynchronous. @deprecated - Use node.rasterized() instead, should be mostly equivalent if wrap:false is provided.

@param [x] - The X offset for where the upper-left of the content drawn into the Canvas @param [y] - The Y offset for where the upper-left of the content drawn into the Canvas @param [width] - The width of the Canvas output @param [height] - The height of the Canvas output

toDataURLNodeSynchronous( x? : number, y? : number, width? : number, height? : number ) : Node¶

Returns a Node that contains this Node's subtree's visual form. This is always synchronous, and sets initialWidth/initialHeight so that we have the bounds immediately. An extra wrapper Node is provided so that transforms can be done independently. Use this method if you need to be able to transform the node the same way as if it had not been rasterized. @deprecated - Use node.rasterized() instead, should be mostly equivalent

@param [x] - The X offset for where the upper-left of the content drawn into the Canvas @param [y] - The Y offset for where the upper-left of the content drawn into the Canvas @param [width] - The width of the Canvas output @param [height] - The height of the Canvas output

rasterized( providedOptions? : RasterizedOptions ) : Node¶

Returns a Node (backed by a scenery Image) that is a rasterized version of this node. See options, by default the image is wrapped with a container Node.

wasVisuallyDisplayed( display? : Display ) : boolean¶

Returns whether this Node was visually rendered/displayed by any Display in the last updateDisplay() call. Note that something can be independently displayed visually, and in the PDOM; this method only checks visually.

@param [display] - if provided, only check if was visible on this particular Display

getConnectedDisplays() : Display[]¶

Get a list of the displays that are connected to this Node. Gathered by looking up the scene graph ancestors and collected all rooted Displays along the way.

localToParentPoint( point : Vector2 ) : Vector2¶

Returns a point transformed from our local coordinate frame into our parent coordinate frame. Applies our node's transform to it.

localToParentBounds( bounds : Bounds2 ) : Bounds2¶

Returns bounds transformed from our local coordinate frame into our parent coordinate frame. If it includes a rotation, the resulting bounding box will include every point that could have been in the original bounding box (and it can be expanded).

parentToLocalPoint( point : Vector2 ) : Vector2¶

Returns a point transformed from our parent coordinate frame into our local coordinate frame. Applies the inverse of our node's transform to it.

parentToLocalBounds( bounds : Bounds2 ) : Bounds2¶

Returns bounds transformed from our parent coordinate frame into our local coordinate frame. If it includes a rotation, the resulting bounding box will include every point that could have been in the original bounding box (and it can be expanded).

transformBoundsFromLocalToParent( bounds : Bounds2 ) : Bounds2¶

A mutable-optimized form of localToParentBounds() that will modify the provided bounds, transforming it from our local coordinate frame to our parent coordinate frame. @returns - The same bounds object.

transformBoundsFromParentToLocal( bounds : Bounds2 ) : Bounds2¶

A mutable-optimized form of parentToLocalBounds() that will modify the provided bounds, transforming it from our parent coordinate frame to our local coordinate frame. @returns - The same bounds object.

getLocalToGlobalMatrix() : Matrix3¶

Returns a new matrix (fresh copy) that would transform points from our local coordinate frame to the global coordinate frame.

NOTE: If there are multiple instances of this Node (e.g. this or one ancestor has two parents), it will fail with an assertion (since the transform wouldn't be uniquely defined).

getUniqueTransform() : Transform3¶

Returns a Transform3 that would transform things from our local coordinate frame to the global coordinate frame. Equivalent to getUniqueTrail().getTransform(), but faster.

NOTE: If there are multiple instances of this Node (e.g. this or one ancestor has two parents), it will fail with an assertion (since the transform wouldn't be uniquely defined).

getGlobalToLocalMatrix() : Matrix3¶

Returns a new matrix (fresh copy) that would transform points from the global coordinate frame to our local coordinate frame.

NOTE: If there are multiple instances of this Node (e.g. this or one ancestor has two parents), it will fail with an assertion (since the transform wouldn't be uniquely defined).

localToGlobalPoint( point : Vector2 ) : Vector2¶

Transforms a point from our local coordinate frame to the global coordinate frame.

NOTE: If there are multiple instances of this Node (e.g. this or one ancestor has two parents), it will fail with an assertion (since the transform wouldn't be uniquely defined).

globalToLocalPoint( point : Vector2 ) : Vector2¶

Transforms a point from the global coordinate frame to our local coordinate frame.

NOTE: If there are multiple instances of this Node (e.g. this or one ancestor has two parents), it will fail with an assertion (since the transform wouldn't be uniquely defined).

localToGlobalBounds( bounds : Bounds2 ) : Bounds2¶

Transforms bounds from our local coordinate frame to the global coordinate frame. If it includes a rotation, the resulting bounding box will include every point that could have been in the original bounding box (and it can be expanded).

NOTE: If there are multiple instances of this Node (e.g. this or one ancestor has two parents), it will fail with an assertion (since the transform wouldn't be uniquely defined).

globalToLocalBounds( bounds : Bounds2 ) : Bounds2¶

Transforms bounds from the global coordinate frame to our local coordinate frame. If it includes a rotation, the resulting bounding box will include every point that could have been in the original bounding box (and it can be expanded).

NOTE: If there are multiple instances of this Node (e.g. this or one ancestor has two parents), it will fail with an assertion (since the transform wouldn't be uniquely defined).

parentToGlobalPoint( point : Vector2 ) : Vector2¶

Transforms a point from our parent coordinate frame to the global coordinate frame.

NOTE: If there are multiple instances of this Node (e.g. this or one ancestor has two parents), it will fail with an assertion (since the transform wouldn't be uniquely defined).

parentToGlobalBounds( bounds : Bounds2 ) : Bounds2¶

Transforms bounds from our parent coordinate frame to the global coordinate frame. If it includes a rotation, the resulting bounding box will include every point that could have been in the original bounding box (and it can be expanded).

NOTE: If there are multiple instances of this Node (e.g. this or one ancestor has two parents), it will fail with an assertion (since the transform wouldn't be uniquely defined).

globalToParentPoint( point : Vector2 ) : Vector2¶

Transforms a point from the global coordinate frame to our parent coordinate frame.

NOTE: If there are multiple instances of this Node (e.g. this or one ancestor has two parents), it will fail with an assertion (since the transform wouldn't be uniquely defined).

globalToParentBounds( bounds : Bounds2 ) : Bounds2¶

Transforms bounds from the global coordinate frame to our parent coordinate frame. If it includes a rotation, the resulting bounding box will include every point that could have been in the original bounding box (and it can be expanded).

NOTE: If there are multiple instances of this Node (e.g. this or one ancestor has two parents), it will fail with an assertion (since the transform wouldn't be uniquely defined).

getGlobalBounds() : Bounds2¶

Returns a bounding box for this Node (and its sub-tree) in the global coordinate frame.

NOTE: If there are multiple instances of this Node (e.g. this or one ancestor has two parents), it will fail with an assertion (since the transform wouldn't be uniquely defined).

NOTE: This requires computation of this node's subtree bounds, which may incur some performance loss.

boundsOf( node : Node ) : Bounds2¶

Returns the bounds of any other Node in our local coordinate frame.

NOTE: If this node or the passed in Node have multiple instances (e.g. this or one ancestor has two parents), it will fail with an assertion.

TODO: Possible to be well-defined and have multiple instances of each. https://github.com/phetsims/scenery/issues/1581

boundsTo( node : Node ) : Bounds2¶

Returns the bounds of this Node in another node's local coordinate frame.

NOTE: If this node or the passed in Node have multiple instances (e.g. this or one ancestor has two parents), it will fail with an assertion.

TODO: Possible to be well-defined and have multiple instances of each. https://github.com/phetsims/scenery/issues/1581

mutate( options? : NodeOptions ) : this¶

Scans the options object for key names that correspond to ES5 setters or other setter functions, and calls those with the values.

For example:

node.mutate( { top: 0, left: 5 } );

will be equivalent to:

node.left = 5; node.top = 0;

In particular, note that the order is different. Mutators will be applied in the order of _mutatorKeys, which can be added to by subtypes.

Additionally, some keys are actually direct function names, like 'scale'. mutate( { scale: 2 } ) will call node.scale( 2 ) instead of activating an ES5 setter directly.

initializePhetioObject( baseOptions : Partial<PhetioObjectOptions>, config : NodeOptions )¶

(protected)

setVoicingVisible( visible : boolean )¶

Set the visibility of this Node with respect to the Voicing feature. Totally separate from graphical display. When visible, this Node and all of its ancestors will be able to speak with Voicing. When voicingVisible is false, all Voicing under this Node will be muted. voicingVisible properties exist in Node.ts because it is useful to set voicingVisible on a root that is composed with Voicing.ts. We cannot put all of the Voicing.ts implementation in Node because that would have a massive memory impact. See Voicing.ts for more information.

isVoicingVisible() : boolean¶

Returns whether this Node is voicingVisible. When true Utterances for this Node can be announced with the Voicing feature, see Voicing.ts for more information.

inspect()¶

Makes this Node's subtree available for inspection.

toString() : string¶

Returns a debugging string that is an attempted serialization of this node's sub-tree.

dispose()¶

Disposes the node, releasing all references that it maintained.

disposeSubtree()¶

Disposes this Node and all other descendant nodes.

NOTE: Use with caution, as you should not re-use any Node touched by this. Not compatible with most DAG techniques.

Instance Properties¶

opacityProperty : TinyProperty<number>¶

(readonly)

Opacity, in the range from 0 (fully transparent) to 1 (fully opaque). NOTE: This is fired synchronously when the opacity of the Node is toggled

disabledOpacityProperty : TinyProperty<number>¶

(readonly)

Disabled opacity, in the range from 0 (fully transparent) to 1 (fully opaque). disabled opacity depends greatly on the value of this.opacity. This acts as a multiplier Combined with the normal opacity ONLY when the node is disabled. Note, the rendered to that value. i.e. read disabledOpacity = .5 as "50% of the current opacity", so if this.opacity is .5, then this renders as 25% opacity, see this.getEffectiveOpacity NOTE: This is fired synchronously when the opacity of the Node is toggled

clipAreaProperty : TinyProperty<Shape | null>¶

(readonly)

This Node and all children will be clipped by this shape (in addition to any other clipping shapes). The shape should be in the local coordinate frame. NOTE: This is fired synchronously when the clipArea of the Node is toggled

voicingVisibleProperty : TinyProperty<boolean>¶

(readonly)

Whether this Node and its subtree can announce content with Voicing and SpeechSynthesis. Though related to Voicing it exists in Node because it is useful to set voicingVisible on a subtree where the root does not compose Voicing. This is not ideal but the entirety of Voicing cannot be composed into every Node because it would produce incorrect behaviors and have a massive memory footprint. See setVoicingVisible() and Voicing.ts for more information about Voicing.

boundsProperty : TinyStaticProperty<Bounds2>¶

(readonly)

[mutable] Bounds for this Node and its children in the "parent" coordinate frame. NOTE: The reference here will not change, we will just notify using the equivalent static notification method. NOTE: This is fired asynchronously (usually as part of a Display.updateDisplay()) when the bounds of the Node is changed.

localBoundsProperty : TinyStaticProperty<Bounds2>¶

(readonly)

[mutable] Bounds for this Node and its children in the "local" coordinate frame. NOTE: The reference here will not change, we will just notify using the equivalent static notification method. NOTE: This is fired asynchronously (usually as part of a Display.updateDisplay()) when the localBounds of the Node is changed.

childBoundsProperty : TinyStaticProperty<Bounds2>¶

(readonly)

[mutable] Bounds just for children of this Node (and sub-trees), in the "local" coordinate frame. NOTE: The reference here will not change, we will just notify using the equivalent static notification method. NOTE: This is fired asynchronously (usually as part of a Display.updateDisplay()) when the childBounds of the Node is changed.

selfBoundsProperty : TinyStaticProperty<Bounds2>¶

(readonly)

[mutable] Bounds just for this Node, in the "local" coordinate frame. NOTE: The reference here will not change, we will just notify using the equivalent static notification method. NOTE: This event can be fired synchronously, and happens with the self-bounds of a Node is changed. This is NOT like the other bounds Properties, which usually fire asynchronously

childrenChangedEmitter : TEmitter¶

(readonly)

This is fired only once for any single operation that may change the children of a Node. For example, if a Node's children are [ a, b ] and setChildren( [ a, x, y, z ] ) is called on it, the childrenChanged event will only be fired once after the entire operation of changing the children is completed.

childInsertedEmitter : TEmitter<[ node: Node, indexOfChild: number ]>¶

(readonly)

For every single added child Node, emits with {Node} Node, {number} indexOfChild

childRemovedEmitter : TEmitter<[ node: Node, indexOfChild: number ]>¶

(readonly)

For every single removed child Node, emits with {Node} Node, {number} indexOfChild

childrenReorderedEmitter : TEmitter<[ minChangedIndex: number, maxChangedIndex: number ]>¶

(readonly)

Provides a given range that may be affected by the reordering

parentAddedEmitter : TEmitter<[ node: Node ]>¶

(readonly)

Fired whenever a parent is added

parentRemovedEmitter : TEmitter<[ node: Node ]>¶

(readonly)

Fired whenever a parent is removed

transformEmitter : TEmitter¶

(readonly)

Fired synchronously when the transform (transformation matrix) of a Node is changed. Any change to a Node's translation/rotation/scale/etc. will trigger this event.

instanceRefreshEmitter : TEmitter¶

(readonly)

Should be emitted when we need to check full metadata updates directly on Instances, to see if we need to change drawable types, etc.

rendererSummaryRefreshEmitter : TEmitter¶

(readonly)

Emitted to when we need to potentially recompute our renderer summary (bitmask flags, or things that could affect descendants)

filterChangeEmitter : TEmitter¶

(readonly)

Emitted to when we change filters (either opacity or generalized filters)

changedInstanceEmitter : TEmitter<[ instance: Instance, added: boolean ]>¶

(readonly)

Fired when an instance is changed (added/removed). CAREFUL!! This is potentially a very dangerous thing to listen to. Instances are updated in an asynchronous batch during updateDisplay(), and it is very important that display updates do not cause changes the scene graph. Thus, this emitter should NEVER trigger a Node's state to change. Currently, all usages of this cause into updates to the audio view, or updates to a separate display (used as an overlay). Please proceed with caution. Most likely you prefer to use the synchronous support of DisplayedTrailsProperty, see https://github.com/phetsims/scenery/issues/1615 and https://github.com/phetsims/scenery/issues/1620 for details.

rootedDisplayChangedEmitter : TEmitter<[ display: Display ]>¶

(readonly)

Fired whenever this node is added as a root to a Display OR when it is removed as a root from a Display (i.e. the Display is disposed).

layoutOptionsChangedEmitter : TEmitter¶

(readonly)

Fired when layoutOptions changes

Static Methods¶

defaultTrailPredicate( node : Node ) : boolean¶

A default for getTrails() searches, returns whether the Node has no parents.

defaultLeafTrailPredicate( node : Node ) : boolean¶

A default for getLeafTrails() searches, returns whether the Node has no parents.

Static Properties¶

REQUIRES_BOUNDS_OPTION_KEYS¶

(readonly)

{Object} - A mapping of all of options that require Bounds to be applied properly. Most often these should be set through mutate in the end of the construcor instead of being passed through super()

NodeIO : IOType¶

DEFAULT_NODE_OPTIONS¶

(readonly)

A mapping of all of the default options provided to Node

Type NodeBoundsBasedTranslationOptions¶

Isolated so that we can delay options that are based on bounds of the Node to after construction. See https://github.com/phetsims/scenery/issues/1332

import type { NodeBoundsBasedTranslationOptions } from 'scenerystack/scenery';

• leftTop?: Vector2
• centerTop?: Vector2
• rightTop?: Vector2
• leftCenter?: Vector2
• center?: Vector2
• rightCenter?: Vector2
• leftBottom?: Vector2
• centerBottom?: Vector2
• rightBottom?: Vector2
• left?: number
• right?: number
• top?: number
• bottom?: number
• centerX?: number
• centerY?: number

Type NodeOptions¶

All base Node options

import type { NodeOptions } from 'scenerystack/scenery';

• children?: Node[]
• cursor?: string | null
• phetioVisiblePropertyInstrumented?: boolean
• visibleProperty?: TReadOnlyProperty<boolean> | null
• visible?: boolean
• pickableProperty?: TReadOnlyProperty<boolean | null> | null
• pickable?: boolean | null
• phetioEnabledPropertyInstrumented?: boolean
• enabledProperty?: TReadOnlyProperty<boolean> | null
• enabled?: boolean
• phetioInputEnabledPropertyInstrumented?: boolean
• inputEnabledProperty?: TReadOnlyProperty<boolean> | null
• inputEnabled?: boolean
• inputListeners?: TInputListener[]
• opacity?: number
• disabledOpacity?: number
• filters?: Filter[]
• excludeInvisibleChildrenFromBounds?: boolean
• interruptSubtreeOnInvisible?: boolean
• layoutOptions?: TLayoutOptions | null
• localBounds?: Bounds2 | null
• maxWidth?: number | null
• maxHeight?: number | null
• renderer?: RendererType
• layerSplit?: boolean
• usesOpacity?: boolean
• cssTransform?: boolean
• excludeInvisible?: boolean
• webglScale?: number | null
• preventFit?: boolean
• mouseArea?: Shape | Bounds2 | null
• touchArea?: Shape | Bounds2 | null
• clipArea?: Shape | null
• transformBounds?: boolean
• visiblePropertyOptions?: PropertyOptions<boolean>
  This option is used to create the instrumented, default PhET-iO visibleProperty. These options should not be provided if a visibleProperty was provided to this Node, though if they are, they will just be ignored. This grace is to support default options across the component hierarchy melding with usages providing a visibleProperty. This option is a bit buried because it can only be used when the Node is being instrumented, which is when the default, instrumented visibleProperty is conditionally created. We don't want to store these on the Node, and thus they aren't support through mutate().
• enabledPropertyOptions?: PropertyOptions<boolean>
• inputEnabledPropertyOptions?: PropertyOptions<boolean>
• & ParallelDOMOptions & NodeTransformOptions

Type NodeTransformOptions¶

All transform options (includes translation options)

import type { NodeTransformOptions } from 'scenerystack/scenery';

• matrix?: Matrix3
• rotation?: number
• scale?: number | Vector2
• & NodeTranslationOptions

Type NodeTranslationOptions¶

All translation options (includes those based on bounds and those that are not)

import type { NodeTranslationOptions } from 'scenerystack/scenery';

• translation?: Vector2
• x?: number
• y?: number
• & NodeBoundsBasedTranslationOptions

Type RendererType¶

import type { RendererType } from 'scenerystack/scenery';

"svg" | "canvas" | "webgl" | "dom" | null

Source Code¶

See the source for Node.ts in the scenery repository.