Class: ElementComponent

ElementComponents are used to construct user interfaces. The ElementComponent#type property can be configured in 3 main ways: as a text element, as an image element or as a group element. If the ElementComponent has a ScreenComponent ancestor in the hierarchy, it will be transformed with respect to the coordinate system of the screen. If there is no ScreenComponent ancestor, the ElementComponent will be transformed like any other entity.

You should never need to use the ElementComponent constructor. To add an ElementComponent to a Entity, use Entity#addComponent:

// Add an element component to an entity with the default options
const entity = Entity()
entity.addComponent('element') // This defaults to a 'group' element

To create a simple text-based element:

entity.addComponent('element', {
  anchor: new Vec4(0.5, 0.5, 0.5, 0.5), // centered anchor
  fontAsset: fontAsset,
  fontSize: 128,
  pivot: new Vec2(0.5, 0.5), // centered pivot
  text: 'Hello World!',
  type: ELEMENTTYPE_TEXT
})

Once the ElementComponent is added to the entity, you can set and get any of its properties:

entity.element.color = Color.RED // Set the element's color to red

console.log(entity.element.color) // Get the element's color and print it

Properties

entity

entity: Entity

The Entity that this Component is attached to.

Inherited from

Component.entity

screen

screen: null | Entity

The Entity with a ScreenComponent that this component belongs to. This is automatically set when the component is a child of a ScreenComponent.

system

system: ComponentSystem

The ComponentSystem used to create this Component.

Inherited from

Component.system

aabb

Get Signature

get aabb(): null | BoundingBox

Gets the world space axis-aligned bounding box for this element component.

Returns

null | BoundingBox

alignment

Get Signature

get alignment(): Vec2

Gets the horizontal and vertical alignment of the text.

Returns

Vec2

Set Signature

set alignment(arg: Vec2): void

Sets the horizontal and vertical alignment of the text. Values range from 0 to 1 where [0, 0] is the bottom left and [1, 1] is the top right. Only works for ELEMENTTYPE_TEXT types.

Parameters

arg

Vec2

Returns

void

anchor

Get Signature

get anchor(): number[] | Vec4

Gets the anchor for this element component.

Returns

number | Vec4

Set Signature

set anchor(value: number[] | Vec4): void

Sets the anchor for this element component. Specifies where the left, bottom, right and top edges of the component are anchored relative to its parent. Each value ranges from 0 to 1. e.g. a value of [0, 0, 0, 0] means that the element will be anchored to the bottom left of its parent. A value of [1, 1, 1, 1] means it will be anchored to the top right. A split anchor is when the left-right or top-bottom pairs of the anchor are not equal. In that case, the component will be resized to cover that entire area. For example, a value of [0, 0, 1, 1] will make the component resize exactly as its parent.

Examples

this.entity.element.anchor = new Vec4(Math.random() * 0.1, 0, 1, 0)

this.entity.element.anchor = [
  Math.random() * 0.1,
  0,
  1,
  0
]

Parameters

value

number | Vec4

Returns

void

autoFitHeight

Get Signature

get autoFitHeight(): boolean

Gets whether the font size and line height will scale so that the text fits inside the height of the Element.

Returns

boolean

Set Signature

set autoFitHeight(arg: boolean): void

Sets whether the font size and line height will scale so that the text fits inside the height of the Element. The font size will be scaled between minFontSize and maxFontSize. The value of autoFitHeight will be ignored if autoHeight is true.

Parameters

arg

boolean

Returns

void

autoFitWidth

Get Signature

get autoFitWidth(): boolean

Gets whether the font size and line height will scale so that the text fits inside the width of the Element.

Returns

boolean

Set Signature

set autoFitWidth(arg: boolean): void

Sets whether the font size and line height will scale so that the text fits inside the width of the Element. The font size will be scaled between minFontSize and maxFontSize. The value of autoFitWidth will be ignored if autoWidth is true.

Parameters

arg

boolean

Returns

void

autoHeight

Get Signature

get autoHeight(): boolean

Gets whether to automatically set the height of the component to be the same as the textHeight.

Returns

boolean

Set Signature

set autoHeight(arg: boolean): void

Sets whether to automatically set the height of the component to be the same as the textHeight. Only works for ELEMENTTYPE_TEXT types.

Parameters

arg

boolean

Returns

void

autoWidth

Get Signature

