Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Button

A simple button composed of an image and, optionally, text.

You can use different textures for various states of the button. If you're providing only an up state, the button is simply scaled a little when it is touched.

In addition, you can overlay text on the button. To customize the text, you can use properties equivalent to those of the TextField class. Move the text to a certain position by updating the textBounds property.

To react on touches on a button, there is special Event.TRIGGERED event. Use this event instead of normal touch events. That way, users can cancel button activation by moving the mouse/finger away from the button before releasing.

Hierarchy

Index

Constructors

Properties

Methods

Constructors

constructor

Properties

alpha

alpha: number

The opacity of the object. 0 = transparent, 1 = opaque. @default 1

alphaWhenDisabled

alphaWhenDisabled: number

The alpha value of the button when it is disabled. @default 0.5

alphaWhenDown

alphaWhenDown: number

The alpha value of the button on touch. @default 1.0

base

The topmost object in the display tree the object is part of.

blendMode

blendMode: string

The blend mode determines how the object is blended with the objects underneath.

default

auto

see

starling.display.BlendMode

bounds

bounds: Rectangle

The bounds of the object relative to the local coordinates of the parent.

color

color: number

The color of the button's state image. Just like every image object, each pixel's color is multiplied with this value. @default white

disabledState

disabledState: Texture

The texture that is displayed when the button is disabled.

downState

downState: Texture

The texture that is displayed while the button is touched.

enabled

enabled: boolean

Indicates if the button can be triggered.

filter

The filter that is attached to the display object. The starling.filters package contains several classes that define specific filters you can use. To combine several filters, assign an instance of the FilterChain class; to remove all filters, assign null.

Beware that a filter instance may only be used on one object at a time! Furthermore, when you remove or replace a filter, it is NOT disposed automatically (since you might want to reuse it on a different object).

@default null @see starling.filters.FragmentFilter @see starling.filters.FilterChain

height

height: number

The height of the object in pixels. Note that for objects in a 3D space (connected to a Sprite3D), this value might not be accurate until the object is part of the display list.

is3D

is3D: boolean

Indicates if this object or any of its parents is a 'Sprite3D' object.

mask

The display object that acts as a mask for the current object. Assign null to remove it.

A pixel of the masked display object will only be drawn if it is within one of the mask's polygons. Texture pixels and alpha values of the mask are not taken into account. The mask object itself is never visible.

If the mask is part of the display list, masking will occur at exactly the location it occupies on the stage. If it is not, the mask will be placed in the local coordinate system of the target object (as if it was one of its children).

For rectangular masks, you can use simple quads; for other forms (like circles or arbitrary shapes) it is recommended to use a 'Canvas' instance.

Note: a mask will typically cause at least two additional draw calls: one to draw the mask to the stencil buffer and one to erase it. However, if the mask object is an instance of starling.display.Quad and is aligned parallel to the stage axes, rendering will be optimized: instead of using the stencil buffer, the object will be clipped using the scissor rectangle. That's faster and reduces the number of draw calls, so make use of this when possible.

Note: AIR apps require the depthAndStencil node in the application descriptor XMLs to be enabled! Otherwise, stencil masking won't work.

@see Canvas @default null

maskInverted

maskInverted: boolean

Indicates if the masked region of this object is set to be inverted.

name

name: string

The name of the display object (default: null). Used by 'getChildByName()' of display object containers.

numChildren

numChildren: number

The number of children of this container.

overState

overState: Texture

The texture that is displayed while mouse hovers over the button.

overlay

overlay: Sprite

The overlay sprite is displayed on top of the button contents. It scales with the button when pressed. Use it to add additional objects to the button (e.g. an icon).

parent

The display object container that contains this display object.

pivotX

pivotX: number

The x coordinate of the object's origin in its own coordinate space (default: 0).

pivotY

pivotY: number

The y coordinate of the object's origin in its own coordinate space (default: 0).

pixelSnapping

pixelSnapping: boolean

Controls whether or not the instance snaps to the nearest pixel. This can prevent the object from looking blurry when it's not exactly aligned with the pixels of the screen. @default true

requiresRedraw

requiresRedraw: boolean

Indicates if the object needs to be redrawn in the upcoming frame, i.e. if it has changed its location relative to the stage or some other aspect of its appearance since it was last rendered.

root

The root object the display object is connected to (i.e. an instance of the class that was passed to the Starling constructor), or null if the object is not connected to the stage.

