Text Component

src/graphics/text.js#L4-L29

Events

Invalidate
when the text is changed

By default, text will have the style "10px sans-serif".

Note: An entity with the text component is just text! If you want to write text inside an image, you need one entity for the text and another entity for the image. More tips for writing text inside an image: (1) Use the z-index (from 2D component) to ensure that the text is on top of the image, not the other way around; (2) use .attach() (from 2D component) to glue the text to the image so they move and rotate together.

Note: For DOM (but not canvas) text entities, various font settings (such as text-decoration) can be set using .css() (see DOM component). If you use .css() to set the individual properties which are controlled by .textFont(), .textColor(), or .textAlign(), the text component will set these properties internally as well. However, if you use .css() to set shorthand properties such as font, these will be ignored by the text component.

Note: If you use canvas text with glyphs that are taller than standard letters, portions of the glyphs might be cut off.

Methods

Back to top

.dynamicTextGeneration()

src/graphics/text.js#L200-L225
public this .dynamicTextGeneration(bool dynamicTextOn[, string textUpdateEvent])
dynamicTextOn

A flag that indicates whether dyanamic text should be on or off.

textUpdateEvent

The name of the event which will trigger text to be updated. Defaults to "UpdateFrame". (This parameter does nothing if dynamicTextOn is false.)

Turns on (or off) dynamic text generation for this entity. While dynamic text generation is on, if the .text() method is called with a text generating function, the text will be updated each frame.

If textUpdateEvent is provided, text generation will be bound to that event instead of "UpdateFrame".

The text generating function is invoked with the event object parameter, which the event was triggered with.

Note: Dynamic text generation could cause performance issues when the entity is attached to a Canvas layer.

Example

Crafty.e("2D, DOM, Text, Motion").attr({ x: 100, y: 100, vx: 10 })
    .text(function () { return "My position is " + this._x })
    .dynamicTextGeneration(true)

The above example will update the text with the entities position as it changes.

Back to top

.text()

src/graphics/text.js#L147-L181
public this .text(String text)
text

String of text that will be inserted into the DOM or Canvas element.

public this .text(Function textGenerator[, Any eventData])
textGenerator

A function that returns a string. It will be immediately invoked with the optional eventData in the context of the entity, with the result used as the text to display.

[eventData]

Optional parameter to invoke the function with.

This method will update the text inside the entity.

If you need to reference attributes on the entity itself you can pass a function instead of a string.

If dynamic text generation is turned on, the function will then be reevaluated as necessary.

Example

Crafty.e("2D, DOM, Text").attr({ x: 100, y: 100 }).text("Look at me!!");

Crafty.e("2D, DOM, Text").attr({ x: 100, y: 100 })
    .text(function () { return "My position is " + this._x });

Crafty.e("2D, Canvas, Text").attr({ x: 100, y: 100 }).text("Look at me!!");

Crafty.e("2D, Canvas, Text").attr({ x: 100, y: 100 })
    .text(function () { return "My position is " + this._x });
Back to top

.textAlign()

src/graphics/text.js#L298-L307
public this .textAlign(String alignment)
alignment

The new alignment of the text.

Change the alignment of the text. Valid values are 'start', 'end, 'left', 'center', or 'right'.

Back to top

.textColor()

src/graphics/text.js#L266-L290
public this .textColor(String color)
color

The color in name, hex, rgb or rgba

Change the color of the text. You can use HEX, rgb and rgba colors.

If you want the text to be transparent, you should use rgba where you can define alphaChannel.

Example

Crafty.e("2D, DOM, Text").attr({ x: 100, y: 100 }).text("Look at me!!")
  .textColor('#FF0000');

Crafty.e("2D, Canvas, Text").attr({ x: 100, y: 100 }).text('Look at me!!')
  .textColor('rgba(0, 255, 0, 0.5)');

Crafty.e("2D, Canvas, Text").attr({ x: 100, y: 100 }).text('Look at me!!')
  .textColor('white');
Back to top

.textFont()

src/graphics/text.js#L316-L341

Events

Invalidate
public this .textFont(String key, * value)
key

Property of the entity to modify

value

Value to set the property to

public this .textFont(Object map)
map

Object where the key is the property to modify and the value as the property value

Use this method to set font property of the text entity. Possible values are: type, weight, size, family, lineHeight, and variant.

When rendered by the canvas, lineHeight and variant will be ignored.

Example

Crafty.e("2D, DOM, Text").textFont({ type: 'italic', family: 'Arial' });
Crafty.e("2D, Canvas, Text").textFont({ size: '20px', weight: 'bold' });

Crafty.e("2D, Canvas, Text").textFont("type", "italic");
Crafty.e("2D, Canvas, Text").textFont("type"); // italic
Back to top

.unselectable()

src/graphics/text.js#L368-L386

Events

Invalidate
public this .unselectable()

This method sets the text so that it cannot be selected (highlighted) by dragging. (Canvas text can never be highlighted, so this only matters for DOM text.) Works by changing the css property "user-select" and its variants.

Likewise, this sets the mouseover cursor to be "default" (arrow), not "text" (I-beam)

Example

Crafty.e("2D, DOM, Text").text('This text cannot be highlighted!').unselectable();