springroll.easeljs.Button Class

Defined in: springroll.easeljs.Button:20

A Multipurpose button class. It is designed to have one image, and an optional text label. The button can be a normal button or a selectable button. The button functions similarly with both EaselJS and PIXI, but slightly differently in initialization and callbacks. Add event listeners for click and mouseover to know about button clicks and mouse overs, respectively.

Constructor

`springroll.easeljs.Button`

(

[imageSettings]
[label=null]
[enabled=true]

)

Defined in springroll.easeljs.Button:20

Parameters:

[imageSettings] Object | Image | HTMLCanvasElement optional

Information about the art to be used for button states, as well as if the button is selectable or not. If this is an Image or Canvas element, then the button assumes that the image is full width and 3 images tall, in the order (top to bottom) up, over, down. If so, then the properties of imageSettings are ignored.
- [image] Image | HTMLCanvasElement optional
  
  The image to use for all of the button states.
- [priority=null] Array optional
  
  The state priority order. If omitted, defaults to ["disabled", "down", "over", "up"]. Previous versions of Button used a hard coded order: ["highlighted", "disabled", "down", "over", "selected", "up"].
- [up] Object optional
  
  The visual information about the up state.
  - [src] createjs.Rectangle optional
    The sourceRect for the state within the image.
  - [trim=null] createjs.Rectangle optional
    Trim data about the state, where x & y are how many pixels were trimmed off the left and right, and height & width are the untrimmed size of the button.
  - [label=null] Object optional
    Label information specific to this state. Properties on this parameter override data in the label parameter for this button state only. All values except "text" from the label parameter may be overridden.
- [over=null] Object optional
  
  The visual information about the over state. If omitted, uses the up state.
  - [src] createjs.Rectangle optional
    The sourceRect for the state within the image.
  - [trim=null] createjs.Rectangle optional
    Trim data about the state, where x & y are how many pixels were trimmed off the left and right, and height & width are the untrimmed size of the button.
  - [label=null] Object optional
    Label information specific to this state. Properties on this parameter override data in the label parameter for this button state only. All values except "text" from the label parameter may be overridden.
- [down=null] Object optional
  
  The visual information about the down state. If omitted, uses the up state.
  - [src] createjs.Rectangle optional
    The sourceRect for the state within the image.
  - [trim=null] createjs.Rectangle optional
    Trim data about the state, where x & y are how many pixels were trimmed off the left and right, and height & width are the untrimmed size of the button.
  - [label=null] Object optional
    Label information specific to this state. Properties on this parameter override data in the label parameter for this button state only. All values except "text" from the label parameter may be overridden.
- [disabled=null] Object optional
  
  The visual information about the disabled state. If omitted, uses the up state.
  - [src] createjs.Rectangle optional
    The sourceRect for the state within the image.
  - [trim=null] createjs.Rectangle optional
    Trim data about the state, where x & y are how many pixels were trimmed off the left and right, and height & width are the untrimmed size of the button.
  - [label=null] Object optional
    Label information specific to this state. Properties on this parameter override data in the label parameter for this button state only. All values except "text" from the label parameter may be overridden.
- [<yourCustomState>=null] Object optional
  
  The visual information about a custom state found in imageSettings.priority. Any state added this way has a property of the same name added to the button. Examples of previous states that have been moved to this system are "selected" and "highlighted".
  - [src] createjs.Rectangle optional
    The sourceRect for the state within the image.
  - [trim=null] createjs.Rectangle optional
    Trim data about the state, where x & y are how many pixels were trimmed off the left and right, and height & width are the untrimmed size of the button.
  - [label=null] Object optional
    Label information specific to this state. Properties on this parameter override data in the label parameter for this button state only. All values except "text" from the label parameter may be overridden.
- [origin=null] createjs.Point optional
  
  An optional offset for all button graphics, in case you want button positioning to not include a highlight glow, or any other reason you would want to offset the button art and label.
[label=null] Object optional

Information about the text label on the button. Omitting this makes the button not use a label.
- [text] String optional
  
  The text to display on the label.
- [font] String optional
  
  The font name and size to use on the label, as createjs.Text expects.
- [color] String optional
  
  The color of the text to use on the label, as createjs.Text expects.
- [textBaseline="middle"] String optional
  
  The baseline for the label text, as createjs.Text expects.
- [stroke=null] Object optional
  
  The stroke to use for the label text, if desired, as createjs.Text (springroll fork only) expects.
- [shadow=null] createjs.Shadow optional
  
  A shadow object to apply to the label text.
- [x="center"] String | Number optional
  
  An x position to place the label text at relative to the button. If omitted, "center" is used, which attempts to horizontally center the label on the button.
- [y="center"] String | Number optional
  
  A y position to place the label text at relative to the button. If omitted, "center" is used, which attempts to vertically center the label on the button. This may be unreliable - see documentation for createjs.Text.getMeasuredLineHeight().
[enabled=true] Boolean optional

Whether or not the button is initially enabled.

Properties

_clickCB
_downCB
_height
_offset
_outCB
_overCB
_stateData
_stateFlags
_statePriority
_upCB
_width
back
BUTTON_OUT static
BUTTON_OVER static
BUTTON_PRESS static
enabled
height
label
width

`_addProperty`

(

propertyName

)

private

Defined in _addProperty:583

