Class 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). 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(com.badlogic.gdx.scenes.scene2d.Event) 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.

    • Constructor Detail

      • Actor

        public Actor()
    • 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. 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 - 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 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 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:
        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 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 - 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 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 - If true, 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)
      • removeListener

        public boolean removeListener​(EventListener listener)
      • 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)
      • 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.
      • getParent

        @Null
        public Group getParent()
        Returns the parent actor, or null if not in a group.
      • 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 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.
      • ascendantsVisible

        public boolean ascendantsVisible()
        Returns true if this actor and all ascendants are visible.
      • ancestorsVisible

        @Deprecated
        public boolean ancestorsVisible()
        Deprecated.
      • hasKeyboardFocus

        public boolean hasKeyboardFocus()
        Returns true if this actor is the keyboard focus actor.
      • hasScrollFocus

        public boolean hasScrollFocus()
        Returns true if this actor is the scroll focus actor.
      • 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 specified alignment.
      • setX

        public void setX​(float x)
      • setX

        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.
      • 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 specified alignment. Note this may set the position to non-integer coordinates.
      • getY

        public float getY​(int alignment)
        Returns the Y position of the specified alignment.
      • 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 specified alignment. 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 specified alignment.
      • 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.
      • setName

        public void setName​(@Null
                            java.lang.String name)
        Set the actor's name, which is used for identification convenience and by toString().
        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'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:
        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​(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:
        false if the clipping area is zero and no drawing should occur.
        See Also:
        ScissorStack
      • 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.
      • 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 if getDebug() is true.
      • drawDebugBounds

        protected void drawDebugBounds​(ShapeRenderer shapes)
        Draws a rectangle for the bounds of this actor if getDebug() is true.
      • getDebug

        public boolean getDebug()
      • toString

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