HighlightPath¶

Overview¶

A Node for a focus highlight that takes a shape and creates a Path with the default styling of a focus highlight for a11y. The FocusHighlight has two paths. The FocusHighlight path is an 'outer' highlight that is a little lighter in color and transparency. It as a child 'inner' path that is darker and more opaque, which gives the focus highlight the illusion that it fades out.

@author Michael Kauzmann (PhET Interactive Simulations) @author Jesse Greenberg (PhET Interactive Simulations)

Class HighlightPath¶

import { HighlightPath } from 'scenerystack/scenery';

Constructor¶

new HighlightPath( shape : InputShape | TReadOnlyProperty<InputShape>, providedOptions? : HighlightPathOptions )¶

Instance Methods¶

mutateWithInnerHighlight( options : PathOptions )¶

Mutating convenience function to mutate both the innerHighlightPath and outerHighlightPath.

setDashed( dashOn : boolean )¶

Mutate both inner and outer Paths to make the stroke dashed by using lineDash.

setShape( shape : InputShape ) : this¶

Update the shape of the child path (inner highlight) and this path (outer highlight). Note for the purposes of chaining the outer Path (this) is returned, not the inner Path.

updateLineWidth( matrix : Matrix3 )¶

Update the line width of both Paths based on transform of this Path, or another Node passed in (usually the node that is being highlighted). Can be overridden by the options passed in the constructor.

getOuterLineWidth( matrix : Matrix3 ) : number¶

Given a transformation matrix, return the lineWidth of this focus highlight (unless a custom lineWidth was specified in the options).

Note - this takes a matrix3 instead of a Node because that is already computed by the highlight overlay and we can avoid the extra computation of the Node's local-to-global matrix.

getInnerLineWidth( matrix : Matrix3 ) : number¶

Given a transformation matrix, return the lineWidth of this focus highlight (unless a custom lineWidth was specified in the options).

Note - this takes a matrix3 instead of a Node because that is already computed by the highlight overlay and we can avoid the extra computation of the Node's local-to-global matrix.

setInnerHighlightColor( color : TPaint )¶

Set the inner color of this focus highlight.

getInnerHighlightColor() : TPaint¶

Get the inner color of this focus highlight path.

setOuterHighlightColor( color : TPaint )¶

Set the outer color of this focus highlight.

getOuterHighlightColor() : TPaint¶

Get the color of the outer highlight for this HighlightPath

Instance Properties¶

highlightChangedEmitter : Emitter¶

(readonly)

Emits whenever this highlight changes.

transformSourceNode : Node | null¶

(readonly)

See option for documentation.

innerHighlightPath : Path¶

(protected, readonly)

The 'inner' focus highlight, the (by default) slightly darker and more opaque path that is on the inside of the outer path to give the focus highlight a 'fade-out' appearance

Static Methods¶

getDilationCoefficient( matrix : Matrix3 ) : number¶

Get the coefficient needed to scale the highlights bounds to surround the node being highlighted elegantly. The highlight is based on a Node's bounds, so it should be scaled out a certain amount so that there is white space between the edge of the component and the beginning (inside edge) of the focusHighlight

getDefaultDilationCoefficient() : number¶

Returns the highlight dilation coefficient when there is no transformation.

getDefaultGroupDilationCoefficient() : number¶

Returns the highlight dilation coefficient for a group focus highlight, which is a bit larger than the typical dilation coefficient.

getDefaultHighlightLineWidth() : number¶

The default highlight line width. The outer line width is wider and can be used as a value for layout. This is the value of the line width without any transformation. The actual value in the global coordinate frame may change based on the pan/zoom of the screen.

getGroupDilationCoefficient( matrix : Matrix3 ) : number¶

Get the dilation coefficient for a group focus highlight, which extends even further beyond node bounds than a regular focus highlight. The group focus highlight goes around a node whenever its descendant has focus, so this will always surround the normal focus highlight.

getCorrectiveScalingMatrix() : Matrix3¶

Returns a final matrix to use to scale a highlight so that it is in a consistent size relative to the application layout bounds.

Static Properties¶

OUTER_FOCUS_COLOR¶

(readonly)

INNER_FOCUS_COLOR¶

(readonly)

INNER_LIGHT_GROUP_FOCUS_COLOR¶

(readonly)

OUTER_LIGHT_GROUP_FOCUS_COLOR¶

(readonly)

INNER_DARK_GROUP_FOCUS_COLOR¶

(readonly)

OUTER_DARK_GROUP_FOCUS_COLOR¶

(readonly)

GROUP_OUTER_LINE_WIDTH¶

(readonly)

GROUP_INNER_LINE_WIDTH¶

(readonly)

layoutScale¶

A scalar describing the layout scale of your application. Highlight line widths are corrected by the layout scale so that they have the same sizes relative to the size of the application.

Type HighlightPathOptions¶

The stroke and linewidth of this path are set with outerLineWidth and outerStroke.

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

• outerStroke?: TPaint
  strokes for each highlight
• innerStroke?: TPaint
• outerLineWidth?: number | null
  lineWidth for each highlight. If null, the lineWidth will be calculated from the transform of the Node of this highlight (or the transformSourceNode).
• innerLineWidth?: number | null
• dashed?: boolean
  If true, the highlight will appear dashed with a lineDash effect. Used often by PhET to indicate that an interactive component is currently picked up and being manipulated by the user.
• transformSourceNode?: Node | null
  If specified, this HighlightPath will reposition with transform changes along the unique trail to this source Node. Otherwise you will have to position this highlight node yourself.
• & StrictOmit<PathOptions, "stroke" | "lineWidth">

Source Code¶

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