Mirror Engine
V5
How To
Mirror Engine Logo

Mirror Engine API


Mirror Engine API / ButtonComponent

Class: ButtonComponent

A ButtonComponent enables a group of entities to behave like a button, with different visual states for hover and press interactions.

Extends

  • Component

Properties

entity

entity: Entity

The Entity that this Component is attached to.

Inherited from

Component.entity

system

system: ComponentSystem

The ComponentSystem used to create this Component.

Inherited from

Component.system

active

Get Signature

get active(): boolean

Gets the button's active state.

Returns

boolean

Set Signature

set active(arg: boolean): void

Sets the button's active state. If set to false, the button will be visible but will not respond to hover or touch interactions. Defaults to true.

Parameters
arg

boolean

Returns

void


enabled

Get Signature

get enabled(): boolean

Gets the enabled state of the component.

Returns

boolean

Set Signature

set enabled(arg: boolean): void

Sets the enabled state of the component.

Parameters
arg

boolean

Returns

void

Overrides

Component.enabled

fadeDuration

Get Signature

get fadeDuration(): number

Gets the duration to be used when fading between tints, in milliseconds.

Returns

number

Set Signature

set fadeDuration(arg: number): void

Sets the duration to be used when fading between tints, in milliseconds. Defaults to 0.

Parameters
arg

number

Returns

void


hitPadding

Get Signature

get hitPadding(): Vec4

Gets the padding to be used in hit-test calculations.

Returns

Vec4

Set Signature

set hitPadding(arg: Vec4): void

Sets the padding to be used in hit-test calculations. Can be used to expand the bounding box so that the button is easier to tap. Defaults to [0, 0, 0, 0].

Parameters
arg

Vec4

Returns

void


hoverSpriteAsset

Get Signature

get hoverSpriteAsset(): Asset

Gets the sprite to be used as the button image when the user hovers over it.

Returns

Asset

Set Signature

set hoverSpriteAsset(arg: Asset): void

Sets the sprite to be used as the button image when the user hovers over it.

Parameters
arg

Asset

Returns

void


hoverSpriteFrame

Get Signature

get hoverSpriteFrame(): number

Gets the frame to be used from the hover sprite.

Returns

number

Set Signature

set hoverSpriteFrame(arg: number): void

Sets the frame to be used from the hover sprite.

Parameters
arg

number

Returns

void


hoverTint

Get Signature

get hoverTint(): Color

Gets the tint color to be used on the button image when the user hovers over it.

Returns

Color

Set Signature

set hoverTint(arg: Color): void

Sets the tint color to be used on the button image when the user hovers over it. Defaults to [0.75, 0.75, 0.75].

Parameters
arg

Color

Returns

void


imageEntity

Get Signature

get imageEntity(): null | Entity

Gets the entity to be used as the button background.

Returns

null | Entity

Set Signature

set imageEntity(arg: null | Entity): void

Sets the entity to be used as the button background. The entity must have an ElementComponent configured as an image element.

Parameters
arg

null | Entity

Returns

void


inactiveSpriteAsset

Get Signature

get inactiveSpriteAsset(): Asset

Gets the sprite to be used as the button image when the button is not interactive.

Returns

Asset

Set Signature

set inactiveSpriteAsset(arg: Asset): void

Sets the sprite to be used as the button image when the button is not interactive.

Parameters
arg

Asset

Returns

void


inactiveSpriteFrame

Get Signature

get inactiveSpriteFrame(): number

Gets the frame to be used from the inactive sprite.

Returns

number

Set Signature

set inactiveSpriteFrame(arg: number): void

Sets the frame to be used from the inactive sprite.

Parameters
arg

number

Returns

void


inactiveTint

Get Signature

get inactiveTint(): Color

Gets the tint color to be used on the button image when the button is not interactive.

Returns

Color

Set Signature

set inactiveTint(arg: Color): void

Sets the tint color to be used on the button image when the button is not interactive. Defaults to [0.25, 0.25, 0.25].

Parameters
arg

Color

Returns

void


pressedSpriteAsset

Get Signature

get pressedSpriteAsset(): Asset

Gets the sprite to be used as the button image when the user presses it.

Returns

Asset

Set Signature

set pressedSpriteAsset(arg: Asset): void

Sets the sprite to be used as the button image when the user presses it.

Parameters
arg

Asset

Returns

void


pressedSpriteFrame

Get Signature

get pressedSpriteFrame(): number

Gets the frame to be used from the pressed sprite.

Returns

number

Set Signature

set pressedSpriteFrame(arg: number): void

Sets the frame to be used from the pressed sprite.

Parameters
arg

number

Returns

void


pressedTint

Get Signature

get pressedTint(): Color

Gets the tint color to be used on the button image when the user presses it.

