Class ButtonComponent

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

Hierarchy (View Summary)

Component
- ButtonComponent

Properties

entity

entity: Entity

The Entity that this Component is attached to.

system

system: ComponentSystem

The ComponentSystem used to create this Component.

Accessors

active

get active(): boolean
Gets the button's active state.

Returns boolean
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 enabled(): boolean
Gets the enabled state of the component.

Returns boolean
set enabled(arg: boolean): void
Sets the enabled state of the component.
Parameters
- arg: boolean
Returns void

fadeDuration

get fadeDuration(): number
Gets the duration to be used when fading between tints, in milliseconds.

Returns number
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 hitPadding(): Vec4
Gets the padding to be used in hit-test calculations.

Returns Vec4
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 hoverSpriteAsset(): Asset
Gets the sprite to be used as the button image when the user hovers over it.

Returns Asset
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 hoverSpriteFrame(): number
Gets the frame to be used from the hover sprite.

Returns number
set hoverSpriteFrame(arg: number): void
Sets the frame to be used from the hover sprite.
Parameters
- arg: number
Returns void

hoverTint

get hoverTint(): Color
Gets the tint color to be used on the button image when the user hovers over it.

Returns Color
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 imageEntity(): null | Entity
Gets the entity to be used as the button background.

Returns null | Entity
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 inactiveSpriteAsset(): Asset
Gets the sprite to be used as the button image when the button is not interactive.

Returns Asset
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 inactiveSpriteFrame(): number
Gets the frame to be used from the inactive sprite.

Returns number
set inactiveSpriteFrame(arg: number): void
Sets the frame to be used from the inactive sprite.
Parameters
- arg: number
Returns void

inactiveTint

get inactiveTint(): Color
Gets the tint color to be used on the button image when the button is not interactive.

Returns Color
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 pressedSpriteAsset(): Asset
Gets the sprite to be used as the button image when the user presses it.

Returns Asset
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 pressedSpriteFrame(): number
Gets the frame to be used from the pressed sprite.

Returns number
set pressedSpriteFrame(arg: number): void
Sets the frame to be used from the pressed sprite.
Parameters
- arg: number
Returns void

pressedTint

get pressedTint(): Color
Gets the tint color to be used on the button image when the user presses it.

Returns Color
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 transitionMode(): number
Gets the button transition mode.

Returns number
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:
- BUTTON_TRANSITION_MODE_TINT
- BUTTON_TRANSITION_MODE_SPRITE_CHANGE
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.
- Optionalarg1: any
  First argument that is passed to the event handler.
- Optionalarg2: any
  Second argument that is passed to the event handler.
- Optionalarg3: any
  Third argument that is passed to the event handler.
- Optionalarg4: any
  Fourth argument that is passed to the event handler.
- Optionalarg5: any
  Fifth argument that is passed to the event handler.
- Optionalarg6: any
  Sixth argument that is passed to the event handler.
- Optionalarg7: any
  Seventh argument that is passed to the event handler.
- Optionalarg8: any
  Eighth argument that is passed to the event handler.
Returns EventHandler
Self for chaining.
Example
```
obj.fire('test', 'This is the message');
```

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
```

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
- Optionalname: string
  Name of the event to unbind.
- Optionalcallback: HandleEventCallback
  Function to be unbound.
- Optionalscope: 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
```

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.
- Optionalscope: 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.on('test', (a, b) => {
    console.log(a + b);
});
obj.fire('test', 1, 2); // prints 3 to the console
```
Example
```
const evt = obj.on('test', (a, b) => {
    console.log(a + b);
});
// some time later
evt.off();
```

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.
- Optionalscope: 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
```

Events

`Static`EVENT_CLICK

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}`);
});

`Static`EVENT_HOVEREND

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`);
});

`Static`EVENT_HOVERSTART

EVENT_HOVERSTART: string = 'hoverstart'

Fired when the button changes state to be hovered.

Example

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

`Static`EVENT_MOUSEDOWN

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}`);
});

`Static`EVENT_MOUSEENTER

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}`);
});

`Static`EVENT_MOUSELEAVE

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}`);
});

`Static`EVENT_MOUSEUP

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}`);
});

`Static`EVENT_PRESSEDEND

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`);
});

`Static`EVENT_PRESSEDSTART

EVENT_PRESSEDSTART: string = 'pressedstart'

Fired when the button changes state to be pressed.

Example

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

`Static`EVENT_SELECTEND

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}`);
});

`Static`EVENT_SELECTENTER

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}`);
});

`Static`EVENT_SELECTLEAVE

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}`);
});

`Static`EVENT_SELECTSTART

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}`);
});

`Static`EVENT_TOUCHCANCEL

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}`);
});

`Static`EVENT_TOUCHEND

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}`);
});

`Static`EVENT_TOUCHLEAVE

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}`);
});

`Static`EVENT_TOUCHSTART

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}`);
});

Class ButtonComponent

Hierarchy (View Summary)

Index

Properties

Accessors

Methods

Events

Properties

entity

system

Accessors

active

Returns boolean

Parameters

Returns void

enabled

Returns boolean

Parameters

Returns void

fadeDuration

Returns number

Parameters

Returns void

hitPadding

Returns Vec4

Parameters

Returns void

hoverSpriteAsset

Returns Asset

Parameters

Returns void

hoverSpriteFrame

Returns number

Parameters

Returns void

hoverTint

Returns Color

Parameters

Returns void

imageEntity

Returns null | Entity

Parameters

Returns void

inactiveSpriteAsset

Returns Asset

Parameters

Returns void

inactiveSpriteFrame

Returns number

Parameters

Returns void

inactiveTint

Returns Color

Parameters

Returns void

pressedSpriteAsset

Returns Asset

Parameters

Returns void

pressedSpriteFrame

Returns number

Parameters

Returns void

pressedTint

Returns Color

Parameters

Returns void

transitionMode

Returns number

Parameters

Returns void

Methods

fire

Parameters

Returns EventHandler

Example

hasEvent

Parameters

Returns boolean

Example

`Static`EVENT_CLICK

`Static`EVENT_HOVEREND

`Static`EVENT_HOVERSTART

`Static`EVENT_MOUSEDOWN

`Static`EVENT_MOUSEENTER

`Static`EVENT_MOUSELEAVE

`Static`EVENT_MOUSEUP

`Static`EVENT_PRESSEDEND

`Static`EVENT_PRESSEDSTART

`Static`EVENT_SELECTEND

`Static`EVENT_SELECTENTER

`Static`EVENT_SELECTLEAVE

`Static`EVENT_SELECTSTART

`Static`EVENT_TOUCHCANCEL

`Static`EVENT_TOUCHEND

`Static`EVENT_TOUCHLEAVE

`Static`EVENT_TOUCHSTART