APIdia Launch Partner
Top Description Fields Constructors Methods
com.badlogic.gdx.scenes.scene2d

public Class Actor

extends Object
Class Inheritance
Known Direct Subclasses
com.badlogic.gdx.scenes.scene2d.Group, com.badlogic.gdx.scenes.scene2d.ui.ParticleEffectActor, com.badlogic.gdx.scenes.scene2d.ui.Widget
Static Imports
com.badlogic.gdx.utils.Align.*

2D scene graph node. An actor has a position, rectangular size, origin, scale, rotation, Z index, and color. The position corresponds to the unrotated, unscaled bottom left corner of the actor. The position is relative to the actor's parent. The origin is relative to the position and is used for scale and rotation.

An actor has a list of in progress actions that are applied to the actor (often over time). These are generally used to change the presentation of the actor (moving it, resizing it, etc). See act(float), Action, and its many subclasses.

An actor has two kinds of listeners associated with it: "capture" and regular. The listeners are notified of events the actor or its children receive. The regular listeners are designed to allow an actor to respond to events that have been delivered. The capture listeners are designed to allow a parent or container actor to handle events before child actors. See fire for more details.

An InputListener can receive all the basic input events. More complex listeners (like ClickListener and ActorGestureListener) can listen for and combine primitive events and recognize complex interactions like multi-touch or pinch.

Authors
mzechner, Nathan Sweet

Field Summary

Modifier and TypeField and Description
private final Array<Action>
private final DelayedRemovalArray<EventListener>
pack-priv final Color
private boolean
pack-priv float
private final DelayedRemovalArray<EventListener>
private String
pack-priv float
pack-priv float
pack-priv Group
public static PoolManager
pack-priv float
pack-priv float
pack-priv float
private Stage
private Touchable
private Object
private boolean
pack-priv float
pack-priv float
x

pack-priv float
y

Constructor Summary

AccessConstructor and Description
public

Method Summary

Modifier and TypeMethod and Description
public void
act(float
Time in seconds since the last frame.
delta
)

Updates the actor based on time.

public void
addAction(Action action)

public boolean
addCaptureListener(EventListener listener)

Adds a listener that is only notified during the capture phase.

public boolean
addListener(EventListener listener)

Add a listener to receive events that hit this actor.

public boolean
public boolean
ascendantsVisible()

Returns true if this actor and all ascendants are visible.

public void
clear()

Removes all actions and listeners on this actor.

public void
clearActions()

Removes all actions on this actor.

public void
clearListeners()

Removes all listeners on this actor.

public boolean
clipBegin()

Calls clipBegin(float, float, float, float) to clip this actor's bounds.

public boolean

Returns:

false if the clipping area is zero and no drawing should occur.
clipBegin
(float x, float y, float width, float height)

Clips the specified screen aligned rectangle, specified relative to the transform matrix of the stage's Batch.

public void
public Actor
debug()

Calls setDebug(boolean) with true.

public void
draw(Batch batch, float
The parent alpha, to be multiplied with this actor's alpha, allowing the parent's alpha to affect all children.
parentAlpha
)

Draws the actor.

public void
drawDebug(ShapeRenderer shapes)

Draws this actor's debug lines if getDebug() is true.

protected void
drawDebugBounds(ShapeRenderer shapes)

Draws a rectangle for the bounds of this actor if getDebug() is true.

public boolean

Returns:

true if the event was cancelled.
fire
(Event event)

Sets this actor as the event target and propagates the event to this actor and ascendants as necessary.

public <T extends Actor> T
firstAscendant(Class<T> type)

Returns this actor or the first ascendant of this actor that is assignable with the specified type, or null if none were found.

public Array<Action>
public DelayedRemovalArray<EventListener>
public Color
getColor()

Returns the color the actor will be tinted when drawn.

public boolean
public float
public DelayedRemovalArray<EventListener>
public String
getName()

Returns: May be null.

public float
public float
public Group
getParent()

Returns the parent actor, or null if not in a group.

public float
getRight()

Returns x plus width.

public float
public float
public float
public Stage
getStage()

Returns the stage that this actor is currently in, or null if not in a stage.

public float
getTop()

Returns y plus height.