Returns

Color

Set Signature

set pressedTint(arg: Color): void

Sets the tint color to be used on the button image when the user presses it. Defaults to [0.5, 0.5, 0.5].

Parameters
arg

Color

Returns

void


transitionMode

Get Signature

get transitionMode(): number

Gets the button transition mode.

Returns

number

Set Signature

set transitionMode(arg: number): void

Sets the button transition mode. This controls how the button responds when the user hovers over it/presses it. Can be:

Defaults to BUTTON_TRANSITION_MODE_TINT.

Parameters
arg

number

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. The handler is passed a ElementMouseEvent or ElementTouchEvent.

Example

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

EVENT_HOVEREND

static EVENT_HOVEREND: string = 'hoverend';

Fired when the button changes state to be not hovered.

Example

entity.button.on('hoverend', () => {
  console.log(`Entity ${'${entity.name}'} unhovered`)
})

EVENT_HOVERSTART

static EVENT_HOVERSTART: string = 'hoverstart';

Fired when the button changes state to be hovered.

Example

entity.button.on('hoverstart', () => {
  console.log(`Entity ${'${entity.name}'} hovered`)
})

EVENT_MOUSEDOWN

static EVENT_MOUSEDOWN: string = 'mousedown';

Fired when the mouse is pressed while the cursor is on the component. The handler is passed a ElementMouseEvent.

Example

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

EVENT_MOUSEENTER

static EVENT_MOUSEENTER: string = 'mouseenter';

Fired when the mouse cursor enters the component. The handler is passed a ElementMouseEvent.

Example

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

EVENT_MOUSELEAVE

static EVENT_MOUSELEAVE: string = 'mouseleave';

Fired when the mouse cursor leaves the component. The handler is passed a ElementMouseEvent.

Example

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

EVENT_MOUSEUP

static EVENT_MOUSEUP: string = 'mouseup';

Fired when the mouse is released while the cursor is on the component. The handler is passed a ElementMouseEvent.

Example

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

EVENT_PRESSEDEND

static EVENT_PRESSEDEND: string = 'pressedend';

Fired when the button changes state to be not pressed.

Example

entity.button.on('pressedend', () => {
  console.log(`Entity ${'${entity.name}'} unpressed`)
})

EVENT_PRESSEDSTART

static EVENT_PRESSEDSTART: string = 'pressedstart';

Fired when the button changes state to be pressed.

Example

entity.button.on('pressedstart', () => {
  console.log(`Entity ${'${entity.name}'} pressed`)
})

EVENT_SELECTEND

static EVENT_SELECTEND: string = 'selectend';

Fired when a xr select ends on the component. The handler is passed a ElementSelectEvent.

Example

entity.button.on('selectend', (event) => {
  console.log(`Select ended on entity ${'${entity.name}'}`)
})

EVENT_SELECTENTER

static EVENT_SELECTENTER: string = 'selectenter';

Fired when a xr select now hovering over the component. The handler is passed a ElementSelectEvent.

Example

entity.button.on('selectenter', (event) => {
  console.log(`Select entered entity ${'${entity.name}'}`)
})

EVENT_SELECTLEAVE

static EVENT_SELECTLEAVE: string = 'selectleave';

Fired when a xr select not hovering over the component. The handler is passed a ElementSelectEvent.

Example

entity.button.on('selectleave', (event) => {
  console.log(`Select left entity ${'${entity.name}'}`)
})

EVENT_SELECTSTART

static EVENT_SELECTSTART: string = 'selectstart';

Fired when a xr select starts on the component. The handler is passed a ElementSelectEvent.

Example

entity.button.on('selectstart', (event) => {
  console.log(`Select started on entity ${'${entity.name}'}`)
})

EVENT_TOUCHCANCEL

static EVENT_TOUCHCANCEL: string = 'touchcancel';

Fired when a touch is canceled on the component. The handler is passed a ElementTouchEvent.

Example

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

EVENT_TOUCHEND

static EVENT_TOUCHEND: string = 'touchend';

Fired when a touch ends on the component. The handler is passed a ElementTouchEvent.

Example

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

EVENT_TOUCHLEAVE

static EVENT_TOUCHLEAVE: string = 'touchleave';

Fired when a touch leaves the component. The handler is passed a ElementTouchEvent.

Example

entity.button.on('touchleave', (event) => {
  console.log(`Touch left entity ${'${entity.name}'}`)
})

EVENT_TOUCHSTART

static EVENT_TOUCHSTART: string = 'touchstart';

Fired when a touch starts on the component. The handler is passed a ElementTouchEvent.

Example

entity.button.on('touchstart', (event) => {
  console.log(`Touch started on entity ${'${entity.name}'}`)
})
Mirror Engine Logo