get autoWidth(): boolean

Gets whether to automatically set the width of the component to be the same as the textWidth.

Returns

boolean

Set Signature

set autoWidth(arg: boolean): void

Sets whether to automatically set the width of the component to be the same as the textWidth. Only works for ELEMENTTYPE_TEXT types.

Parameters

arg

boolean

Returns

void

batchGroupId

Get Signature

get batchGroupId(): number

Gets the batch group (see BatchGroup) for this element.

Returns

number

Set Signature

set batchGroupId(value: number): void

Sets the batch group (see BatchGroup) for this element. Default is -1 (no group).

Parameters

value

number

Returns

void

bottom

Get Signature

get bottom(): number

Gets the distance from the bottom edge of the anchor.

Returns

number

Set Signature

set bottom(value: number): void

Sets the distance from the bottom edge of the anchor. Can be used in combination with a split anchor to make the component's top edge always be 'top' units away from the top.

Parameters

value

number

Returns

void

calculatedHeight

Get Signature

get calculatedHeight(): number

Gets the height at which the element will be rendered.

Returns

number

Set Signature

set calculatedHeight(value: number): void

Sets the height at which the element will be rendered. In most cases this will be the same as height. However, in some cases the engine may calculate a different height for the element, such as when the element is under the control of a LayoutGroupComponent. In these scenarios, calculatedHeight may be smaller or larger than the height that was set in Build Mode.

Parameters

value

number

Returns

void

calculatedWidth

Get Signature

get calculatedWidth(): number

Gets the width at which the element will be rendered.

Returns

number

Set Signature

set calculatedWidth(value: number): void

Sets the width at which the element will be rendered. In most cases this will be the same as width. However, in some cases the engine may calculate a different width for the element, such as when the element is under the control of a LayoutGroupComponent. In these scenarios, calculatedWidth may be smaller or larger than the width that was set in the Build Mode.

Parameters

value

number

Returns

void

canvasCorners

Get Signature

get canvasCorners(): Vec2[]

Gets the array of 4 Vec2s that represent the bottom left, bottom right, top right and top left corners of the component in canvas pixels. Only works for screen space element components.

Returns

Vec2

color

Get Signature

get color(): Color

Gets the color of the element.

Returns

Color

Set Signature

set color(arg: Color): void

Sets the color of the image for ELEMENTTYPE_IMAGE types or the color of the text for ELEMENTTYPE_TEXT types.

Parameters

arg

Color

Returns

void

drawOrder

Get Signature

get drawOrder(): number

Gets the draw order of the component.

Returns

number

Set Signature

set drawOrder(value: number): void

Sets the draw order of the component. A higher value means that the component will be rendered on top of other components.

Parameters

value

number

Returns

void

enabled

Get Signature

get enabled(): boolean

Gets the enabled state of the component.

Returns

boolean

Set Signature

set enabled(value: boolean): void

Sets the enabled state of the component.

Parameters

value

boolean

Returns

void

Overrides

Component.enabled

enableMarkup

Get Signature

get enableMarkup(): boolean

Gets whether markup processing is enabled for this element.

Returns

boolean

Set Signature

set enableMarkup(arg: boolean): void

Sets whether markup processing is enabled for this element. Only works for ELEMENTTYPE_TEXT types. Defaults to false.

Parameters

arg

boolean

Returns

void

fitMode

Get Signature

get fitMode(): string

Gets the fit mode of the element.

Returns

string

Set Signature

set fitMode(value: string): void

Sets the fit mode of the element. Controls how the content should be fitted and preserve the aspect ratio of the source texture or sprite. Only works for ELEMENTTYPE_IMAGE types. Can be:

• FITMODE_STRETCH: Fit the content exactly to Element's bounding box.
• FITMODE_CONTAIN: Fit the content within the Element's bounding box while preserving its Aspect Ratio.
• FITMODE_COVER: Fit the content to cover the entire Element's bounding box while preserving its Aspect Ratio.

Parameters

value

string

Returns

void

font

Get Signature

get font(): Font | CanvasFont

Gets the font used for rendering the text.

Returns

Font | CanvasFont

Set Signature

set font(arg: Font | CanvasFont): void

Sets the font used for rendering the text. Only works for ELEMENTTYPE_TEXT types.

Parameters

arg

Font | CanvasFont

Returns

void

fontAsset

Get Signature

get fontAsset(): number

