Skip to content

Text

Overview

Displays text that can be filled/stroked.

For many font/text-related properties, it's helpful to understand the CSS equivalents (http://www.w3.org/TR/css3-fonts/).

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

Class Text

import { Text } from 'scenerystack/scenery';

Constructor

new Text( string : string | number | TReadOnlyProperty<string>, options? : TextOptions )

Instance Methods

mutate( options? : TextOptions ) : this

setString( string : string | number ) : this

Sets the string displayed by our node.

@param string - The string to display. If it's a number, it will be cast to a string

getString() : string

Returns the string displayed by our text Node.

NOTE: If a number was provided to setString(), it will not be returned as a number here.

getRenderedText() : string

Returns a potentially modified version of this.string, where spaces are replaced with non-breaking spaces, and embedding marks are potentially simplified.

setStringProperty( newTarget : TReadOnlyProperty<string> | null ) : this

See documentation for Node.setVisibleProperty, except this is for the text string.

NOTE: Setting the .string after passing a truly read-only Property will fail at runtime. We choose to allow passing in read-only Properties for convenience.

getStringProperty() : TProperty<string>

Like Node.getVisibleProperty(), but for the text string. Note this is not the same as the Property provided in setStringProperty. Thus is the nature of TinyForwardingProperty.

initializePhetioObject( baseOptions : Partial<PhetioObjectOptions>, config : TextOptions )

(protected)

See documentation and comments in Node.initializePhetioObject

getPhetioMouseHitTarget( fromLinking ) : PhetioObject | 'phetioNotSelectable'

Text supports a "string" selection mode, in which it will map to its stringProperty (if applicable), otherwise is uses the default mouse-hit target from the supertype.

setBoundsMethod( method : TextBoundsMethod ) : this

Sets the method that is used to determine bounds from the text.

Possible values: - 'fast' - Measures using SVG, can be inaccurate. Can't be rendered in Canvas. - 'fastCanvas' - Like 'fast', but allows rendering in Canvas. - 'accurate' - Recursively renders to a Canvas to accurately determine bounds. Slow, but works with all renderers. - 'hybrid' - [default] Cache SVG height, and uses Canvas measureText for the width.

TODO: deprecate fast/fastCanvas options? https://github.com/phetsims/scenery/issues/1581

NOTE: Most of these are unfortunately not hard guarantees that content is all inside of the returned bounds. 'accurate' should probably be the only one where that guarantee can be assumed. Things like cyrillic in italic, combining marks and other unicode features can fail to be detected. This is particularly relevant for the height, as certain stacked accent marks or descenders can go outside of the prescribed range, and fast/canvasCanvas/hybrid will always return the same vertical bounds (top and bottom) for a given font when the text isn't the empty string.

getBoundsMethod() : TextBoundsMethod

Returns the current method to estimate the bounds of the text. See setBoundsMethod() for more information.

getTextRendererBitmask() : number

(protected)

Returns a bitmask representing the supported renderers for the current configuration of the Text node.

@returns - A bitmask that includes supported renderers, see Renderer for details.

invalidateSupportedRenderers()

Triggers a check and update for what renderers the current configuration supports. This should be called whenever something that could potentially change supported renderers happen (which can be isHTML, boundsMethod, etc.)

updateSelfBounds() : boolean

(protected)

Computes a more efficient selfBounds for our Text.

@returns - Whether the self bounds changed.

canvasPaintSelf( wrapper : CanvasContextWrapper, matrix : Matrix3 )

(protected)

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.

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)

We need to add additional padding around the text when the text is in a container that could clip things badly if the text is larger than the normal bounds computation.

setFont( font : Font | string ) : this

Sets the font of the Text node.

This can either be a Scenery Font object, or a string. The string format is described by Font's constructor, and is basically the CSS3 font shortcut format. If a string is provided, it will be wrapped with a new (immutable) Scenery Font object.

getFont() : string

Returns a string representation of the current Font.

This returns the CSS3 font shortcut that is a possible input to setFont(). See Font's constructor for detailed information on the ordering of information.

NOTE: If a Font object was provided to setFont(), this will not currently return it. TODO: Can we refactor so we can have access to (a) the Font object, and possibly (b) the initially provided value. https://github.com/phetsims/scenery/issues/1581

setFontWeight( weight : FontWeight | number ) : this

Sets the weight of this node's font.

The font weight supports the following options: 'normal', 'bold', 'bolder', 'lighter', '100', '200', '300', '400', '500', '600', '700', '800', '900', or a number that when cast to a string will be one of the strings above.

getFontWeight() : FontWeight

Returns the weight of this node's font, see setFontWeight() for details.

NOTE: If a numeric weight was passed in, it has been cast to a string, and a string will be returned here.

setFontFamily( family : string ) : this

Sets the family of this node's font.

@param family - A comma-separated list of families, which can include generic families (preferably at the end) such as 'serif', 'sans-serif', 'cursive', 'fantasy' and 'monospace'. If there is any question about escaping (such as spaces in a font name), the family should be surrounded by double quotes.

getFontFamily() : string

Returns the family of this node's font, see setFontFamily() for details.

setFontStretch( stretch : FontStretch ) : this

Sets the stretch of this node's font.

The font stretch supports the following options: 'normal', 'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'semi-expanded', 'expanded', 'extra-expanded' or 'ultra-expanded'

getFontStretch() : FontStretch

Returns the stretch of this node's font, see setFontStretch() for details.

setFontStyle( style : FontStyle ) : this

Sets the style of this node's font.

The font style supports the following options: 'normal', 'italic' or 'oblique'

getFontStyle() : FontStyle

Returns the style of this node's font, see setFontStyle() for details.

setFontSize( size : string | number ) : this

Sets the size of this node's font.

The size can either be a number (created as a quantity of 'px'), or any general CSS font-size string (for example, '30pt', '5em', etc.)

getFontSize() : string

Returns the size of this node's font, see setFontSize() for details.

NOTE: If a numeric size was passed in, it has been converted to a string with 'px', and a string will be returned here.

isPainted() : boolean

Whether this Node itself is painted (displays something itself).

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'.

dispose()

Static Methods

embeddedDebugString( string : string ) : string

Replaces embedding mark characters with visible strings. Useful for debugging for strings with embedding marks.

@returns - With embedding marks replaced.

simplifyEmbeddingMarks( string : string ) : string

Returns a (potentially) modified string where embedding marks have been simplified.

This simplification wouldn't usually be necessary, but we need to prevent cases like https://github.com/phetsims/scenery/issues/520 where Edge decides to turn [POP][LTR] (after another [LTR]) into a 'box' character, when nothing should be rendered.

This will remove redundant nesting: e.g. [LTR][LTR]boo[POP][POP] => [LTR]boo[POP]) and will also combine adjacent directions: e.g. [LTR]Mail[POP][LTR]Man[POP] => [LTR]MailMan[Pop]

Note that it will NOT combine in this way if there was a space between the two LTRs: e.g. [LTR]Mail[POP] [LTR]Man[Pop]) as in the general case, we'll want to preserve the break there between embeddings.

TODO: A stack-based implementation that doesn't create a bunch of objects/closures would be nice for performance.

Static Properties

STRING_PROPERTY_NAME

(readonly)

STRING_PROPERTY_TANDEM_NAME

(readonly)

TextIO : IOType

Type TextBoundsMethod

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

"fast" | "fastCanvas" | "accurate" | "hybrid"

Type TextOptions

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

Source Code

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