Class: ButtonComponent
A ButtonComponent enables a group of entities to behave like a button, with different visual states for hover and press interactions.
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
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
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
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
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
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
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
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
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
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
Returns
void
pressedSpriteAsset
Get Signature
get pressedSpriteAsset(): Asset
Gets the sprite to be used as the button image when the user presses it.
Returns
Set Signature
set pressedSpriteAsset(arg: Asset): void
Sets the sprite to be used as the button image when the user presses it.
Parameters
arg
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
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
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
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. 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}'}`)
})