public Touchable
public Object
getUserObject()

Returns an application specific object for convenience, or null.

public float
public float
getX()

Returns the X position of the actor's left edge.

public float
getX(int alignment)

Returns the X position of the specified alignment.

public float
getY()

Returns the Y position of the actor's bottom edge.

public float
getY(int alignment)

Returns the Y position of the specified alignment.

public int
getZIndex()

Returns the z-index of this actor, or -1 if the actor is not in a group.

public boolean
hasActions()

Returns true if the actor has one or more actions.

public boolean
hasKeyboardFocus()

Returns true if this actor is the keyboard focus actor.

public boolean
hasParent()

Returns true if the actor's parent is not null.

public boolean
hasScrollFocus()

Returns true if this actor is the scroll focus actor.

public Actor
hit(float x, float y, boolean
If true, hit detection will respect the touchability.
touchable
)

Returns the deepest visible (and optionally, touchable) actor that contains the specified point, or null if no actor was hit.

public boolean
isAscendantOf(Actor actor)

Returns true if this actor is the same as or is the ascendant of the specified actor.

public boolean
isDescendantOf(Actor actor)

Returns true if this actor is the same as or is the descendant of the specified actor.

public boolean
isTouchable()

Returns true if input events are processed by this actor.

public boolean
isTouchFocusListener()

Returns true if this actor is a listener actor for touch focus.

public boolean
isTouchFocusTarget()

Returns true if this actor is a target actor for touch focus.

public boolean
public Vector2
localToActorCoordinates(Actor actor, Vector2 localCoords)

Converts coordinates for this actor to those of another actor, which can be anywhere in the stage.

public Vector2
localToAscendantCoordinates(Actor ascendant, Vector2 localCoords)

Converts coordinates for this actor to those of an ascendant.

public Vector2
localToParentCoordinates(Vector2 localCoords)

Transforms the specified point in the actor's coordinates to be in the parent's coordinates.

public Vector2
localToScreenCoordinates(Vector2 localCoords)

Transforms the specified point in the actor's coordinates to be in screen coordinates.

public Vector2
localToStageCoordinates(Vector2 localCoords)

Transforms the specified point in the actor's coordinates to be in the stage's coordinates.

public void
moveBy(float x, float y)

Add x and y to current position

public boolean

Returns:

true if the event was cancelled.
notify
(Event event, boolean
If true, the capture listeners will be notified instead of the regular listeners.
capture
)

Notifies this actor's listeners of the event.

public Vector2
parentToLocalCoordinates(Vector2 parentCoords)

Converts the coordinates given in the parent's coordinate system to this actor's coordinate system.

protected void
positionChanged()

Called when the actor's position has been changed.

public boolean
remove()

Removes this actor from its parent, if it has a parent.

public void
removeAction(Action
May be null, in which case nothing is done.
action
)

public boolean
public boolean
public void
rotateBy(float amountInDegrees)

Adds the specified rotation to the current rotation.

protected void
rotationChanged()

Called when the actor's rotation has been changed.

public void
scaleBy(float scale)

Adds the specified scale to the current scale.

public void
scaleBy(float scaleX, float scaleY)

Adds the specified scale to the current scale.

protected void
scaleChanged()

Called when the actor's scale has been changed.

public Vector2
screenToLocalCoordinates(Vector2 screenCoords)

Transforms the specified point in screen coordinates to the actor's local coordinate system.

public void
setBounds(float x, float y, float width, float height)

Set bounds the x, y, width, and height.

public void
setColor(Color color)

public void
setColor(float r, float g, float b, float a)

public void
setDebug(boolean enabled)

If true, drawDebug(ShapeRenderer) will be called for this actor.

public void
setHeight(float height)

public void
setName(String
May be null.
name
)

Set the actor's name, which is used for identification convenience and by toString().

public void
setOrigin(float originX, float originY)

Sets the origin position which is relative to the actor's bottom left corner.

public void
setOrigin(int alignment)

Sets the origin position to the specified alignment.

public void
setOriginX(float originX)

public void
setOriginY(float originY)

protected void
setParent(Group
May be null if the actor has been removed from the parent.
parent
)

Called by the framework when an actor is added to or removed from a group.

public void
setPosition(float x, float y)