rotation

rotation: number

The rotation of the object in radians. (In Starling, all angles are measured in radians.)

scale

scale: number

Sets both 'scaleX' and 'scaleY' to the same value. The getter simply returns the value of 'scaleX' (even if the scaling values are different). @default 1

scale9Grid

scale9Grid: Rectangle

The current scaling grid used for the button's state image. Use this property to create buttons that resize in a smart way, i.e. with the four corners keeping the same size and only stretching the center area.

@see Image#scale9Grid @default null

scaleWhenDown

scaleWhenDown: number

The scale factor of the button on touch. Per default, a button without a down state texture will be made slightly smaller, while a button with a down state texture remains unscaled.

scaleWhenOver

scaleWhenOver: number

The scale factor of the button while the mouse cursor hovers over it. @default 1.0

scaleX

scaleX: number

The horizontal scale factor. '1' means no scale, negative values flip the object.

default

1

scaleY

scaleY: number

The vertical scale factor. '1' means no scale, negative values flip the object.

default

1

skewX

skewX: number

The horizontal skew angle in radians.

skewY

skewY: number

The vertical skew angle in radians.

stage

stage: Stage

The stage the display object is connected to, or null if it is not connected to the stage.

state

state: string

The current state of the button. The corresponding strings are found in the ButtonState class.

style

style: MeshStyle

The style that is used to render the button. Note that a style instance may only be used on one mesh at a time.

text

text: string

The text that is displayed on the button.

textBounds

textBounds: Rectangle

The bounds of the textfield on the button. Allows moving the text to a custom position.

textFormat

textFormat: TextFormat

The format of the button's TextField.

textStyle

textStyle: MeshStyle

The style that is used to render the button's TextField.

textureSmoothing

textureSmoothing: string

The smoothing type used for the button's state image.

touchGroup

touchGroup: boolean

If a container is a 'touchGroup', it will act as a single touchable object. Touch events will have the container as target, not the touched child. (Similar to 'mouseChildren' in the classic display list, but with inverted logic.)

default

false

touchable

touchable: boolean

Indicates if this object (and its children) will receive touch events.

transformationMatrix

transformationMatrix: Matrix

The transformation matrix of the object relative to its parent.

If you assign a custom transformation matrix, Starling will try to figure out suitable values for x, y, scaleX, scaleY, and rotation. However, if the matrix was created in a different way, this might not be possible. In that case, Starling will apply the matrix, but not update the corresponding properties.

CAUTION: not a copy, but the actual object!

transformationMatrix3D

transformationMatrix3D: Matrix3D

The 3D transformation matrix of the object relative to its parent.

For 2D objects, this property returns just a 3D version of the 2D transformation matrix. Only the 'Sprite3D' class supports real 3D transformations.

CAUTION: not a copy, but the actual object!

upState

upState: Texture

The texture that is displayed when the button is not being touched.

useHandCursor

useHandCursor: boolean

Indicates if the mouse cursor should transform into a hand while it's over the sprite.

default

false

visible

visible: boolean

The visibility of the object. An invisible object will be untouchable.

width

width: number

The width of the object in pixels. Note that for objects in a 3D space (connected to a Sprite3D), this value might not be accurate until the object is part of the display list.

x

x: number

The x coordinate of the object relative to the local coordinates of the parent.

y

y: number

The y coordinate of the object relative to the local coordinates of the parent.

Methods

addChild

addChildAt

addEventListener

  • addEventListener(type: string, listener: Function): void

alignPivot

  • alignPivot(horizontalAlign?: string, verticalAlign?: string): void

broadcastEvent

  • broadcastEvent(event: Event): void

broadcastEventWith

  • broadcastEventWith(eventType: string, data?: any): void

contains

dispatchEvent

  • dispatchEvent(event: Event): void
  • Dispatches an event to all objects that have registered listeners for its type. If an event with enabled 'bubble' property is dispatched to a display object, it will travel up along the line of parents, until it either hits the root object or someone stops its propagation manually.

    Parameters

    Returns void

dispatchEventWith

  • dispatchEventWith(type: string, bubbles?: boolean, data?: any): void

dispose

  • dispose(): void