Adds a property to the button. Setting the property sets the value in _stateFlags and calls _updateState().

Parameters:

propertyName String

The property name to add to the button.

`_onClick`

()

private

Defined in _onClick:713

The callback for when the button the button is clicked or tapped on. This is the most reliable way of detecting mouse up/touch end events that are on this button while letting the pressup event handle the mouse up/touch ends on and outside the button.

`_onMouseDown`

()

private

Defined in _onMouseDown:685

The callback for when the button receives a mouse down event.

`_onMouseOut`

()

private

Defined in _onMouseOut:738

The callback for when the mouse leaves the button area.

`_onMouseOver`

()

private

Defined in _onMouseOver:725

The callback for when the button is moused over.

`_onMouseUp`

()

private

Defined in _onMouseUp:698

The callback for when the button for when the mouse/touch is released on the button

only when the button was held down initially.

`_updateState`

() Object

private

Defined in _updateState:614

Updates back based on the current button state.

Returns:

Object:

The state data for the active button state, so that subclasses can use the value picked by this function without needing to calculate it themselves.

`cacheByBounds`

(

[buffer=0]
[scale=1]

)

Inherited from createjs.Container: cacheByBounds:18

Does a cache by the nominalBounds set from Flash

Parameters:

[buffer=0] Int optional

The space around the nominal bounds to include in cache image
[scale=1] Number optional

The scale to cache the container by.

`cacheByRect`

(

rect
[buffer=0]
[scale=1]

)

Inherited from createjs.Container: cacheByRect:29

Does a cache by a given rectangle

Parameters:

rect createjs.Rectangle

The rectangle to cache with.
[buffer=0] Int optional

Additional space around the rectangle to include in cache image
[scale=1] Number optional

The scale to cache the container by.

`destroy`

()

public

Defined in destroy:751

Destroys the button.

`generateDefaultStates`

(

image
[disabledSettings]
[highlightSettings]

)

Object

static

Defined in generateDefaultStates:771

Generates a desaturated up state as a disabled state, and an update with a solid colored glow for a highlighted state.

Parameters:

image Image | HTMLCanvasElement

The image to use for all of the button states, in the standard up/over/down format.
[disabledSettings] Object optional

The settings object for the disabled state. If omitted, no disabled state is created.
- [saturation] Number optional
  
  The saturation adjustment for the disabled state. 100 is fully saturated, 0 is unchanged, -100 is desaturated.
- [brightness] Number optional
  
  The brightness adjustment for the disabled state. 100 is fully bright, 0 is unchanged, -100 is completely dark.
- [contrast] Number optional
  
  The contrast adjustment for the disabled state. 100 is full contrast, 0 is unchanged, -100 is no contrast.
[highlightSettings] Object optional

The settings object for the highlight state. If omitted, no state is created.
- [size] Number optional
  
  How many pixels to make the glow, eg 8 for an 8 pixel increase on each side.
- [red] Number optional
  
  The red value for the glow, from 0 to 255.
- [green] Number optional
  
  The green value for the glow, from 0 to 255.
- [blue] Number optional
  
  The blue value for the glow, from 0 to 255.
- [alpha=255] Number optional
  
  The alpha value for the glow, from 0 to 255, with 0 being transparent and 255 fully opaque.
- [rgba] Array optional
  
  An array of values to use for red, green, blue, and optionally alpha that can be used instead of providing separate properties on highlightSettings.

Returns:

Object:

An object for use as the 'imageSettings' parameter on a new Button.

`generateSettingsFromAtlas`

(

atlas
baseName
statePriority

)

static

Defined in generateSettingsFromAtlas:952

Generates an 'imageSettings' from a TextureAtlas, a base name for all frames, and a list of state priorities.

Parameters:

atlas springroll.easeljs.TextureAtlas

The TextureAtlas to pull all frames from.
baseName String

The base name for all frames in the atlas.
statePriority Array

The state order, as well as determining frame names in the atlas. Each state frame name in the atlas should be baseName + "_" + statePriority[i].

`setText`

(

text

)

public

Defined in setText:511

Sets the text of the label. This does nothing if the button was not initialized with a label.

Parameters:

text String

The text to set the label to.

`_clickCB`

Function private

Defined in _clickCB:211

Callback for click, bound to this button.

`_downCB`

Function private

Defined in _downCB:197

Callback for mouse down, bound to this button.

`_height`

Number private

Defined in _height:250

The height of the button art, independent of the scaling of the button itself.

`_offset`

createjs.Point private

Defined in _offset:257

An offset to button positioning, generally used to adjust for a highlight around the button.

`_outCB`

Function private

Defined in _outCB:190

Callback for mouse out, bound to this button.

`_overCB`

Function private

Defined in _overCB:183

Callback for mouse over, bound to this button.

`_stateData`

Object private

Defined in _stateData:234

A dictionary of state graphic data, keyed by state name. Each object contains the sourceRect (src) and optionally 'trim', another Rectangle. Additionally, each object will contain a 'label' object if the button has a text label.

`_stateFlags`

Object private

Defined in _stateFlags:218

A dictionary of state booleans, keyed by state name.

`_statePriority`

Array private

Defined in _statePriority:225

An array of state names (Strings), in their order of priority. The standard order previously was ["highlighted", "disabled", "down", "over", "selected", "up"].