API Documentation for: 0.6.0
Show:

Text Class

Extends DisplayObject
Defined in: Text:34
Module: EaselJS

Display one or more lines of dynamic text (not user editable) in the display list. Line wrapping support (using the lineWidth) is very basic, wrapping on spaces and tabs only. Note that as an alternative to Text, you can position HTML text above or below the canvas relative to items in the display list using the localToGlobal method, or using DOMElement.

Please note that Text does not support HTML text, and can only display one font style at a time. To use multiple font styles, you will need to create multiple text instances, and position them manually.

Example

 var text = new createjs.Text("Hello World", "20px Arial", #ff7700");
 text.x = 100;
 text.textBaseline = "alphabetic";

CreateJS Text supports web fonts (the same rules as Canvas). The font must be loaded and supported by the browser before it can be displayed.

Constructor

Text

(
  • [text]
  • [font]
  • [color]
)

Defined in Text:34

Parameters:

  • [text] String optional

    The text to display.

  • [font] String optional

    The font style to use. Any valid value for the CSS font attribute is acceptable (ex. "bold 36px Arial").

  • [color] String optional

    The color to draw the text in. Any valid value for the CSS color attribute is acceptable (ex. "#F00", "red", or "#FF0000").

Methods

_applyFilters

() protected

_applyShadow

(
  • ctx
  • shadow
)
protected

Parameters:

  • ctx CanvasRenderingContext2D
  • shadow Shadow

_drawTextLine

(
  • ctx
  • text
  • y
)
protected

Defined in _drawTextLine:332

Parameters:

_getWorkingContext

() Number protected

Draws multiline text.

Returns:

Number: The number of lines drawn.

_getWorkingContext

() protected

_hasMouseHandler

(
  • typeMask
)
Boolean protected

Indicates whether the display object has a listener of the corresponding event types.

Parameters:

  • typeMask Number

    A bitmask indicating which event types to look for. Bit 1 specifies press & click & double click, bit 2 specifies it should look for mouse over and mouse out. This implementation may change.

Returns:

_testHit

(
  • ctx
)
Boolean protected

Inherited from DisplayObject: _testHit:949

Parameters:

  • ctx CanvasRenderingContext2D

Returns:

_tick

() protected

Inherited from DisplayObject: _tick:937

addEventListener

(
  • type
  • listener
)
Function | Object

Adds the specified event listener.

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    An object with a handleEvent method, or a function that will be called when the event is dispatched.

Returns:

Function | Object: Returns the listener for chaining or assignment.

cache

(
  • x
  • y
  • width
  • height
  • scale
)

Inherited from DisplayObject: cache:628

Draws the display object into a new canvas, which is then used for subsequent draws. For complex content that does not change frequently (ex. a Container with many children that do not move, or a complex vector Shape), this can provide for much faster rendering because the content does not need to be re-rendered each tick. The cached display object can be moved, rotated, faded, etc freely, however if it's content changes, you must manually update the cache by calling updateCache() or cache() again. You must specify the cache area via the x, y, w, and h parameters. This defines the rectangle that will be rendered and cached using this display object's coordinates. For example if you defined a Shape that drew a circle at 0, 0 with a radius of 25, you could call myShape.cache(-25, -25, 50, 50) to cache the full shape.

Parameters:

  • x Number

    The x coordinate origin for the cache region.

  • y Number

    The y coordinate origin for the cache region.

  • width Number

    The width of the cache region.

  • height Number

    The height of the cache region.

  • scale Number

    Optional. The scale at which the cache will be created. For example, if you cache a vector shape using myShape.cache(0,0,100,100,2) then the resulting cacheCanvas will be 200x200 px. This lets you scale and rotate cached elements with greater fidelity. Default is 1.

clone

() Text

Inherited from DisplayObject but overwritten in clone:237

Returns a clone of the Text instance.

Returns:

Text: a clone of the Text instance.

cloneProps

(
  • o
)
protected

Inherited from DisplayObject but overwritten in cloneProps:266

Parameters:

dispatchEvent

(
  • eventObj
  • [target]
)
Boolean

Dispatches the specified event.

Parameters:

  • eventObj Object | String

    An object with a "type" property, or a string type. If a string is used, dispatchEvent will contstruct a generic event object with "type" and "params" properties.

  • [target] Object optional

    The object to use as the target property of the event object. This will default to the dispatching object.

Returns:

Boolean: Returns true if any listener returned true.

draw

(
  • ctx
  • ignoreCache
)

Inherited from DisplayObject but overwritten in draw:183

Draws the Text into the specified context ignoring it's visible, alpha, shadow, and transform. Returns true if the draw was handled (useful for overriding functionality). NOTE: This method is mainly for internal use, though it may be useful for advanced uses.

Parameters:

  • ctx CanvasRenderingContext2D

    The canvas 2D context object to draw into.

  • ignoreCache Boolean

    Indicates whether the draw operation should ignore any current cache. For example, used for drawing the cache (to prevent it from simply drawing an existing cache back into itself).

getCacheDataURL.

()

Returns a data URL for the cache, or null if this display object is not cached. Uses cacheID to ensure a new data URL is not generated if the cache has not changed.

getConcatenatedMatrix

(
  • mtx
)
Matrix2D

Generates a concatenated Matrix2D object representing the combined transform of the display object and all of its parent Containers up to the highest level ancestor (usually the stage). This can be used to transform positions between coordinate spaces, such as with localToGlobal and globalToLocal.

Parameters:

  • mtx Matrix2D

    Optional. A Matrix2D object to populate with the calculated values. If null, a new Matrix object is returned.

Returns:

Matrix2D: a concatenated Matrix2D object representing the combined transform of the display object and all of its parent Containers up to the highest level ancestor (usually the stage).

getMatrix

(
  • matrix
)
Matrix2D

Inherited from DisplayObject: getMatrix:800

Returns a matrix based on this object's transform.

Parameters:

  • matrix Matrix2D

    Optional. A Matrix2D object to populate with the calculated values. If null, a new Matrix object is returned.

Returns:

Matrix2D: A matrix representing this display object's transform.

getMeasuredHeight

() Number

Returns the approximate height of multiline text by multiplying the number of lines against either the lineHeight (if specified) or getMeasuredLineHeight(). Note that this operation requires the text flowing logic to run, which has an associated CPU cost.

Returns:

Number: The approximate height of the drawn multiline text.

getMeasuredLineHeight

() Number

Returns an approximate line height of the text, ignoring the lineHeight property. This is based on the measured width of a "M" character multiplied by 1.2, which approximates em for most fonts.

Returns:

Number: an approximate line height of the text, ignoring the lineHeight property. This is based on the measured width of a "M" character multiplied by 1.2, which approximates em for most fonts.

getMeasuredWidth

() Number

Returns the measured, untransformed width of the text without wrapping.

Returns:

Number: The measured, untransformed width of the text.

getStage

() Stage

Inherited from DisplayObject: getStage:702

Returns the stage that this display object will be rendered on, or null if it has not been added to one.

Returns:

Stage: The Stage instance that the display object is a descendent of. null if the DisplayObject has not been added to a Stage.

globalToLocal

(
  • x
  • y
)
Point

Transforms the specified x and y position from the global (stage) coordinate space to the coordinate space of the display object. For example, this could be used to determine the current mouse position within the display object. Returns a Point instance with x and y properties correlating to the transformed position in the display object's coordinate space.

Parameters:

  • x Number

    The x position on the stage to transform.

  • y Number

    The y position on the stage to transform.

Returns:

Point: A Point instance with x and y properties correlating to the transformed position in the display object's coordinate space.

hasEventListener

(
  • type
)
Boolean

Indicates whether there is at least one listener for the specified event type.

Parameters:

  • type String

    The string type of the event.

Returns:

Boolean: Returns true if there is at least one listener for the specified event.

hitTest

(
  • x
  • y
)
Boolean

Inherited from DisplayObject: hitTest:834

Tests whether the display object intersects the specified local point (ie. draws a pixel with alpha > 0 at the specified position). This ignores the alpha, shadow and compositeOperation of the display object, and all transform properties including regX/Y.

Parameters:

  • x Number

    The x position to check in the display object's local coordinates.

  • y Number

    The y position to check in the display object's local coordinates.

Returns:

Boolean: A Boolean indicting whether a visible portion of the DisplayObject intersect the specified local Point.

initialize

() protected

Inherited from EventDispatcher but overwritten in initialize:152

Initialization method.

isVisible

() Boolean

Inherited from DisplayObject but overwritten in isVisible:164

Returns true or false indicating whether the display object would be visible if drawn to a canvas. This does not account for whether it would be visible within the boundaries of the stage. NOTE: This method is mainly for internal use, though it may be useful for advanced uses.

Returns:

Boolean: Whether the display object would be visible if drawn to a canvas

localToGlobal

(
  • x
  • y
)
Point

Transforms the specified x and y position from the coordinate space of the display object to the global (stage) coordinate space. For example, this could be used to position an HTML label over a specific point on a nested display object. Returns a Point instance with x and y properties correlating to the transformed coordinates on the stage.

Parameters:

  • x Number

    The x position in the source display object to transform.

  • y Number

    The y position in the source display object to transform.

Returns:

Point: A Point instance with x and y properties correlating to the transformed coordinates on the stage.

localToLocal

(
  • x
  • y
  • target
)
Point

Transforms the specified x and y position from the coordinate space of this display object to the coordinate space of the target display object. Returns a Point instance with x and y properties correlating to the transformed position in the target's coordinate space. Effectively the same as calling var pt = this.localToGlobal(x, y); pt = target.globalToLocal(pt.x, pt.y);

Parameters:

  • x Number

    The x position in the source display object to transform.

  • y Number

    The y position on the stage to transform.

  • target DisplayObject

    The target display object to which the coordinates will be transformed.

Returns:

Point: Returns a Point instance with x and y properties correlating to the transformed position in the target's coordinate space.

removeAllEventListeners

(
  • [type]
)

Removes all listeners for the specified type, or all listeners of all types.

Parameters:

  • [type] String optional

    The string type of the event. If omitted, all listeners for all types will be removed.

removeEventListener

(
  • type
  • listener
)

Removes the specified event listener.

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    The listener function or object.

set

(
  • props
)
DisplayObject

Inherited from DisplayObject: set:858

Provides a chainable shortcut method for setting a number of properties on a DisplayObject instance. Ex.
var shape = stage.addChild( new Shape() ).set({graphics:myGraphics, x:100, y:100, alpha:0.5});

Parameters:

  • props Object

    A generic object containing properties to copy to the DisplayObject instance.

Returns:

DisplayObject: Returns The DisplayObject instance the method is called on (useful for chaining calls.)

setTransform

(
  • x
  • y
  • scaleX
  • scaleY
  • rotation
  • skewX
  • skewY
  • regX
  • regY
)
DisplayObject

Shortcut method to quickly set the transform properties on the display object. All parameters are optional. Omitted parameters will have the default value set (ex. 0 for x/y, 1 for scaleX/Y).

Parameters:

Returns:

DisplayObject: Returns this instance. Useful for chaining commands.

setupContext

(
  • ctx
)

Applies this display object's transformation, alpha, globalCompositeOperation, clipping path (mask), and shadow to the specified context. This is typically called prior to draw.

Parameters:

  • ctx CanvasRenderingContext2D

    The canvas 2D to update.

toString

() String

Inherited from EventDispatcher but overwritten in toString:248

Returns a string representation of this object.

Returns:

String: a string representation of the instance.

uncache

()

Inherited from DisplayObject: uncache:681

Clears the current cache. See cache() for more information.

updateCache

(
  • compositeOperation
)

Inherited from DisplayObject: updateCache:658

Redraws the display object to its cache. Calling updateCache without an active cache will throw an error. If compositeOperation is null the current cache will be cleared prior to drawing. Otherwise the display object will be drawn over the existing cache using the specified compositeOperation.

Parameters:

Properties

_cacheDataURL

String protected

Default: null

_cacheDataURLID

Number protected

Default: 0

_cacheOffsetX

Number protected

Default: 0

_cacheOffsetY

Number protected

Default: 0

_cacheScale

Number protected

Inherited from DisplayObject: _cacheScale:523

Default: 1

_listeners

Object protected

Inherited from EventDispatcher: _listeners:90

_matrix

Matrix2D protected

Inherited from DisplayObject: _matrix:547

Default: null

_workingContext

CanvasRenderingContext2D private

Defined in _workingContext:66

alpha

Number

Inherited from DisplayObject: alpha:207

The alpha (transparency) for this display object. 0 is fully transparent, 1 is fully opaque.

Default: 1

cacheCanvas

HTMLCanvasElement | Object

Inherited from DisplayObject: cacheCanvas:215

If a cache is active, this returns the canvas that holds the cached version of this display object. See cache() for more information. READ-ONLY.

Default: null

cacheID

Number

Inherited from DisplayObject: cacheID:453

Returns an ID number that uniquely identifies the current cache for this display object. This can be used to determine if the cache has changed since a previous check.

Default: 0

color

String

Defined in color:88

The color to draw the text in. Any valid value for the CSS color attribute is acceptable (ex. "#F00"). Default is "#000".

compositeOperation

String

The composite operation indicates how the pixels of this display object will be composited with the elements behind it. If null, this property is inherited from the parent container. For more information, read the whatwg spec on compositing.

Default: null

cursor

String

Inherited from DisplayObject: cursor:484

A CSS cursor (ex. "pointer", "help", "text", etc) that will be displayed when the user hovers over this display object. You must enable mouseover events using the stage.enableMouseOver() method to use this property. If null it will use the default cursor.

Default: null

DisplayObject_cloneProps

Function private

DisplayObject_draw

Function private

DisplayObject_initialize

Function private

filters

Array

Inherited from DisplayObject: filters:444

An array of Filter objects to apply to this display object. Filters are only applied / updated when cache() or updateCache() is called on the display object, and only apply to the area that is cached.

Default: null

font

String

Defined in font:81

The font style to use. Any valid value for the CSS font attribute is acceptable (ex. "bold 36px Arial").

hitArea

DisplayObject

Inherited from DisplayObject: hitArea:471

A display object that will be tested when checking mouse interactions or testing getObjectsUnderPoint. The hit area will have its transformation applied relative to this display object's coordinate space (as though the hit test object were a child of this display object and relative to its regX/Y). The hitArea will be tested using only its own alpha value regardless of the alpha value on the target display object, or the target's ancestors (parents). hitArea is NOT currently used by the hitTest() method.

Note that hitArea is not supported for Stage.

Default: null

id

Number

Inherited from DisplayObject: id:224

Unique ID for this display object. Makes display objects easier for some uses.

Default: -1

lineHeight

Number

Defined in lineHeight:129

the value of getMeasuredLineHeight is used.

lineWidth

Number

Defined in lineWidth:136

Indicates the maximum width for a line of text before it is wrapped to multiple lines. If null, the text will not be wrapped.

mask

Shape

Inherited from DisplayObject: mask:462

A Shape instance that defines a vector mask (clipping path) for this display object. The shape's transformation will be applied relative to the display object's parent coordinates (as if it were a child of the parent).

Default: null

maxWidth

Number

Defined in maxWidth:114

shrunk to make it fit in this width. For detailed information view the whatwg spec.

mouseEnabled

Boolean

Indicates whether to include this object when running Stage.getObjectsUnderPoint(), and thus for mouse interactions. Setting this to true for Containers will cause the Container to be returned (not its children) regardless of whether it's mouseChildren property is true.

Default: true

name

String

Inherited from DisplayObject: name:243

An optional name for this display object. Included in toString(). Useful for debugging.

Default: null

onClick

Function deprecated

Inherited from DisplayObject: onClick:392

Deprecated: In favour of the "click" event. Will be removed in a future version.

The onClick callback is called when the user presses down on and then releases the mouse button over this display object. The handler is passed a single param containing the corresponding MouseEvent instance. If an onClick handler is set on a container, it will receive the event if any of its children are clicked.

onDoubleClick

Function deprecated

Inherited from DisplayObject: onDoubleClick:402

Deprecated: In favour of the "dblClick" event. Will be removed in a future version.

The onDoubleClick callback is called when the user double clicks over this display object. The handler is passed a single param containing the corresponding MouseEvent instance. If an onDoubleClick handler is set on a container, it will receive the event if any of its children are clicked.

onMouseOut

Function deprecated

Inherited from DisplayObject: onMouseOut:421

Deprecated: In favour of the "mouseout" event. Will be removed in a future version.

The onMouseOut callback is called when the user rolls off of the display object. You must enable this event using stage.enableMouseOver(). The handler is passed a single param containing the corresponding MouseEvent instance.

onMouseOver

Function deprecated

Inherited from DisplayObject: onMouseOver:412

Deprecated: In favour of the "mouseover" event. Will be removed in a future version.

The onMouseOver callback is called when the user rolls over the display object. You must enable this event using stage.enableMouseOver(). The handler is passed a single param containing the corresponding MouseEvent instance.

onPress

Function deprecated

Inherited from DisplayObject: onPress:381

Deprecated: In favour of the "mousedown" event. Will be removed in a future version.

The onPress callback is called when the user presses down on their mouse over this display object. The handler is passed a single param containing the corresponding MouseEvent instance. You can subscribe to the onMouseMove and onMouseUp callbacks of the event object to receive these events until the user releases the mouse button. If an onPress handler is set on a container, it will receive the event if any of its children are clicked.

onTick

Function deprecated

Inherited from DisplayObject: onTick:430

Deprecated: In favour of the "tick" event. Will be removed in a future version.

The onTick callback is called on each display object on a stage whenever the stage updates. This occurs immediately before the rendering (draw) pass. When stage.update() is called, first all display objects on the stage have onTick called, then all of the display objects are drawn to stage. Children will have their onTick called in order of their depth prior to onTick being called on their parent.

Any parameters passed in to stage.update() are passed on to the onTick() handlers. For example, if you call stage.update("hello"), all of the display objects with a handler will have onTick("hello") called.

outline

Boolean

Defined in outline:123

parent

Container final

Inherited from DisplayObject: parent:251

A reference to the Container or Stage object that contains this display object, or null if it has not been added to one. READ-ONLY.

Default: null

regX

Number

Inherited from DisplayObject: regX:261

The x offset for this display object's registration point. For example, to make a 100x100px Bitmap rotate around it's center, you would set regX and regY to 50.

Default: 0

regY

Number

Inherited from DisplayObject: regY:270

The y offset for this display object's registration point. For example, to make a 100x100px Bitmap rotate around it's center, you would set regX and regY to 50.

Default: 0

rotation

Number

Inherited from DisplayObject: rotation:279

The rotation in degrees for this display object.

Default: 0

scaleX

Number

Inherited from DisplayObject: scaleX:287

The factor to stretch this display object horizontally. For example, setting scaleX to 2 will stretch the display object to twice it's nominal width.

Default: 1

scaleY

Number

Inherited from DisplayObject: scaleY:296

The factor to stretch this display object vertically. For example, setting scaleY to 0.5 will stretch the display object to half it's nominal height.

Default: 1

shadow

Shadow

Inherited from DisplayObject: shadow:321

A shadow object that defines the shadow to render on this display object. Set to null to remove a shadow. If null, this property is inherited from the parent container.

Default: null

skewX

Number

Inherited from DisplayObject: skewX:305

The factor to skew this display object horizontally.

Default: 0

skewY

Number

Inherited from DisplayObject: skewY:313

The factor to skew this display object vertically.

Default: 0

snapToPixel

Boolean deprecated

Inherited from DisplayObject: snapToPixel:365

Deprecated: Hardware acceleration in modern browsers makes this unnecessary.

Indicates whether the display object should have it's x & y position rounded prior to drawing it to stage. Snapping to whole pixels can result in a sharper and faster draw for images (ex. Bitmap & cached objects). This only applies if the enclosing stage has snapPixelsEnabled set to true. The snapToPixel property is true by default for Bitmap and BitmapAnimation instances, and false for all other display objects.

Note that this applies only rounds the display object's local position. You should ensure that all of the display object's ancestors (parent containers) are also on a whole pixel. You can do this by setting the ancestors' snapToPixel property to true.

Default: false

text

String

Defined in text:74

The text to display.

textAlign

String

Defined in textAlign:95

The horizontal text alignment. Any of "start", "end", "left", "right", and "center". For detailed information view the whatwg spec. Default is "left".

textBaseline

String

Defined in textBaseline:105

"ideographic", or "bottom". For detailed information view the whatwg spec. Default is "top".

visible

Boolean

Inherited from DisplayObject: visible:330

Indicates whether this display object should be rendered to the canvas and included when running Stage.getObjectsUnderPoint().

Default: true

x

Number

Inherited from DisplayObject: x:339

The x (horizontal) position of the display object, relative to its parent.

Default: 0

y

Number

Inherited from DisplayObject: y:347

Default: 0

Events

click

Inherited from DisplayObject: click:162

Available since 0.6.0

Dispatched when the user presses their left mouse button and then releases it while over the display object. See the MouseEvent class for a listing of event properties.

dblClick

Inherited from DisplayObject: dblClick:169

Available since 0.6.0

Dispatched when the user double clicks their left mouse button over this display object. See the MouseEvent class for a listing of event properties.

mousedown

Inherited from DisplayObject: mousedown:155

Available since 0.6.0

Dispatched when the user presses their left mouse button over the display object. See the MouseEvent class for a listing of event properties.

mouseout

Inherited from DisplayObject: mouseout:185

Available since 0.6.0

Dispatched when the user's mouse rolls out of this display object. This event must be enabled using enableMouseOver. See the MouseEvent class for a listing of event properties.

mouseover

Inherited from DisplayObject: mouseover:176

Available since 0.6.0

Dispatched when the user's mouse rolls over this display object. This event must be enabled using Stage.enableMouseOver. See the MouseEvent class for a listing of event properties.

tick

Inherited from DisplayObject: tick:193

Available since 0.6.0

Dispatched on each display object on a stage whenever the stage updates. This occurs immediately before the rendering (draw) pass. When update is called, first all display objects on the stage dispatch the tick event, then all of the display objects are drawn to stage. Children will have their tick event dispatched in order of their depth prior to the event being dispatched on their parent.

Event Payload:

  • target Object

    The object that dispatched the event.

  • type String

    The event type.

  • params Array

    An array containing any arguments that were passed to the Stage.update() method. For example if you called stage.update("hello"), then the params would be ["hello"].