Skip to content

AlignBox

Overview

A Node that will align child (content) Node within a specific bounding box.

If a custom alignBounds is provided, content will be aligned within that bounding box. Otherwise, it will be aligned within a bounding box with the left-top corner of (0,0) of the necessary size to include both the content and all the margins.

Preferred sizes will set the alignBounds (to a minimum x/y of 0, and a maximum x/y of preferredWidth/preferredHeight)

If alignBounds or a specific preferred size have not been set yet, the AlignBox will not adjust things on that dimension.

There are four margins: left, right, top, bottom. They can be set independently, or multiple can be set at the same time (xMargin, yMargin and margin).

AlignBox will only adjust the preferred size of its content if: 1. The align for the axis is 'stretch' 2. The content is sizable for that axis Additionally, if the above is true and there is an associated AlignGroup, the minimum size of the content will be used to compute the AlignGroup's size (instead of current counts).

NOTE: AlignBox resize may not happen immediately, and may be delayed until bounds of a alignBox's child occurs. layout updates can be forced with invalidateAlignment(). If the alignBox's content that changed is connected to a Scenery display, its bounds will update when Display.updateDisplay() will called, so this will guarantee that the layout will be applied before it is displayed. alignBox.getBounds() will not force a refresh, and may return stale bounds.

See https://phetsims.github.io/scenery/doc/layout#AlignBox for details

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

Class AlignBox

import { AlignBox } from 'scenerystack/scenery';

Constructor

new AlignBox( content : Node, providedOptions? : AlignBoxOptions )

Instance Methods

invalidateAlignment()

Triggers recomputation of the alignment. Should be called if it needs to be refreshed.

NOTE: alignBox.getBounds() will not trigger a bounds validation for our content, and thus WILL NOT trigger layout. content.getBounds() should trigger it, but invalidateAligment() is the preferred method for forcing a re-check.

setAlignBounds( alignBounds : Bounds2 | null ) : this

Sets the alignment bounds (the bounds in which our content will be aligned). If null, AlignBox will act as if the alignment bounds have a left-top corner of (0,0) and with a width/height that fits the content and bounds.

NOTE: If the group is a valid AlignGroup, it will be responsible for setting the alignBounds.

getAlignBounds() : Bounds2 | null

Returns the current alignment bounds (if available, see setAlignBounds for details).

setGroup( group : AlignGroup | null ) : this

Sets the attachment to an AlignGroup. When attached, our alignBounds will be controlled by the group.

getGroup() : AlignGroup | null

Returns the attached alignment group (if one exists), or null otherwise.

setXAlign( xAlign : AlignBoxXAlign ) : this

Sets the horizontal alignment of this box.

getXAlign() : AlignBoxXAlign

Returns the current horizontal alignment of this box.

setYAlign( yAlign : AlignBoxYAlign ) : this

Sets the vertical alignment of this box.

getYAlign() : AlignBoxYAlign

Returns the current vertical alignment of this box.

getAlign() : AlignBoxXAlign & AlignBoxYAlign

setAlign( value : AlignBoxXAlign & AlignBoxYAlign ) : this

setMargin( margin : number ) : this

Sets the margin of this box (setting margin values for all sides at once).

This margin is the minimum amount of horizontal space that will exist between the content the sides of this box.

getMargin() : number

Returns the current margin of this box (assuming all margin values are the same).

setXMargin( xMargin : number ) : this

Sets the horizontal margin of this box (setting both left and right margins at once).

This margin is the minimum amount of horizontal space that will exist between the content and the left and right sides of this box.

getXMargin() : number

Returns the current horizontal margin of this box (assuming the left and right margins are the same).

setYMargin( yMargin : number ) : this

Sets the vertical margin of this box (setting both top and bottom margins at once).

This margin is the minimum amount of vertical space that will exist between the content and the top and bottom sides of this box.

getYMargin() : number

Returns the current vertical margin of this box (assuming the top and bottom margins are the same).

setLeftMargin( leftMargin : number ) : this

Sets the left margin of this box.

This margin is the minimum amount of horizontal space that will exist between the content and the left side of the box.

getLeftMargin() : number

Returns the current left margin of this box.

setRightMargin( rightMargin : number ) : this

Sets the right margin of this box.

This margin is the minimum amount of horizontal space that will exist between the content and the right side of the container.

getRightMargin() : number

Returns the current right margin of this box.

setTopMargin( topMargin : number ) : this

Sets the top margin of this box.

This margin is the minimum amount of vertical space that will exist between the content and the top side of the container.

getTopMargin() : number

Returns the current top margin of this box.

setBottomMargin( bottomMargin : number ) : this

Sets the bottom margin of this box.

This margin is the minimum amount of vertical space that will exist between the content and the bottom side of the container.

getBottomMargin() : number

Returns the current bottom margin of this box.

getContent() : Node

getContentBounds() : Bounds2

Returns the bounding box of this box's content. This will include any margins.

getMinimumWidth() : number

getMinimumHeight() : number

dispose()

Disposes this box, releasing listeners and any references to an AlignGroup

mutate( options? : AlignBoxOptions ) : this

Type AlignBoxOptions

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

Type AlignBoxXAlign

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

( typeof AlignBoxXAlignValues )[number]

Type AlignBoxYAlign

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

( typeof AlignBoxYAlignValues )[number]

Source Code

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