drawToBitmapData

  • drawToBitmapData(out?: BitmapData, color?: number, alpha?: number): BitmapData
  • Draws the object into a BitmapData object.

    This is achieved by drawing the object into the back buffer and then copying the pixels of the back buffer into a texture. This also means that the returned bitmap data cannot be bigger than the current viewPort.

    @param out If you pass null, the object will be created for you. If you pass a BitmapData object, it should have the size of the object bounds, multiplied by the current contentScaleFactor. @param color The RGB color value with which the bitmap will be initialized. @param alpha The alpha value with which the bitmap will be initialized.

    Parameters

    • Optional out: BitmapData
    • Optional color: number
    • Optional alpha: number

    Returns BitmapData

getBounds

  • getBounds(targetSpace: DisplayObject, out?: Rectangle): Rectangle

getChildAt

getChildByName

getChildIndex

getTransformationMatrix

  • getTransformationMatrix(targetSpace: DisplayObject, out?: Matrix): Matrix

getTransformationMatrix3D

  • getTransformationMatrix3D(targetSpace: DisplayObject, out?: Matrix3D): Matrix3D

Protected get_alpha

  • get_alpha(): number

Protected get_alphaWhenDisabled

  • get_alphaWhenDisabled(): number

Protected get_alphaWhenDown

  • get_alphaWhenDown(): number

Protected get_base

Protected get_blendMode

  • get_blendMode(): string

Protected get_bounds

  • get_bounds(): Rectangle

Protected get_color

  • get_color(): number

Protected get_disabledState

Protected get_downState

Protected get_enabled

  • get_enabled(): boolean

Protected get_filter

Protected get_height

  • get_height(): number

Protected get_is3D

  • get_is3D(): boolean

Protected get_mask

Protected get_maskInverted

  • get_maskInverted(): boolean

Protected get_name

  • get_name(): string

Protected get_numChildren

  • get_numChildren(): number

Protected get_overState

Protected get_overlay

Protected get_parent

Protected get_pivotX

  • get_pivotX(): number

Protected get_pivotY

  • get_pivotY(): number

Protected get_pixelSnapping

  • get_pixelSnapping(): boolean

Protected get_requiresRedraw

  • get_requiresRedraw(): boolean

Protected get_root

Protected get_rotation

  • get_rotation(): number

Protected get_scale

  • get_scale(): number

Protected get_scale9Grid

  • get_scale9Grid(): Rectangle

Protected get_scaleWhenDown

  • get_scaleWhenDown(): number

Protected get_scaleWhenOver

  • get_scaleWhenOver(): number

Protected get_scaleX

  • get_scaleX(): number

Protected get_scaleY

  • get_scaleY(): number

Protected get_skewX

  • get_skewX(): number

Protected get_skewY

  • get_skewY(): number

Protected get_stage

Protected get_state

  • get_state(): string

Protected get_style

Protected get_text

  • get_text(): string

Protected get_textBounds

  • get_textBounds(): Rectangle

Protected get_textFormat

Protected get_textStyle

Protected get_textureSmoothing

  • get_textureSmoothing(): string

Protected get_touchGroup

  • get_touchGroup(): boolean

Protected get_touchable

  • get_touchable(): boolean

Protected get_transformationMatrix

  • get_transformationMatrix(): Matrix

Protected get_transformationMatrix3D

  • get_transformationMatrix3D(): Matrix3D

Protected get_upState

Protected get_useHandCursor

  • get_useHandCursor(): boolean

Protected get_visible

  • get_visible(): boolean

Protected get_width

  • get_width(): number

Protected get_x

  • get_x(): number

Protected get_y

  • get_y(): number

globalToLocal

  • globalToLocal(globalPoint: Point, out?: Point): Point
  • Transforms a point from global (stage) coordinates to the local coordinate system. If you pass an out-point, the result will be stored in this point instead of creating a new object.

    Parameters

    • globalPoint: Point
    • Optional out: Point

    Returns Point

globalToLocal3D

  • globalToLocal3D(globalPoint: Point, out?: Vector3D): Vector3D
  • Transforms a point from global (stage) coordinates to the 3D local coordinate system. If you pass an out-vector, the result will be stored in this point instead of creating a new object.

    Parameters

    • globalPoint: Point
    • Optional out: Vector3D

    Returns Vector3D

hasEventListener

  • hasEventListener(type: string, listener?: any): boolean

hitTest

hitTestMask

  • hitTestMask(localPoint: Point): boolean