Sets the position of the actor's bottom left corner.

public void
setPosition(float x, float y, int alignment)

Sets the position using the specified alignment.

public void
setRotation(float degrees)

public void
setScale(float scaleXY)

Sets the scale for both X and Y

public void
setScale(float scaleX, float scaleY)

Sets the scale X and scale Y.

public void
setScaleX(float scaleX)

public void
setScaleY(float scaleY)

public void
setSize(float width, float height)

Sets the width and height.

protected void
setStage(Stage
May be null if the actor or any ascendant is no longer in a stage.
stage
)

Called by the framework when this actor or any ascendant is added to a group that is in the stage.

public void
setTouchable(Touchable touchable)

Determines how touch events are distributed to this actor.

public void
setUserObject(Object userObject)

Sets an application specific object for convenience.

public void
setVisible(boolean visible)

If false, the actor will not be drawn and will not receive touch events.

public void
setWidth(float width)

public void
setX(float x)

public void
setX(float x, int alignment)

Sets the x position using the specified alignment.

public void
setY(float y)

public void
setY(float y, int alignment)

Sets the y position using the specified alignment.

public boolean

Returns:

true if the z-index changed.
setZIndex
(int index)

Sets the z-index of this actor.

public void
sizeBy(float size)

Adds the specified size to the current size.

public void
sizeBy(float width, float height)

Adds the specified size to the current size.

protected void
sizeChanged()

Called when the actor's size has been changed.

public Vector2
stageToLocalCoordinates(Vector2 stageCoords)

Transforms the specified point in the stage's coordinates to the actor's local coordinate system.

public void
toBack()

Changes the z-order for this actor so it is in back of all siblings.

public void
toFront()

Changes the z-order for this actor so it is in front of all siblings.

public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

actionsback to summary
private final Array<Action> actions
captureListenersback to summary
private final DelayedRemovalArray<EventListener> captureListeners
colorback to summary
pack-priv final Color color
debugback to summary
private boolean debug
heightback to summary
pack-priv float height
listenersback to summary
private final DelayedRemovalArray<EventListener> listeners
nameback to summary
private String name
Annotations
@Null
originXback to summary
pack-priv float originX
originYback to summary
pack-priv float originY
parentback to summary
pack-priv Group parent
Annotations
@Null
POOLSback to summary
public static PoolManager POOLS
rotationback to summary
pack-priv float rotation
scaleXback to summary
pack-priv float scaleX
scaleYback to summary
pack-priv float scaleY
stageback to summary
private Stage stage
Annotations
@Null
touchableback to summary
private Touchable touchable
userObjectback to summary
private Object userObject
Annotations
@Null
visibleback to summary
private boolean visible
widthback to summary
pack-priv float width
xback to summary
pack-priv float x
yback to summary
pack-priv float y

Constructor Detail

Actorback to summary
public Actor()

Method Detail

actback to summary
public void act(float delta)

Updates the actor based on time. Typically this is called each frame by Stage#act(float).

The default implementation calls Action#act(float) on each action and removes actions that are complete.

Parameters
delta:float

Time in seconds since the last frame.

addActionback to summary
public void addAction(Action action)
addCaptureListenerback to summary
public boolean addCaptureListener(EventListener listener)

Adds a listener that is only notified during the capture phase.

See Also
fire(Event)
addListenerback to summary
public boolean addListener(EventListener listener)

Add a listener to receive events that hit this actor. See fire(Event).

See Also
InputListener, ClickListener
ancestorsVisibleback to summary
public boolean ancestorsVisible()

Deprecated

Use ascendantsVisible().

Annotations
@Deprecated
ascendantsVisibleback to summary
public boolean ascendantsVisible()

Returns true if this actor and all ascendants are visible.

clearback to summary
public void clear()

Removes all actions and listeners on this actor.

clearActionsback to summary
public void clearActions()

Removes all actions on this actor.

clearListenersback to summary
public void clearListeners()

Removes all listeners on this actor.

clipBeginback to summary
public boolean clipBegin()

Calls clipBegin(float, float, float, float) to clip this actor's bounds.

clipBeginback to summary
public boolean clipBegin(float x, float y, float width, float height)

