Creates a button with a set of state-textures and (optionally) some text. Any state that is left 'null' will display the up-state texture. Beware that all state textures should have the same dimensions.
The opacity of the object. 0 = transparent, 1 = opaque. @default 1
The alpha value of the button when it is disabled. @default 0.5
The alpha value of the button on touch. @default 1.0
The topmost object in the display tree the object is part of.
The blend mode determines how the object is blended with the objects underneath.
The bounds of the object relative to the local coordinates of the parent.
The color of the button's state image. Just like every image object, each pixel's color is multiplied with this value. @default white
The texture that is displayed when the button is disabled.
The texture that is displayed while the button is touched.
Indicates if the button can be triggered.
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
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.
Indicates if this object or any of its parents is a 'Sprite3D' object.
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
Indicates if the masked region of this object is set to be inverted.
The name of the display object (default: null). Used by 'getChildByName()' of display object containers.
The number of children of this container.
The texture that is displayed while mouse hovers over the button.
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).
The display object container that contains this display object.
The x coordinate of the object's origin in its own coordinate space (default: 0).
The y coordinate of the object's origin in its own coordinate space (default: 0).
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
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.
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.
The rotation of the object in radians. (In Starling, all angles are measured in radians.)
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
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
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.
The scale factor of the button while the mouse cursor hovers over it. @default 1.0
The horizontal scale factor. '1' means no scale, negative values flip the object.
The vertical scale factor. '1' means no scale, negative values flip the object.
The horizontal skew angle in radians.
The vertical skew angle in radians.
The stage the display object is connected to, or null if it is not connected to the stage.
The current state of the button. The corresponding strings are found in the ButtonState class.
The style that is used to render the button. Note that a style instance may only be used on one mesh at a time.
The text that is displayed on the button.
The bounds of the textfield on the button. Allows moving the text to a custom position.
The format of the button's TextField.
The style that is used to render the button's TextField.
The smoothing type used for the button's state image.
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.)
Indicates if this object (and its children) will receive touch events.
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!
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!
The texture that is displayed when the button is not being touched.
Indicates if the mouse cursor should transform into a hand while it's over the sprite.
The visibility of the object. An invisible object will be untouchable.
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.
The x coordinate of the object relative to the local coordinates of the parent.
The y coordinate of the object relative to the local coordinates of the parent.
Adds a child to the container. It will be at the frontmost position.
Adds a child to the container at a certain index.
Moves the pivot point to a certain position within the local coordinate system of the object. If you pass no arguments, it will be centered.
Dispatches an event on all children (recursively). The event must not bubble.
Dispatches an event with the given parameters on all children (recursively). The method uses an internal pool of event objects to avoid allocations.
Determines if a certain object is a child of the container (recursively).
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.
Dispatches an event with the given parameters to all objects that have registered listeners for the given type. The method uses an internal pool of event objects to avoid allocations.
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.
Returns a child object at a certain index. If you pass a negative index, '-1' will return the last child, '-2' the second to last child, etc.
Returns a child object with a certain name (non-recursively).
Returns the index of a child within the container, or "-1" if it is not found.
Creates a matrix that represents the transformation from the local coordinate system
to another. If you pass an out
-matrix, the result will be stored in this matrix
instead of creating a new object.
Creates a matrix that represents the transformation from the local coordinate system
to another. This method supports three dimensional objects created via 'Sprite3D'.
If you pass an out
-matrix, the result will be stored in this matrix
instead of creating a new object.
Indicates if the mouse cursor should transform into a hand while it's over the button.
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.
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.
If called with one argument, figures out if there are any listeners registered for the given event type. If called with two arguments, also determines if a specific listener is registered.
Checks if a certain point is inside the display object's mask. If there is no mask,
this method always returns true
(because having no mask is equivalent
to having one that's infinitely big).
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.
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.
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.
Removes a child from the container. If the object is not a child, the method returns
null
. If requested, the child will be disposed right away.
Removes a child at a certain index. The index positions of any display objects above the child are decreased by 1. If requested, the child will be disposed right away.
Removes a range of children from the container (endIndex included). If no arguments are given, all children will be removed.
Removes the object from its parent, if it has one, and optionally disposes it.
Moves a child to a certain index. Children at and after the replaced position move up.
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.
Sorts the children according to a given (that works just like the sort function of the Vector class).
Swaps the indexes of two children.
Swaps the indexes of two children.
Generated using TypeDoc
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.