local3DToGlobal

  • local3DToGlobal(localPoint: Vector3D, out?: Point): Point
  • Transforms a 3D point from the local coordinate system to global (stage) coordinates. This is achieved by projecting the 3D point onto the (2D) view plane.

    If you pass an out-point, the result will be stored in this point instead of creating a new object.

    Parameters

    • localPoint: Vector3D
    • Optional out: Point

    Returns Point

localToGlobal

  • localToGlobal(localPoint: Point, out?: Point): Point
  • Transforms a point from the local coordinate system to global (stage) coordinates. If you pass an out-point, the result will be stored in this point instead of creating a new object.

    Parameters

    • localPoint: Point
    • Optional out: Point

    Returns Point

readjustSize

  • readjustSize(resetTextBounds?: boolean): void
  • Readjusts the dimensions of the button according to its current state texture. Call this method to synchronize button and texture size after assigning a texture with a different size. Per default, this method also resets the bounds of the button's text.

    Parameters

    • Optional resetTextBounds: boolean

    Returns void

removeChild

removeChildAt

removeChildren

  • removeChildren(beginIndex?: number, endIndex?: number, dispose?: boolean): void

removeEventListener

  • removeEventListener(type: string, listener: Function): void

removeEventListeners

  • removeEventListeners(type?: string): void

removeFromParent

  • removeFromParent(dispose?: boolean): void

render

setChildIndex

setRequiresRedraw

  • setRequiresRedraw(): void
  • Forces the object to be redrawn in the next frame. This will prevent the object to be drawn from the render cache.

    This method is called every time the object changes in any way. When creating custom mesh styles or any other custom rendering code, call this method if the object needs to be redrawn.

    If the object needs to be redrawn just because it does not support the render cache, call painter.excludeFromCache() in the object's render method instead. That way, Starling's skipUnchangedFrames policy won't be disrupted.

    Returns void

Protected set_alpha

  • set_alpha(value: number): number

Protected set_alphaWhenDisabled

  • set_alphaWhenDisabled(value: number): number

Protected set_alphaWhenDown

  • set_alphaWhenDown(value: number): number

Protected set_blendMode

  • set_blendMode(value: string): string

Protected set_color

  • set_color(value: number): number

Protected set_disabledState

Protected set_downState

Protected set_enabled

  • set_enabled(value: boolean): boolean

Protected set_filter

Protected set_height

  • set_height(value: number): number

Protected set_mask

Protected set_maskInverted

  • set_maskInverted(value: boolean): boolean

Protected set_name

  • set_name(value: string): string

Protected set_overState

Protected set_pivotX

  • set_pivotX(value: number): number

Protected set_pivotY

  • set_pivotY(value: number): number

Protected set_pixelSnapping

  • set_pixelSnapping(value: boolean): boolean

Protected set_rotation

  • set_rotation(value: number): number

Protected set_scale

  • set_scale(value: number): number

Protected set_scale9Grid

  • set_scale9Grid(value: Rectangle): Rectangle

Protected set_scaleWhenDown

  • set_scaleWhenDown(value: number): number

Protected set_scaleWhenOver

  • set_scaleWhenOver(value: number): number

Protected set_scaleX

  • set_scaleX(value: number): number

Protected set_scaleY

  • set_scaleY(value: number): number

Protected set_skewX

  • set_skewX(value: number): number

Protected set_skewY

  • set_skewY(value: number): number

Protected set_state

  • set_state(value: string): string

Protected set_style

Protected set_text

  • set_text(value: string): string

Protected set_textBounds

  • set_textBounds(value: Rectangle): Rectangle

Protected set_textFormat

Protected set_textStyle

Protected set_textureSmoothing

  • set_textureSmoothing(value: string): string

Protected set_touchGroup

  • set_touchGroup(value: boolean): boolean

Protected set_touchable

  • set_touchable(value: boolean): boolean

Protected set_transformationMatrix

  • set_transformationMatrix(matrix: Matrix): Matrix

Protected set_upState

Protected set_useHandCursor

  • set_useHandCursor(value: boolean): boolean

Protected set_visible

  • set_visible(value: boolean): boolean

Protected set_width

  • set_width(value: number): number

Protected set_x

  • set_x(value: number): number

Protected set_y

  • set_y(value: number): number

sortChildren

  • sortChildren(compareFunction: function): void

swapChildren

swapChildrenAt

  • swapChildrenAt(index1: number, index2: number): void

Generated using TypeDoc