Clips the specified screen aligned rectangle, specified relative to the transform matrix of the stage's Batch. The transform matrix and the stage's camera must not have rotational components. Calling this method must be followed by a call to clipEnd() if true is returned.

Returns:boolean

false if the clipping area is zero and no drawing should occur.

See Also
ScissorStack
clipEndback to summary
public void clipEnd()

Ends clipping begun by clipBegin(float, float, float, float).

debugback to summary
public Actor debug()

Calls setDebug(boolean) with true.

drawback to summary
public void draw(Batch batch, float parentAlpha)

Draws the actor. The batch is configured to draw in the parent's coordinate system. This draw method is convenient to draw a rotated and scaled TextureRegion. Batch#begin() has already been called on the batch. If Batch#end() is called to draw without the batch then Batch#begin() must be called before the method returns.

The default implementation does nothing.

Parameters
parentAlpha:float

The parent alpha, to be multiplied with this actor's alpha, allowing the parent's alpha to affect all children.

drawDebugback to summary
public void drawDebug(ShapeRenderer shapes)

Draws this actor's debug lines if getDebug() is true.

drawDebugBoundsback to summary
protected void drawDebugBounds(ShapeRenderer shapes)

Draws a rectangle for the bounds of this actor if getDebug() is true.

fireback to summary
public boolean fire(Event event)

Sets this actor as the event target and propagates the event to this actor and ascendants as necessary. If this actor is not in the stage, the stage must be set before calling this method.

Events are fired in 2 phases:

  1. The first phase (the "capture" phase) notifies listeners on each actor starting at the root and propagating down the hierarchy to (and including) this actor.
  2. The second phase notifies listeners on each actor starting at this actor and, if Event#getBubbles() is true, propagating upward to the root.
If the event is stopped at any time, it will not propagate to the next actor.
Returns:boolean

true if the event was cancelled.

firstAscendantback to summary
public <T extends Actor> T firstAscendant(Class<T> type)

Returns this actor or the first ascendant of this actor that is assignable with the specified type, or null if none were found.

Annotations
@Null
getActionsback to summary
public Array<Action> getActions()
getCaptureListenersback to summary
public DelayedRemovalArray<EventListener> getCaptureListeners()
getColorback to summary
public Color getColor()

Returns the color the actor will be tinted when drawn. The returned instance can be modified to change the color.

getDebugback to summary
public boolean getDebug()
getHeightback to summary
public float getHeight()
getListenersback to summary
public DelayedRemovalArray<EventListener> getListeners()
getNameback to summary
public String getName()
Returns:String

May be null.

Annotations
@Null
See Also
setName(String)
getOriginXback to summary
public float getOriginX()
getOriginYback to summary
public float getOriginY()
getParentback to summary
public Group getParent()

Returns the parent actor, or null if not in a group.

Annotations
@Null
getRightback to summary
public float getRight()

Returns x plus width.

getRotationback to summary
public float getRotation()
getScaleXback to summary
public float getScaleX()
getScaleYback to summary
public float getScaleY()
getStageback to summary
public Stage getStage()

Returns the stage that this actor is currently in, or null if not in a stage.

Annotations
@Null
getTopback to summary
public float getTop()

Returns y plus height.

getTouchableback to summary
public Touchable getTouchable()
getUserObjectback to summary
public Object getUserObject()

Returns an application specific object for convenience, or null.

Annotations
@Null
getWidthback to summary
public float getWidth()
getXback to summary
public float getX()

Returns the X position of the actor's left edge.

getXback to summary
public float getX(int alignment)

Returns the X position of the specified alignment.

getYback to summary
public float getY()

Returns the Y position of the actor's bottom edge.

getYback to summary
public float getY(int alignment)

Returns the Y position of the specified alignment.

getZIndexback to summary
public int getZIndex()

Returns the z-index of this actor, or -1 if the actor is not in a group.

See Also
setZIndex(int)
hasActionsback to summary
public boolean hasActions()

Returns true if the actor has one or more actions.

hasKeyboardFocusback to summary
public boolean hasKeyboardFocus()

Returns true if this actor is the keyboard focus actor.

hasParentback to summary
public boolean hasParent()

Returns true if the actor's parent is not null.

