libgdx API

com.badlogic.gdx.scenes.scene2d
Class Actor

java.lang.Object
  extended by com.badlogic.gdx.scenes.scene2d.Actor
Direct Known Subclasses:
Group, Widget

public class Actor
extends java.lang.Object

2D scene graph node. An actor has a position, rectangular size, origin, scale, rotation, 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 also has a list of actions that can manipulate the actor over time, and a list of listeners that are notified of events the actor receives.

Author:
mzechner, Nathan Sweet

Constructor Summary
Actor()
           
 
Method Summary
 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)
           
 void clearActions()
          Removes all actions on this actor.
 boolean clipBegin()
          Calls clipBegin(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 SpriteBatch.
 void clipEnd()
          Ends clipping begun by clipBegin(float, float, float, float).
 void draw(SpriteBatch batch, float parentAlpha)
          Draws the actor.
 boolean fire(Event event)
          Sets this actor as the event target and propagates the event to this actor and ancestor actors as necessary.
 Array<Action> getActions()
           
 Array<EventListener> getCaptureListeners()
           
 Color getColor()
          Returns the color the actor will be tinted when drawn.
 float getHeight()
           
 Array<EventListener> getListeners()
           
 java.lang.String getName()
           
 float getOriginX()
           
 float getOriginY()
           
 Group getParent()
          Returns the parent actor, or null if not in a stage.
 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()
           
 float getWidth()
           
 float getX()
           
 float getY()
           
 int getZIndex()
          Returns the z-index of this actor.
 boolean hasParent()
          Returns true if the actor's parent is not null.
 Actor hit(float x, float y, boolean touchable)
          Returns the deepest actor that contains the specified point and is touchable and visible, or null if no actor was hit.
 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 isVisible()
           
 Vector2 localToAscendantCoordinates(Actor ascendant, Vector2 localCoords)
          Converts coordinates for this actor to those of a parent actor.
 Vector2 localToParentCoordinates(Vector2 localCoords)
          Transforms the specified point in the actor's coordinates to be in the parent's coordinates.
 Vector2 localToStageCoordinates(Vector2 localCoords)
          Transforms the specified point in the actor's coordinates to be in the stage's coordinates.
 boolean 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.
 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 rotate(float amountInDegrees)
          Adds the specified rotation to the current rotation.
 void scale(float scale)
          Adds the specified scale to the current scale.
 void scale(float scaleX, float scaleY)
          Adds the specified scale to the current scale.
 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(Color color)
           
 void setColor(float r, float g, float b, float a)
           
 void setHeight(float height)
           
 void setName(java.lang.String name)
          Sets a name for easier identification of the actor in application code.
 void setOrigin(float originX, float originY)
          Sets the originx and originy.
 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 x and y.
 void setRotation(float degrees)
           
 void setScale(float scale)
          Sets the scalex and scaley.
 void setScale(float scaleX, float scaleY)
          Sets the scalex and scaley.
 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 parent is added to a group that is in the stage.
 void setTouchable(Touchable touchable)
          Determines how touch events are distributed to this actor.
 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 setY(float y)
           
 void setZIndex(int index)
          Sets the z-index of this actor.
 void size(float size)
          Adds the specified size to the current size.
 void size(float width, float height)
          Adds the specified size to the current size.
 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()
           
 void translate(float x, float y)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Actor

public Actor()
Method Detail

draw

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

The default implementation does nothing.

Parameters:
parentAlpha - Should be multipied with the actor's alpha, allowing a 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 by Stage.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 event target and propagates the event to this actor and ancestor actors 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 notifies listeners on each actor starting at the root and propagating downward to (and including) this actor. The second phase notifes 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:
true of 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 parents. Before notifying the listeners, this actor is set as the listener actor. The event target must be set before calling this method. 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 of the event was cancelled.

hit

public Actor hit(float x,
                 float y,
                 boolean touchable)
Returns the deepest actor that contains the specified point and is touchable and visible, 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 events. If this method returns null, touchDown will not occur.

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

Parameters:
touchable - If true, the hit detection will respect the touchability.
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)
See Also:
InputListener, ClickListener

removeListener

public boolean removeListener(EventListener listener)

getListeners

public Array<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 Array<EventListener> getCaptureListeners()

addAction

public void addAction(Action action)

removeAction

public void removeAction(Action action)

getActions

public Array<Action> getActions()

clearActions

public void clearActions()
Removes all actions on this actor.


getStage

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 parent is added to a group that is in the stage.

Parameters:
stage - May be null if the actor or any parent 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.


hasParent

public boolean hasParent()
Returns true if the actor's parent is not null.


getParent

public Group getParent()
Returns the parent actor, or null if not in a stage.


setParent

protected void setParent(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.

getTouchable

public Touchable getTouchable()

setTouchable

public void setTouchable(Touchable touchable)
Determines how touch events are distributed to this actor. Default is Touchable.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.


getX

public float getX()

setX

public void setX(float x)

getY

public float getY()

setY

public void setY(float y)

setPosition

public void setPosition(float x,
                        float y)
Sets the x and y.


translate

public void translate(float x,
                      float y)

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.


setSize

public void setSize(float width,
                    float height)
Sets the width and height.


size

public void size(float size)
Adds the specified size to the current size.


size

public void size(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 originx and originy.


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 scale)
Sets the scalex and scaley.


setScale

public void setScale(float scaleX,
                     float scaleY)
Sets the scalex and scaley.


scale

public void scale(float scale)
Adds the specified scale to the current scale.


scale

public void scale(float scaleX,
                  float scaleY)
Adds the specified scale to the current scale.


getRotation

public float getRotation()

setRotation

public void setRotation(float degrees)

rotate

public void rotate(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

public java.lang.String getName()

setName

public void setName(java.lang.String name)
Sets a name for easier identification of the actor in application code.

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 void 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.


getZIndex

public int getZIndex()
Returns the z-index of this actor.

See Also:
setZIndex(int)

clipBegin

public boolean clipBegin()
Calls clipBegin(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 SpriteBatch. 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:
false if the clipping area is zero and no drawing should occur.
See Also:
ScissorStack

clipEnd

public void clipEnd()
Ends clipping begun by clipBegin(float, float, float, float).


screenToLocalCoordinates

public Vector2 screenToLocalCoordinates(Vector2 screenCoords)
Transforms the specified point in screen coordinates to the actor's local coordinate system.


stageToLocalCoordinates

public Vector2 stageToLocalCoordinates(Vector2 stageCoords)
Transforms the specified point in the stage's coordinates to the actor's local coordinate system.


localToStageCoordinates

public Vector2 localToStageCoordinates(Vector2 localCoords)
Transforms the specified point in the actor's coordinates to be in the stage's coordinates. Note this method will ONLY work for screen aligned, unrotated, unscaled actors!


localToParentCoordinates

public Vector2 localToParentCoordinates(Vector2 localCoords)
Transforms the specified point in the actor's coordinates to be in the parent's coordinates. Note this method will ONLY work for screen aligned, unrotated, unscaled actors!


localToAscendantCoordinates

public Vector2 localToAscendantCoordinates(Actor ascendant,
                                           Vector2 localCoords)
Converts coordinates for this actor to those of a parent actor. The ascendant does not need to be a direct parent.


parentToLocalCoordinates

public Vector2 parentToLocalCoordinates(Vector2 parentCoords)
Converts the coordinates given in the parent's coordinate system to this actor's coordinate system.


toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

libgdx API

Copyright 2010 Mario Zechner (contact@badlogicgames.com), Nathan Sweet (admin@esotericsoftware.com)