Mirror Engine API / ElementComponent
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
Extends
Component
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
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
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
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
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
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
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
Set Signature
set material(arg: Material): void
Sets the material to use when rendering an image. Only works for ELEMENTTYPE_IMAGE types.
Parameters
arg
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
Set Signature
set outlineColor(arg: Color): void
Sets the text outline effect color and opacity. Only works for ELEMENTTYPE_TEXT types.
Parameters
arg
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
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
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
Set Signature
set shadowColor(arg: Color): void
Sets the text shadow effect color and opacity. Only works for ELEMENTTYPE_TEXT types.
Parameters
arg
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
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
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:
color- override the element's color property. Examples:[color="#ff0000"]red text[/color][color="#00ff00"]green text[/color][color="#0000ff"]blue text[/color]
outline- override the element's outlineColor and outlineThickness properties. Example: -[outline color="#ffffff" thickness="0.5"]text[/outline]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
Set Signature
set texture(arg: Texture): void
Sets the texture to render. Only works for ELEMENTTYPE_IMAGE types.
Parameters
arg
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
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
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
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
- 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}'}`)
})