hasScrollFocusback to summary
public boolean hasScrollFocus()

Returns true if this actor is the scroll focus actor.

hitback to summary
public Actor hit(float x, float y, boolean touchable)

Returns the deepest visible (and optionally, touchable) actor that contains the specified point, or null if no actor was hit. The point is specified in the actor's local coordinate system (0,0 is the bottom left of the actor and width,height is the upper right).

This method is used to delegate touchDown, mouse, and enter/exit events. If this method returns null, those events will not occur on this Actor.

The default implementation returns this actor if the point is within this actor's bounds and this actor is visible.

Parameters
touchable:boolean

If true, hit detection will respect the touchability.

Annotations
@Null
See Also
Touchable
isAscendantOfback to summary
public boolean isAscendantOf(Actor actor)

Returns true if this actor is the same as or is the ascendant of the specified actor.

isDescendantOfback to summary
public boolean isDescendantOf(Actor actor)

Returns true if this actor is the same as or is the descendant of the specified actor.

isTouchableback to summary
public boolean isTouchable()

Returns true if input events are processed by this actor.

isTouchFocusListenerback to summary
public boolean isTouchFocusListener()

Returns true if this actor is a listener actor for touch focus.

See Also
Stage#addTouchFocus(EventListener, Actor, Actor, int, int)
isTouchFocusTargetback to summary
public boolean isTouchFocusTarget()

Returns true if this actor is a target actor for touch focus.

See Also
Stage#addTouchFocus(EventListener, Actor, Actor, int, int)
isVisibleback to summary
public boolean isVisible()
localToActorCoordinatesback to summary
public Vector2 localToActorCoordinates(Actor actor, Vector2 localCoords)

Converts coordinates for this actor to those of another actor, which can be anywhere in the stage.

localToAscendantCoordinatesback to summary
public Vector2 localToAscendantCoordinates(Actor ascendant, Vector2 localCoords)

Converts coordinates for this actor to those of an ascendant. The ascendant is not required to be the immediate parent.

Exceptions
IllegalArgumentException:
if the specified actor is not an ascendant of this actor.
localToParentCoordinatesback to summary
public Vector2 localToParentCoordinates(Vector2 localCoords)

Transforms the specified point in the actor's coordinates to be in the parent's coordinates.

localToScreenCoordinatesback to summary
public Vector2 localToScreenCoordinates(Vector2 localCoords)

Transforms the specified point in the actor's coordinates to be in screen coordinates.

See Also
Stage#stageToScreenCoordinates(Vector2)
localToStageCoordinatesback to summary
public Vector2 localToStageCoordinates(Vector2 localCoords)

Transforms the specified point in the actor's coordinates to be in the stage's coordinates.

moveByback to summary
public void moveBy(float x, float y)

Add x and y to current position

notifyback to summary
public boolean notify(Event event, boolean capture)

Notifies this actor's listeners of the event. The event is not propagated to any ascendants. The event target must be set before calling this method. Before notifying the listeners, this actor is set as the listener actor. If this actor is not in the stage, the stage must be set before calling this method.

Parameters
capture:boolean

If true, the capture listeners will be notified instead of the regular listeners.

Returns:boolean

true if the event was cancelled.

parentToLocalCoordinatesback to summary
public Vector2 parentToLocalCoordinates(Vector2 parentCoords)

Converts the coordinates given in the parent's coordinate system to this actor's coordinate system.

positionChangedback to summary
protected void positionChanged()

Called when the actor's position has been changed.

removeback to summary
public boolean remove()

Removes this actor from its parent, if it has a parent.

See Also
Group#removeActor(Actor)
removeActionback to summary
public void removeAction(Action action)
Parameters
action:Action

May be null, in which case nothing is done.

removeCaptureListenerback to summary
public boolean removeCaptureListener(EventListener listener)
removeListenerback to summary
public boolean removeListener(EventListener listener)
rotateByback to summary
public void rotateBy(float amountInDegrees)

Adds the specified rotation to the current rotation.

rotationChangedback to summary
protected void rotationChanged()

Called when the actor's rotation has been changed.

scaleByback to summary
public void scaleBy(float scale)

Adds the specified scale to the current scale.