Gets the id of the font asset used for rendering the text.

Returns

number

Set Signature

set fontAsset(arg: number): void

Sets the id of the font asset used for rendering the text. Only works for ELEMENTTYPE_TEXT types.

Parameters

arg

number

Returns

void

fontSize

Get Signature

get fontSize(): number

Gets the size of the font.

Returns

number

Set Signature

set fontSize(arg: number): void

Sets the size of the font. Only works for ELEMENTTYPE_TEXT types.

Parameters

arg

number

Returns

void

height

Get Signature

get height(): number

Gets the height of the element.

Returns

number

Set Signature

set height(value: number): void

Sets the height of the element as set in Build Mode. Note that in some cases this may not reflect the true height at which the element is rendered, such as when the element is under the control of a LayoutGroupComponent. See calculatedHeight in order to ensure you are reading the true height at which the element will be rendered.

Parameters

value

number

Returns

void

key

Get Signature

get key(): string

Gets the localization key to use to get the localized text from Application#i18n.

Returns

string

Set Signature

set key(arg: string): void

Sets the localization key to use to get the localized text from Application#i18n. Only works for ELEMENTTYPE_TEXT types.

Parameters

arg

string

Returns

void

layers

Get Signature

get layers(): number[]

Gets the array of layer IDs (Layer#id) to which this element belongs.

Returns

number

Set Signature

set layers(value: number[]): void

Sets the array of layer IDs (Layer#id) to which this element should belong. Don't push, pop, splice or modify this array. If you want to change it, set a new one instead.

Parameters

value

number

Returns

void

left

Get Signature

get left(): number

Gets the distance from the left edge of the anchor.

Returns

number

Set Signature

set left(value: number): void

Sets the distance from the left edge of the anchor. Can be used in combination with a split anchor to make the component's left edge always be 'left' units away from the left.

Parameters

value

number

Returns

void

lineHeight

Get Signature

get lineHeight(): number

Gets the height of each line of text.

Returns

number

Set Signature

set lineHeight(arg: number): void

Sets the height of each line of text. Only works for ELEMENTTYPE_TEXT types.

Parameters

arg

number

Returns

void

margin

Get Signature

get margin(): Vec4

Gets the distance from the left, bottom, right and top edges of the anchor.

Returns

Vec4

Set Signature

set margin(value: Vec4): void

Sets the distance from the left, bottom, right and top edges of the anchor. For example, if we are using a split anchor like [0, 0, 1, 1] and the margin is [0, 0, 0, 0] then the component will be the same width and height as its parent.

Parameters

value

Vec4

Returns

void

mask

Get Signature

get mask(): boolean

Gets whether the Image Element should be treated as a mask.

Returns

boolean

Set Signature

set mask(arg: boolean): void

Sets whether the Image Element should be treated as a mask. Masks do not render into the scene, but instead limit child elements to only be rendered where this element is rendered.

Parameters

arg

boolean

Returns

void

material

Get Signature

get material(): Material

Gets the material to use when rendering an image.

Returns

Material

Set Signature

set material(arg: Material): void

Sets the material to use when rendering an image. Only works for ELEMENTTYPE_IMAGE types.

Parameters

arg

Material

Returns

void

materialAsset

Get Signature

get materialAsset(): number

Gets the id of the material asset to use when rendering an image.

Returns

number

Set Signature

set materialAsset(arg: number): void

Sets the id of the material asset to use when rendering an image. Only works for ELEMENTTYPE_IMAGE types.

Parameters

arg

number

Returns

void

maxFontSize

Get Signature

get maxFontSize(): number

Gets the maximum size that the font can scale to when autoFitWidth or autoFitHeight are true.

Returns

number

Set Signature

set maxFontSize(arg: number): void

Sets the maximum size that the font can scale to when autoFitWidth or autoFitHeight are true.

Parameters

arg

number

Returns

void

maxLines

Get Signature

get maxLines(): null | number

Gets the maximum number of lines that the Element can wrap to. Returns null for unlimited lines.

Returns

null | number

Set Signature

set maxLines(arg: null | number): void

Sets the maximum number of lines that the Element can wrap to. Any leftover text will be appended to the last line. Set this to null to allow unlimited lines.

Parameters

arg

null | number

Returns

void

minFontSize

Get Signature

get minFontSize(): number

Gets the minimum size that the font can scale to when autoFitWidth or autoFitHeight are true.

Returns

number

Set Signature

set minFontSize(arg: number): void

Sets the minimum size that the font can scale to when autoFitWidth or autoFitHeight are true.

Parameters

arg

number

Returns

void

opacity

Get Signature

get opacity(): number

Gets the opacity of the element.

Returns

number

Set Signature

set opacity(arg: number): void

Sets the opacity of the element. This works for both ELEMENTTYPE_IMAGE and ELEMENTTYPE_TEXT element types.

Parameters

arg

number

Returns

void

outlineColor

Get Signature

get outlineColor(): Color

Gets the text outline effect color and opacity.

Returns

Color

Set Signature

set outlineColor(arg: Color): void

Sets the text outline effect color and opacity. Only works for ELEMENTTYPE_TEXT types.

Parameters

arg

Color

Returns

void

outlineThickness

Get Signature

get outlineThickness(): number

Gets the width of the text outline effect.

Returns

number

Set Signature

set outlineThickness(arg: number): void

Sets the width of the text outline effect. Only works for ELEMENTTYPE_TEXT types.

Parameters

arg

number

Returns

void

pivot

Get Signature

get pivot(): number[] | Vec2

Gets the position of the pivot of the component relative to its anchor.

Returns

number | Vec2

Set Signature

set pivot(value: number[] | Vec2): void

Sets the position of the pivot of the component relative to its anchor. Each value ranges from 0 to 1 where [0, 0] is the bottom left and [1, 1] is the top right.

Examples

this.entity.element.pivot = [
  Math.random() * 0.1,
  Math.random() * 0.1
]

this.entity.element.pivot = new Vec2(Math.random() * 0.1, Math.random() * 0.1)

Parameters

value

number | Vec2

Returns

void

pixelsPerUnit

Get Signature

get pixelsPerUnit(): number

Gets the number of pixels that map to one Mirror Engine unit.

Returns

number

Set Signature

set pixelsPerUnit(arg: number): void

Sets the number of pixels that map to one Mirror Engine unit. Only works for ELEMENTTYPE_IMAGE types who have a sliced sprite assigned.

Parameters

arg

number

Returns

void

rangeEnd

Get Signature

get rangeEnd(): number

Gets the index of the last character to render.

Returns

number

Set Signature

set rangeEnd(arg: number): void

Sets the index of the last character to render. Only works for ELEMENTTYPE_TEXT types.

Parameters

arg

number

Returns

void

rangeStart

Get Signature

get rangeStart(): number

Gets the index of the first character to render.

Returns

number

Set Signature

set rangeStart(arg: number): void

Sets the index of the first character to render. Only works for ELEMENTTYPE_TEXT types.

Parameters

arg

number

Returns

void

rect

Get Signature

get rect(): Vec4

Gets the region of the texture to use in order to render an image.

Returns

Vec4

Set Signature

set rect(arg: Vec4): void

Sets the region of the texture to use in order to render an image. Values range from 0 to 1 and indicate u, v, width, height. Only works for ELEMENTTYPE_IMAGE types.

Parameters

arg

Vec4

Returns

void

right

Get Signature

get right(): number

Gets the distance from the right edge of the anchor.

Returns

number

Set Signature

set right(value: number): void

Sets the distance from the right edge of the anchor. Can be used in combination with a split anchor to make the component's right edge always be 'right' units away from the right.

Parameters

value

number

Returns

void

rtlReorder

Get Signature

get rtlReorder(): boolean

Gets whether to reorder the text for RTL languages.

Returns

boolean

Set Signature

set rtlReorder(arg: boolean): void

Sets whether to reorder the text for RTL languages. The reordering uses a function registered by app.systems.element.registerUnicodeConverter.

Parameters

arg

boolean

Returns

void

screenCorners

Get Signature

get screenCorners(): Vec3[]

Gets the array of 4 Vec3s that represent the bottom left, bottom right, top right and top left corners of the component relative to its parent ScreenComponent.

Returns

Vec3

shadowColor

Get Signature

get shadowColor(): Color

Gets the text shadow effect color and opacity.

Returns

Color

Set Signature

set shadowColor(arg: Color): void

Sets the text shadow effect color and opacity. Only works for ELEMENTTYPE_TEXT types.

Parameters

arg

Color

Returns

void

shadowOffset

Get Signature

get shadowOffset(): number

Gets the text shadow effect shift amount from original text.

Returns

number

Set Signature

set shadowOffset(arg: number): void

Sets the text shadow effect shift amount from original text. Only works for ELEMENTTYPE_TEXT types.

Parameters

arg

number

Returns

void

spacing

Get Signature

get spacing(): number

Gets the spacing between the letters of the text.

Returns

number

Set Signature

set spacing(arg: number): void

Sets the spacing between the letters of the text. Only works for ELEMENTTYPE_TEXT types.

Parameters

arg

number

Returns

void

sprite

Get Signature

get sprite(): Sprite

Gets the sprite to render.

Returns

Sprite

Set Signature

set sprite(arg: Sprite): void

Sets the sprite to render. Only works for ELEMENTTYPE_IMAGE types which can render either a texture or a sprite.

Parameters

arg

Sprite

Returns

void

spriteAsset

Get Signature

get spriteAsset(): number

Gets the id of the sprite asset to render.

Returns

number

Set Signature

set spriteAsset(arg: number): void

Sets the id of the sprite asset to render. Only works for ELEMENTTYPE_IMAGE types which can render either a texture or a sprite.

Parameters

arg

number

Returns

void

spriteFrame

Get Signature

get spriteFrame(): number

Gets the frame of the sprite to render.

Returns

number

Set Signature

set spriteFrame(arg: number): void

Sets the frame of the sprite to render. Only works for ELEMENTTYPE_IMAGE types who have a sprite assigned.

Parameters

arg

number

Returns

void

text

Get Signature

get text(): string

Gets the text to render.

Returns

string

Set Signature

set text(arg: string): void

Sets the text to render. Only works for ELEMENTTYPE_TEXT types. To override certain text styling properties on a per-character basis, the text can optionally include markup tags contained within square brackets. Supported tags are:

1. color - override the element's color property. Examples:
   • [color="#ff0000"]red text[/color]
   • [color="#00ff00"]green text[/color]
   • [color="#0000ff"]blue text[/color]
2. outline - override the element's outlineColor and outlineThickness properties. Example: - [outline color="#ffffff" thickness="0.5"]text[/outline]
3. shadow - override the element's shadowColor and shadowOffset properties. Examples: - [shadow color="#ffffff" offset="0.5"]text[/shadow] - [shadow color="#000000" offsetX="0.1" offsetY="0.2"]text[/shadow]

Note that markup tags are only processed if the text element's enableMarkup property is set to true.

Parameters

arg

string

Returns

void

textHeight

Get Signature

get textHeight(): number

Gets the height of the text rendered by the component. Only works for ELEMENTTYPE_TEXT types.

Returns

number

texture

Get Signature

get texture(): Texture

Gets the texture to render.

Returns

Texture

Set Signature

set texture(arg: Texture): void

Sets the texture to render. Only works for ELEMENTTYPE_IMAGE types.

Parameters

arg

Texture

Returns

void

textureAsset

Get Signature

get textureAsset(): number

Gets the id of the texture asset to render.

Returns

number

Set Signature

set textureAsset(arg: number): void

Sets the id of the texture asset to render. Only works for ELEMENTTYPE_IMAGE types.

Parameters

arg

number

Returns

void

textWidth

Get Signature

get textWidth(): number

Gets the width of the text rendered by the component. Only works for ELEMENTTYPE_TEXT types.

Returns

number

top

Get Signature

get top(): number

Gets the distance from the top edge of the anchor.

Returns

number

Set Signature

set top(value: number): void

Sets the distance from the top edge of the anchor. Can be used in combination with a split anchor to make the component's bottom edge always be 'bottom' units away from the bottom.

Parameters

value

number

Returns

void

type

Get Signature

get type(): string

Gets the type of the ElementComponent.

Returns

string

Set Signature

set type(value: string): void

Sets the type of the ElementComponent. Can be:

• ELEMENTTYPE_GROUP: The component can be used as a layout mechanism to create groups of ElementComponents e.g. panels.
• ELEMENTTYPE_IMAGE: The component will render an image
• ELEMENTTYPE_TEXT: The component will render text

Parameters

value

string

Returns

void

unicodeConverter

Get Signature

get unicodeConverter(): boolean

Gets whether to convert unicode characters.

Returns

boolean

Set Signature

set unicodeConverter(arg: boolean): void

Sets whether to convert unicode characters. This uses a function registered by app.systems.element.registerUnicodeConverter.

Parameters

arg

boolean

Returns

void

useInput

Get Signature

get useInput(): boolean

Gets whether the component will receive mouse and touch input events.

Returns

boolean

Set Signature

set useInput(value: boolean): void

Sets whether the component will receive mouse and touch input events.

Parameters

value

boolean

Returns

void

width

Get Signature

get width(): number

Gets the width of the element.

Returns

number

Set Signature

set width(value: number): void

Sets the width of the element as set in Build Mode. Note that in some cases this may not reflect the true width at which the element is rendered, such as when the element is under the control of a LayoutGroupComponent. See calculatedWidth in order to ensure you are reading the true width at which the element will be rendered.

Parameters

value

number

Returns

void

worldCorners

Get Signature

get worldCorners(): Vec3[]

Gets the array of 4 Vec3s that represent the bottom left, bottom right, top right and top left corners of the component in world space. Only works for 3D element components.

Returns

Vec3

wrapLines

Get Signature

get wrapLines(): boolean

Gets whether to automatically wrap lines based on the element width.

Returns

boolean

Set Signature

set wrapLines(arg: boolean): void

Sets whether to automatically wrap lines based on the element width. Only works for ELEMENTTYPE_TEXT types, and when autoWidth is set to false.

Parameters

arg

boolean

Returns

void

Methods

fire()

fire(
   name: string,
   arg1?: any,
   arg2?: any,
   arg3?: any,
   arg4?: any,
   arg5?: any,
   arg6?: any,
   arg7?: any,
   arg8?: any): EventHandler

Fire an event, all additional arguments are passed on to the event listener.

Parameters

name

string

Name of event to fire.

arg1?

any

First argument that is passed to the event handler.

arg2?

any

Second argument that is passed to the event handler.

arg3?

any

Third argument that is passed to the event handler.

arg4?

any

Fourth argument that is passed to the event handler.

arg5?

any

Fifth argument that is passed to the event handler.

arg6?

any

Sixth argument that is passed to the event handler.

arg7?

any

Seventh argument that is passed to the event handler.

arg8?

any

Eighth argument that is passed to the event handler.

Returns

EventHandler

Self for chaining.

Example

obj.fire('test', 'This is the message')

Inherited from

Component.fire

hasEvent()

hasEvent(name: string): boolean

Test if there are any handlers bound to an event name.

Parameters

name

string

The name of the event to test.

Returns

boolean

True if the object has handlers bound to the specified event name.

Example

obj.on('test', () => {}) // bind an event to 'test'
obj.hasEvent('test') // returns true
obj.hasEvent('hello') // returns false

Inherited from

Component.hasEvent

off()

off(
   name?: string,
   callback?: HandleEventCallback,
   scope?: any): EventHandler

Detach an event handler from an event. If callback is not provided then all callbacks are unbound from the event, if scope is not provided then all events with the callback will be unbound.

Parameters

name?

string

Name of the event to unbind.

callback?

HandleEventCallback

Function to be unbound.

scope?

any

Scope that was used as the this when the event is fired.

Returns

EventHandler

Self for chaining.

Example

const handler = () => {}
obj.on('test', handler)

obj.off() // Removes all events
obj.off('test') // Removes all events called 'test'
obj.off('test', handler) // Removes all handler functions, called 'test'
obj.off('test', handler, this) // Removes all handler functions, called 'test' with scope this

Inherited from

Component.off

on()

on(
   name: string,
   callback: HandleEventCallback,
   scope?: any): EventHandle

Attach an event handler to an event.

Parameters

name

string

Name of the event to bind the callback to.

callback

HandleEventCallback

Function that is called when event is fired. Note the callback is limited to 8 arguments.

scope?

any = ...

Object to use as 'this' when the event is fired, defaults to current this.

Returns

EventHandle

Can be used for removing event in the future.

Examples

obj.on('test', (a, b) => {
  console.log(a + b)
})
obj.fire('test', 1, 2) // prints 3 to the console

const evt = obj.on('test', (a, b) => {
  console.log(a + b)
})
// some time later
evt.off()

Inherited from

Component.on

once()

once(
   name: string,
   callback: HandleEventCallback,
   scope?: any): EventHandle

Attach an event handler to an event. This handler will be removed after being fired once.

Parameters

name

string

Name of the event to bind the callback to.

callback

HandleEventCallback

Function that is called when event is fired. Note the callback is limited to 8 arguments.

scope?

any = ...

Object to use as 'this' when the event is fired, defaults to current this.

Returns

EventHandle

• can be used for removing event in the future.

Example

obj.once('test', (a, b) => {
  console.log(a + b)
})
obj.fire('test', 1, 2) // prints 3 to the console
obj.fire('test', 1, 2) // not going to get handled

Inherited from

Component.once

Events

EVENT_CLICK

static EVENT_CLICK: string = 'click';

Fired when the mouse is pressed and released on the component or when a touch starts and ends on the component. Only fired when useInput is true. The handler is passed an ElementMouseEvent or ElementTouchEvent.

Example

entity.element.on('click', (event) => {
  console.log(`Click event on entity ${'${entity.name}'}`)
})

EVENT_MOUSEDOWN

static EVENT_MOUSEDOWN: string = 'mousedown';

Fired when the mouse is pressed while the cursor is on the component. Only fired when useInput is true. The handler is passed an ElementMouseEvent.

Example

entity.element.on('mousedown', (event) => {
  console.log(`Mouse down event on entity ${'${entity.name}'}`)
})

EVENT_MOUSEENTER

static EVENT_MOUSEENTER: string = 'mouseenter';

Fired when the mouse cursor enters the component. Only fired when useInput is true. The handler is passed an ElementMouseEvent.

Example

entity.element.on('mouseenter', (event) => {
  console.log(`Mouse enter event on entity ${'${entity.name}'}`)
})

EVENT_MOUSELEAVE

static EVENT_MOUSELEAVE: string = 'mouseleave';

Fired when the mouse cursor leaves the component. Only fired when useInput is true. The handler is passed an ElementMouseEvent.

Example

entity.element.on('mouseleave', (event) => {
  console.log(`Mouse leave event on entity ${'${entity.name}'}`)
})

EVENT_MOUSEMOVE

static EVENT_MOUSEMOVE: string = 'mousemove';

Fired when the mouse cursor is moved on the component. Only fired when useInput is true. The handler is passed an ElementMouseEvent.

Example

entity.element.on('mousemove', (event) => {
  console.log(`Mouse move event on entity ${'${entity.name}'}`)
})

EVENT_MOUSEUP

static EVENT_MOUSEUP: string = 'mouseup';

Fired when the mouse is released while the cursor is on the component. Only fired when useInput is true. The handler is passed an ElementMouseEvent.

Example

entity.element.on('mouseup', (event) => {
  console.log(`Mouse up event on entity ${'${entity.name}'}`)
})

EVENT_MOUSEWHEEL

static EVENT_MOUSEWHEEL: string = 'mousewheel';

Fired when the mouse wheel is scrolled on the component. Only fired when useInput is true. The handler is passed an ElementMouseEvent.

Example

entity.element.on('mousewheel', (event) => {
  console.log(`Mouse wheel event on entity ${'${entity.name}'}`)
})

EVENT_TOUCHCANCEL

static EVENT_TOUCHCANCEL: string = 'touchcancel';

Fired when a touch is canceled on the component. Only fired when useInput is true. The handler is passed an ElementTouchEvent.

Example

entity.element.on('touchcancel', (event) => {
  console.log(`Touch cancel event on entity ${'${entity.name}'}`)
})

EVENT_TOUCHEND

static EVENT_TOUCHEND: string = 'touchend';

Fired when a touch ends on the component. Only fired when useInput is true. The handler is passed an ElementTouchEvent.

Example

entity.element.on('touchend', (event) => {
  console.log(`Touch end event on entity ${'${entity.name}'}`)
})

EVENT_TOUCHMOVE

static EVENT_TOUCHMOVE: string = 'touchmove';

Fired when a touch moves after it started touching the component. Only fired when useInput is true. The handler is passed an ElementTouchEvent.

Example

entity.element.on('touchmove', (event) => {
  console.log(`Touch move event on entity ${'${entity.name}'}`)
})

EVENT_TOUCHSTART

static EVENT_TOUCHSTART: string = 'touchstart';

Fired when a touch starts on the component. Only fired when useInput is true. The handler is passed an ElementTouchEvent.

Example

entity.element.on('touchstart', (event) => {
  console.log(`Touch start event on entity ${'${entity.name}'}`)
})