Class Actor
- java.lang.Object
-
- com.badlogic.gdx.scenes.scene2d.Actor
-
- Direct Known Subclasses:
Group
,ParticleEffectActor
,Widget
public class Actor extends java.lang.Object
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). Seeact(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(com.badlogic.gdx.scenes.scene2d.Event)
for more details.An
InputListener
can receive all the basic input events. More complex listeners (likeClickListener
andActorGestureListener
) can listen for and combine primitive events and recognize complex interactions like multi-touch or pinch.
-
-
Constructor Summary
Constructors Constructor Description Actor()
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
act(float delta)
Updates the actor based on time.void
addAction(Action action)
boolean
addCaptureListener(EventListener listener)
Adds a listener that is only notified during the capture phase.boolean
addListener(EventListener listener)
Add a listener to receive events thathit
this actor.boolean
ancestorsVisible()
Deprecated.UseascendantsVisible()
.boolean
ascendantsVisible()
Returns true if this actor and all ascendants are visible.void
clear()
Removes all actions and listeners on this actor.void
clearActions()
Removes all actions on this actor.void
clearListeners()
Removes all listeners on this actor.boolean
clipBegin()
CallsclipBegin(float, float, float, float)
to clip this actor's bounds.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.void
clipEnd()
Ends clipping begun byclipBegin(float, float, float, float)
.Actor
debug()
CallssetDebug(boolean)
withtrue
.void
draw(Batch batch, float parentAlpha)
Draws the actor.void
drawDebug(ShapeRenderer shapes)
Draws this actor's debug lines ifgetDebug()
is true.protected void
drawDebugBounds(ShapeRenderer shapes)
Draws a rectangle for the bounds of this actor ifgetDebug()
is true.boolean
fire(Event event)
Sets this actor as the eventtarget
and propagates the event to this actor and ascendants as necessary.<T extends Actor>
TfirstAscendant(java.lang.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.Array<Action>
getActions()
DelayedRemovalArray<EventListener>
getCaptureListeners()
Color
getColor()
Returns the color the actor will be tinted when drawn.boolean
getDebug()
float
getHeight()
DelayedRemovalArray<EventListener>
getListeners()
java.lang.String
getName()
float
getOriginX()
float
getOriginY()
Group
getParent()
Returns the parent actor, or null if not in a group.float
getRight()
Returns x plus width.float
getRotation()
float
getScaleX()
float
getScaleY()
Stage
getStage()
Returns the stage that this actor is currently in, or null if not in a stage.float
getTop()
Returns y plus height.Touchable
getTouchable()
java.lang.Object
getUserObject()
Returns an application specific object for convenience, or null.float
getWidth()
float
getX()
Returns the X position of the actor's left edge.float
getX(int alignment)
Returns the X position of the specifiedalignment
.float
getY()
Returns the Y position of the actor's bottom edge.float
getY(int alignment)
Returns the Y position of the specifiedalignment
.int
getZIndex()
Returns the z-index of this actor, or -1 if the actor is not in a group.boolean
hasActions()
Returns true if the actor has one or more actions.boolean
hasKeyboardFocus()
Returns true if this actor is thekeyboard focus
actor.boolean
hasParent()
Returns true if the actor's parent is not null.boolean
hasScrollFocus()
Returns true if this actor is thescroll focus
actor.Actor
hit(float x, float y, boolean touchable)
boolean
isAscendantOf(Actor actor)
Returns true if this actor is the same as or is the ascendant of the specified actor.boolean
isDescendantOf(Actor actor)
Returns true if this actor is the same as or is the descendant of the specified actor.boolean
isTouchable()
Returns true if input events are processed by this actor.boolean
isTouchFocusListener()
Returns true if this actor is a listener actor for touch focus.boolean
isTouchFocusTarget()
Returns true if this actor is a target actor for touch focus.boolean
isVisible()
Vector2
localToActorCoordinates(Actor actor, Vector2 localCoords)
Converts coordinates for this actor to those of another actor, which can be anywhere in the stage.Vector2
localToAscendantCoordinates(Actor ascendant, Vector2 localCoords)
Converts coordinates for this actor to those of an ascendant.Vector2
localToParentCoordinates(Vector2 localCoords)
Transforms the specified point in the actor's coordinates to be in the parent's coordinates.Vector2
localToScreenCoordinates(Vector2 localCoords)
Transforms the specified point in the actor's coordinates to be in screen coordinates.Vector2
localToStageCoordinates(Vector2 localCoords)
Transforms the specified point in the actor's coordinates to be in the stage's coordinates.void
moveBy(float x, float y)
Add x and y to current positionboolean
notify(Event event, boolean capture)
Notifies this actor's listeners of the event.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.boolean
remove()
Removes this actor from its parent, if it has a parent.void
removeAction(Action action)
boolean
removeCaptureListener(EventListener listener)
boolean
removeListener(EventListener listener)
void
rotateBy(float amountInDegrees)
Adds the specified rotation to the current rotation.protected void
rotationChanged()
Called when the actor's rotation has been changed.void
scaleBy(float scale)
Adds the specified scale to the current scale.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.Vector2
screenToLocalCoordinates(Vector2 screenCoords)
Transforms the specified point in screen coordinates to the actor's local coordinate system.void
setBounds(float x, float y, float width, float height)
Set bounds the x, y, width, and height.void
setColor(float r, float g, float b, float a)
void
setColor(Color color)
void
setDebug(boolean enabled)
If true,drawDebug(ShapeRenderer)
will be called for this actor.void
setHeight(float height)
void
setName(java.lang.String name)
Set the actor's name, which is used for identification convenience and bytoString()
.void
setOrigin(float originX, float originY)
Sets the origin position which is relative to the actor's bottom left corner.void
setOrigin(int alignment)
Sets the origin position to the specifiedalignment
.void
setOriginX(float originX)
void
setOriginY(float originY)
protected void
setParent(Group parent)
Called by the framework when an actor is added to or removed from a group.void
setPosition(float x, float y)
Sets the position of the actor's bottom left corner.void
setPosition(float x, float y, int alignment)
Sets the position using the specifiedalignment
.void
setRotation(float degrees)
void
setScale(float scaleXY)
Sets the scale for both X and Yvoid
setScale(float scaleX, float scaleY)
Sets the scale X and scale Y.void
setScaleX(float scaleX)
void
setScaleY(float scaleY)
void
setSize(float width, float height)
Sets the width and height.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.void
setTouchable(Touchable touchable)
Determines how touch events are distributed to this actor.void
setUserObject(java.lang.Object userObject)
Sets an application specific object for convenience.void
setVisible(boolean visible)
If false, the actor will not be drawn and will not receive touch events.void
setWidth(float width)
void
setX(float x)
void
setX(float x, int alignment)
Sets the x position using the specifiedalignment
.void
setY(float y)
void
setY(float y, int alignment)
Sets the y position using the specifiedalignment
.boolean
setZIndex(int index)
Sets the z-index of this actor.void
sizeBy(float size)
Adds the specified size to the current size.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.Vector2
stageToLocalCoordinates(Vector2 stageCoords)
Transforms the specified point in the stage's coordinates to the actor's local coordinate system.void
toBack()
Changes the z-order for this actor so it is in back of all siblings.void
toFront()
Changes the z-order for this actor so it is in front of all siblings.java.lang.String
toString()
-
-
-
Method Detail
-
draw
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. IfBatch.end()
is called to draw without the batch thenBatch.begin()
must be called before the method returns.The default implementation does nothing.
- Parameters:
parentAlpha
- The parent alpha, to be multiplied with this actor's alpha, allowing the parent's alpha to affect all children.
-
act
public void act(float delta)
Updates the actor based on time. Typically this is called each frame byStage.act(float)
.The default implementation calls
Action.act(float)
on each action and removes actions that are complete.- Parameters:
delta
- Time in seconds since the last frame.
-
fire
public boolean fire(Event event)
Sets this actor as the eventtarget
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:
- 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.
- The second phase notifies listeners on each actor starting at this actor and, if
Event.getBubbles()
is true, propagating upward to the root.
stopped
at any time, it will not propagate to the next actor.- Returns:
- true if the event was
cancelled
.
-
notify
public boolean notify(Event event, boolean capture)
Notifies this actor's listeners of the event. The event is not propagated to any ascendants. The eventtarget
must be set before calling this method. Before notifying the listeners, this actor is set as thelistener actor
. If this actor is not in the stage, the stage must be set before calling this method.- Parameters:
capture
- If true, the capture listeners will be notified instead of the regular listeners.- Returns:
- true if the event was
cancelled
.
-
hit
@Null public Actor hit(float x, float y, boolean touchable)
Returns the deepestvisible
(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
- If true, hit detection will respect thetouchability
.- See Also:
Touchable
-
remove
public boolean remove()
Removes this actor from its parent, if it has a parent.- See Also:
Group.removeActor(Actor)
-
addListener
public boolean addListener(EventListener listener)
Add a listener to receive events thathit
this actor. Seefire(Event)
.- See Also:
InputListener
,ClickListener
-
removeListener
public boolean removeListener(EventListener listener)
-
getListeners
public DelayedRemovalArray<EventListener> getListeners()
-
addCaptureListener
public boolean addCaptureListener(EventListener listener)
Adds a listener that is only notified during the capture phase.- See Also:
fire(Event)
-
removeCaptureListener
public boolean removeCaptureListener(EventListener listener)
-
getCaptureListeners
public DelayedRemovalArray<EventListener> getCaptureListeners()
-
addAction
public void addAction(Action action)
-
removeAction
public void removeAction(@Null Action action)
- Parameters:
action
- May be null, in which case nothing is done.
-
hasActions
public boolean hasActions()
Returns true if the actor has one or more actions.
-
clearActions
public void clearActions()
Removes all actions on this actor.
-
clearListeners
public void clearListeners()
Removes all listeners on this actor.
-
clear
public void clear()
Removes all actions and listeners on this actor.
-
getStage
@Null public Stage getStage()
Returns the stage that this actor is currently in, or null if not in a stage.
-
setStage
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
- May be null if the actor or any ascendant is no longer in a stage.
-
isDescendantOf
public boolean isDescendantOf(Actor actor)
Returns true if this actor is the same as or is the descendant of the specified actor.
-
isAscendantOf
public boolean isAscendantOf(Actor actor)
Returns true if this actor is the same as or is the ascendant of the specified actor.
-
firstAscendant
@Null public <T extends Actor> T firstAscendant(java.lang.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.
-
hasParent
public boolean hasParent()
Returns true if the actor's parent is not null.
-
setParent
protected void setParent(@Null Group parent)
Called by the framework when an actor is added to or removed from a group.- Parameters:
parent
- May be null if the actor has been removed from the parent.
-
isTouchable
public boolean isTouchable()
Returns true if input events are processed by this actor.
-
getTouchable
public Touchable getTouchable()
-
setTouchable
public void setTouchable(Touchable touchable)
Determines how touch events are distributed to this actor. Default isTouchable.enabled
.
-
isVisible
public boolean isVisible()
-
setVisible
public void setVisible(boolean visible)
If false, the actor will not be drawn and will not receive touch events. Default is true.
-
ascendantsVisible
public boolean ascendantsVisible()
Returns true if this actor and all ascendants are visible.
-
ancestorsVisible
@Deprecated public boolean ancestorsVisible()
Deprecated.UseascendantsVisible()
.
-
hasKeyboardFocus
public boolean hasKeyboardFocus()
Returns true if this actor is thekeyboard focus
actor.
-
hasScrollFocus
public boolean hasScrollFocus()
Returns true if this actor is thescroll focus
actor.
-
isTouchFocusTarget
public boolean isTouchFocusTarget()
Returns true if this actor is a target actor for touch focus.
-
isTouchFocusListener
public boolean isTouchFocusListener()
Returns true if this actor is a listener actor for touch focus.
-
getUserObject
@Null public java.lang.Object getUserObject()
Returns an application specific object for convenience, or null.
-
setUserObject
public void setUserObject(@Null java.lang.Object userObject)
Sets an application specific object for convenience.
-
getX
public float getX()
Returns the X position of the actor's left edge.
-
getX
public float getX(int alignment)
Returns the X position of the specifiedalignment
.
-
setX
public void setX(float x)
-
setX
public void setX(float x, int alignment)
Sets the x position using the specifiedalignment
. Note this may set the position to non-integer coordinates.
-
getY
public float getY()
Returns the Y position of the actor's bottom edge.
-
setY
public void setY(float y)
-
setY
public void setY(float y, int alignment)
Sets the y position using the specifiedalignment
. Note this may set the position to non-integer coordinates.
-
getY
public float getY(int alignment)
Returns the Y position of the specifiedalignment
.
-
setPosition
public void setPosition(float x, float y)
Sets the position of the actor's bottom left corner.
-
setPosition
public void setPosition(float x, float y, int alignment)
Sets the position using the specifiedalignment
. Note this may set the position to non-integer coordinates.
-
moveBy
public void moveBy(float x, float y)
Add x and y to current position
-
getWidth
public float getWidth()
-
setWidth
public void setWidth(float width)
-
getHeight
public float getHeight()
-
setHeight
public void setHeight(float height)
-
getTop
public float getTop()
Returns y plus height.
-
getRight
public float getRight()
Returns x plus width.
-
positionChanged
protected void positionChanged()
Called when the actor's position has been changed.
-
sizeChanged
protected void sizeChanged()
Called when the actor's size has been changed.
-
scaleChanged
protected void scaleChanged()
Called when the actor's scale has been changed.
-
rotationChanged
protected void rotationChanged()
Called when the actor's rotation has been changed.
-
setSize
public void setSize(float width, float height)
Sets the width and height.
-
sizeBy
public void sizeBy(float size)
Adds the specified size to the current size.
-
sizeBy
public void sizeBy(float width, float height)
Adds the specified size to the current size.
-
setBounds
public void setBounds(float x, float y, float width, float height)
Set bounds the x, y, width, and height.
-
getOriginX
public float getOriginX()
-
setOriginX
public void setOriginX(float originX)
-
getOriginY
public float getOriginY()
-
setOriginY
public void setOriginY(float originY)
-
setOrigin
public void setOrigin(float originX, float originY)
Sets the origin position which is relative to the actor's bottom left corner.
-
setOrigin
public void setOrigin(int alignment)
Sets the origin position to the specifiedalignment
.
-
getScaleX
public float getScaleX()
-
setScaleX
public void setScaleX(float scaleX)
-
getScaleY
public float getScaleY()
-
setScaleY
public void setScaleY(float scaleY)
-
setScale
public void setScale(float scaleXY)
Sets the scale for both X and Y
-
setScale
public void setScale(float scaleX, float scaleY)
Sets the scale X and scale Y.
-
scaleBy
public void scaleBy(float scale)
Adds the specified scale to the current scale.
-
scaleBy
public void scaleBy(float scaleX, float scaleY)
Adds the specified scale to the current scale.
-
getRotation
public float getRotation()
-
setRotation
public void setRotation(float degrees)
-
rotateBy
public void rotateBy(float amountInDegrees)
Adds the specified rotation to the current rotation.
-
setColor
public void setColor(Color color)
-
setColor
public void setColor(float r, float g, float b, float a)
-
getColor
public Color getColor()
Returns the color the actor will be tinted when drawn. The returned instance can be modified to change the color.
-
getName
@Null public java.lang.String getName()
- Returns:
- May be null.
- See Also:
setName(String)
-
setName
public void setName(@Null java.lang.String name)
Set the actor's name, which is used for identification convenience and bytoString()
.- Parameters:
name
- May be null.- See Also:
Group.findActor(String)
-
toFront
public void toFront()
Changes the z-order for this actor so it is in front of all siblings.
-
toBack
public void toBack()
Changes the z-order for this actor so it is in back of all siblings.
-
setZIndex
public boolean setZIndex(int index)
Sets the z-index of this actor. The z-index is the index into the parent'schildren
, 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:
- true if the z-index changed.
-
getZIndex
public int getZIndex()
Returns the z-index of this actor, or -1 if the actor is not in a group.- See Also:
setZIndex(int)
-
clipBegin
public boolean clipBegin()
CallsclipBegin(float, float, float, float)
to clip this actor's bounds.
-
clipBegin
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 toclipEnd()
if true is returned.- Returns:
- false if the clipping area is zero and no drawing should occur.
- See Also:
ScissorStack
-
clipEnd
public void clipEnd()
Ends clipping begun byclipBegin(float, float, float, float)
.
-
screenToLocalCoordinates
public Vector2 screenToLocalCoordinates(Vector2 screenCoords)
Transforms the specified point in screen coordinates to the actor's local coordinate system.- See Also:
Stage.screenToStageCoordinates(Vector2)
-
stageToLocalCoordinates
public Vector2 stageToLocalCoordinates(Vector2 stageCoords)
Transforms the specified point in the stage's coordinates to the actor's local coordinate system.
-
parentToLocalCoordinates
public Vector2 parentToLocalCoordinates(Vector2 parentCoords)
Converts the coordinates given in the parent's coordinate system to this actor's coordinate system.
-
localToScreenCoordinates
public Vector2 localToScreenCoordinates(Vector2 localCoords)
Transforms the specified point in the actor's coordinates to be in screen coordinates.- See Also:
Stage.stageToScreenCoordinates(Vector2)
-
localToStageCoordinates
public Vector2 localToStageCoordinates(Vector2 localCoords)
Transforms the specified point in the actor's coordinates to be in the stage's coordinates.
-
localToParentCoordinates
public Vector2 localToParentCoordinates(Vector2 localCoords)
Transforms the specified point in the actor's coordinates to be in the parent's coordinates.
-
localToAscendantCoordinates
public Vector2 localToAscendantCoordinates(@Null Actor ascendant, Vector2 localCoords)
Converts coordinates for this actor to those of an ascendant. The ascendant is not required to be the immediate parent.- Throws:
java.lang.IllegalArgumentException
- if the specified actor is not an ascendant of this actor.
-
localToActorCoordinates
public Vector2 localToActorCoordinates(Actor actor, Vector2 localCoords)
Converts coordinates for this actor to those of another actor, which can be anywhere in the stage.
-
drawDebug
public void drawDebug(ShapeRenderer shapes)
Draws this actor's debug lines ifgetDebug()
is true.
-
drawDebugBounds
protected void drawDebugBounds(ShapeRenderer shapes)
Draws a rectangle for the bounds of this actor ifgetDebug()
is true.
-
setDebug
public void setDebug(boolean enabled)
If true,drawDebug(ShapeRenderer)
will be called for this actor.
-
getDebug
public boolean getDebug()
-
debug
public Actor debug()
CallssetDebug(boolean)
withtrue
.
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
-