scaleByback to summary
public void scaleBy(float scaleX, float scaleY)

Adds the specified scale to the current scale.

scaleChangedback to summary
protected void scaleChanged()

Called when the actor's scale has been changed.

screenToLocalCoordinatesback to summary
public Vector2 screenToLocalCoordinates(Vector2 screenCoords)

Transforms the specified point in screen coordinates to the actor's local coordinate system.

See Also
Stage#screenToStageCoordinates(Vector2)
setBoundsback to summary
public void setBounds(float x, float y, float width, float height)

Set bounds the x, y, width, and height.

setColorback to summary
public void setColor(Color color)
setColorback to summary
public void setColor(float r, float g, float b, float a)
setDebugback to summary
public void setDebug(boolean enabled)

If true, drawDebug(ShapeRenderer) will be called for this actor.

setHeightback to summary
public void setHeight(float height)
setNameback to summary
public void setName(String name)

Set the actor's name, which is used for identification convenience and by toString().

Parameters
name:String

May be null.

See Also
Group#findActor(String)
setOriginback to summary
public void setOrigin(float originX, float originY)

Sets the origin position which is relative to the actor's bottom left corner.

setOriginback to summary
public void setOrigin(int alignment)

Sets the origin position to the specified alignment.

setOriginXback to summary
public void setOriginX(float originX)
setOriginYback to summary
public void setOriginY(float originY)
setParentback to summary
protected void setParent(Group parent)

Called by the framework when an actor is added to or removed from a group.

Parameters
parent:Group

May be null if the actor has been removed from the parent.

setPositionback to summary
public void setPosition(float x, float y)

Sets the position of the actor's bottom left corner.

setPositionback to summary
public void setPosition(float x, float y, int alignment)

Sets the position using the specified alignment. Note this may set the position to non-integer coordinates.

setRotationback to summary
public void setRotation(float degrees)
setScaleback to summary
public void setScale(float scaleXY)

Sets the scale for both X and Y

setScaleback to summary
public void setScale(float scaleX, float scaleY)

Sets the scale X and scale Y.

setScaleXback to summary
public void setScaleX(float scaleX)
setScaleYback to summary
public void setScaleY(float scaleY)
setSizeback to summary
public void setSize(float width, float height)

Sets the width and height.

setStageback to summary
protected void setStage(Stage stage)

Called by the framework when this actor or any ascendant is added to a group that is in the stage.

Parameters
stage:Stage

May be null if the actor or any ascendant is no longer in a stage.

setTouchableback to summary
public void setTouchable(Touchable touchable)

Determines how touch events are distributed to this actor. Default is Touchable#enabled.

setUserObjectback to summary
public void setUserObject(Object userObject)

Sets an application specific object for convenience.

setVisibleback to summary
public void setVisible(boolean visible)

If false, the actor will not be drawn and will not receive touch events. Default is true.

setWidthback to summary
public void setWidth(float width)
setXback to summary
public void setX(float x)
setXback to summary
public void setX(float x, int alignment)

Sets the x position using the specified alignment. Note this may set the position to non-integer coordinates.

setYback to summary
public void setY(float y)
setYback to summary
public void setY(float y, int alignment)

Sets the y position using the specified alignment. Note this may set the position to non-integer coordinates.

setZIndexback to summary
public boolean setZIndex(int index)

Sets the z-index of this actor. The z-index is the index into the parent's children, where a lower index is below a higher index. Setting a z-index higher than the number of children will move the child to the front. Setting a z-index less than zero is invalid.

Returns:boolean

true if the z-index changed.

sizeByback to summary
public void sizeBy(float size)

Adds the specified size to the current size.

sizeByback to summary
public void sizeBy(float width, float height)

Adds the specified size to the current size.

sizeChangedback to summary
protected void sizeChanged()

Called when the actor's size has been changed.

stageToLocalCoordinatesback to summary
public Vector2 stageToLocalCoordinates(Vector2 stageCoords)

Transforms the specified point in the stage's coordinates to the actor's local coordinate system.

toBackback to summary
public void toBack()

Changes the z-order for this actor so it is in back of all siblings.

toFrontback to summary
public void toFront()

Changes the z-order for this actor so it is in front of all siblings.

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.