com.badlogic.gdx.scenes.scene2d
Class Actor

java.lang.Object
  com.badlogic.gdx.scenes.scene2d.Actor

Direct Known Subclasses:

Group, Widget

public class Actor
extends 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 (over time). These are generally used to change the presentation of the actor (moving it, resizing it, etc). See act(float) and Action.

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 capture listeners are designed to allow a parent or container actor to hide events from child actors. The regular listeners are designed to allow an actor to respond to events that have been delivered. See fire(com.badlogic.gdx.scenes.scene2d.Event) for more details.

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

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) Add a listener to receive events that hit this actor.
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() 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()
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(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)
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.
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.
String	toString()
void	translate(float x, float y)

Methods inherited from class java.lang.Object

equals, 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 multiplied 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.

1. The first phase (the "capture" phase) notifies listeners on each actor starting at the root and propagating downward 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:

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

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)

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

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.

clearListeners

public void clearListeners()

Removes all listeners on this actor.

clear

public void clear()

Removes all actions and listeners on this actor.

getStage

public Stage getStage()

Returns the stage that this actor is currently in, or null if not 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.

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 String getName()

setName

public void setName(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.

See Also:

Stage.toScreenCoordinates(Vector2, com.badlogic.gdx.math.Matrix4)

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(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 String toString()

Overrides:

toString in class Object