API Documentation for: 1.1.23
Show:

Button (CreateJS) Class

Extends createjs.Container
Defined in: Button (CreateJS):8
Namespace: cloudkid

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

Button (CreateJS)

(
  • [imageSettings]
  • [label=null]
  • [enabled=true]
)

Defined in Button (CreateJS):8

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 (CloudKid 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.

Methods

_addProperty

(
  • propertyName
)
private

Defined in _addProperty:448

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:553

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:525

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

_onMouseOut

() private

Defined in _onMouseOut:576

The callback for when the mouse leaves the button area.

_onMouseOver

() private

Defined in _onMouseOver:565

The callback for when the button is moused over.

_onMouseUp

() private

Defined in _onMouseUp:538

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

() private

Defined in _updateState:470

Updates back based on the current button state.

destroy

() public

Defined in destroy:587

Destroys the button.

generateDefaultStates

(
  • image
  • [disabledSettings]
  • [highlightSettings]
)
static

Defined in generateDefaultStates:607

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] Number optional

      The alpha value for the glow, from 0 to 255, with 0 being transparent and 255 fully opaque.

initialize

(
  • [imageSettings]
  • [label=null]
  • [enabled=true]
)

Defined in initialize:205

Constructor for the button when using CreateJS.

Parameters:

  • [imageSettings] Object | Image | HTMLCanvasElement optional

    See the constructor for more information

  • [label=null] Object optional

    Information about the text label on the button. Omitting this makes the button not use a label.

  • [enabled=true] Boolean optional

    Whether or not the button is initially enabled.

setText

(
  • text
)
public

Defined in setText:381

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.

Properties

_clickCB

Function private

Defined in _clickCB:131

Callback for click, bound to this button.

_downCB

Function private

Defined in _downCB:117

Callback for mouse down, bound to this button.

_height

Number private

Defined in _height:168

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

_offset

createjs.Point private

Defined in _offset:175

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

_outCB

Function private

Defined in _outCB:110

Callback for mouse out, bound to this button.

_overCB

Function private

Defined in _overCB:103

Callback for mouse over, bound to this button.

_stateData

Object private

Defined in _stateData:152

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:138

A dictionary of state booleans, keyed by state name.

_statePriority

Array private

Defined in _statePriority:144

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

_upCB

Function private

Defined in _upCB:124

Callback for press up, bound to this button.

_width

Number private

Defined in _width:161

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

back

createjs.Bitmap public

Defined in back:84

The sprite that is the body of the button. The type of this property is dependent on which version of the OS library is used.

BUTTON_PRESS

String public static

Defined in BUTTON_PRESS:182

An event for when the button is pressed (while enabled).

enabled

Boolean

Defined in enabled:415

Whether or not the button is enabled.

Default: true

height

Number

Defined in height:370

The height of the button, based on the height of back. This value is affected by scale.

label

createjs.Text public

Defined in label:93

The text field of the button. The label is centered by both width and height on the button. The type of this property is dependent on which version of the OS library is used.

width

Number

Defined in width:359

The width of the button, based on the width of back. This value is affected by scale.