Package com.prineside.tdi2.scene2d

Class Stage

java.lang.Object
com.badlogic.gdx.InputAdapter
com.prineside.tdi2.scene2d.Stage
All Implemented Interfaces:
InputProcessor, Disposable
public class Stage extends InputAdapter implements Disposable
A 2D scene graph containing hierarchies of actors. Stage handles the viewport and distributes input events.

setViewport(Viewport) controls the coordinates used within the stage and sets up the camera used to convert between stage coordinates and screen coordinates.

A stage must receive input events so it can distribute them to actors. This is typically done by passing the stage to Gdx.input.setInputProcessor. An InputMultiplexer may be used to handle input events before or after the stage does. If an actor handles an event by returning true from the input method, then the stage's input method will also return true, causing subsequent InputProcessors to not receive the event.

The Stage and its constituents (like Actors and Listeners) are not thread-safe and should only be updated and queried from a single thread (presumably the main render thread). Methods should be reentrant, so you can update Actors and Stages from within callbacks and handlers.

Author:
mzechner, Nathan Sweet

  • Constructor Details

    • Stage

      public Stage(Viewport viewport)
      Creates a stage with the specified viewport. The stage will use its own Batch which will be disposed when the stage is disposed.

    • Stage

      public Stage(Viewport viewport, Batch batch)
      Creates a stage with the specified viewport and batch. This can be used to specify an existing batch or to customize which batch implementation is used.
      Parameters:
      batch - Will not be disposed if dispose() is called, handle disposal yourself.

  • Method Details

    • draw

      public void draw()

    • act

      public void act()
      Calls act(float) with Graphics.getDeltaTime(), limited to a minimum of 30fps.

    • act

      public void act(float delta)
      Calls the Actor.act(float) method on each actor in the stage. Typically called each frame. This method also fires enter and exit events.
      Parameters:
      delta - Time in seconds since the last frame.

    • touchDown

      public boolean touchDown(int screenX, int screenY, int pointer, int button)
      Applies a touch down event to the stage and returns true if an actor in the scene handled the event.
      Specified by:
      touchDown in interface InputProcessor
      Overrides:
      touchDown in class InputAdapter
      Parameters:
      screenX - The x coordinate, origin is in the upper left corner
      screenY - The y coordinate, origin is in the upper left corner
      pointer - the pointer for the event.
      button - the button
      Returns:
      whether the input was processed

    • touchDragged

      public boolean touchDragged(int screenX, int screenY, int pointer)
      Applies a touch moved event to the stage and returns true if an actor in the scene handled the event. Only listeners that returned true for touchDown will receive this event.
      Specified by:
      touchDragged in interface InputProcessor
      Overrides:
      touchDragged in class InputAdapter
      pointer - the pointer for the event.
      Returns:
      whether the input was processed

    • touchUp

      public boolean touchUp(int screenX, int screenY, int pointer, int button)
      Applies a touch up event to the stage and returns true if an actor in the scene handled the event. Only listeners that returned true for touchDown will receive this event.
      Specified by:
      touchUp in interface InputProcessor
      Overrides:
      touchUp in class InputAdapter
      pointer - the pointer for the event.
      button - the button
      Returns:
      whether the input was processed

    • touchCancelled

      public boolean touchCancelled(int screenX, int screenY, int pointer, int button)
      Description copied from interface: com.badlogic.gdx.InputProcessor
      Called when the touch gesture is cancelled. Reason may be from OS interruption to touch becoming a large surface such as the user cheek). Relevant on Android and iOS only. The button parameter will be Input.Buttons.LEFT on iOS.
      Specified by:
      touchCancelled in interface InputProcessor
      Overrides:
      touchCancelled in class InputAdapter
      pointer - the pointer for the event.
      button - the button
      Returns:
      whether the input was processed

    • mouseMoved

      public boolean mouseMoved(int screenX, int screenY)
      Applies a mouse moved event to the stage and returns true if an actor in the scene handled the event. This event only occurs on the desktop.
      Specified by:
      mouseMoved in interface InputProcessor
      Overrides:
      mouseMoved in class InputAdapter
      Returns:
      whether the input was processed

    • scrolled

      public boolean scrolled(float amountX, float amountY)
      Applies a mouse scroll event to the stage and returns true if an actor in the scene handled the event. This event only occurs on the desktop.
      Specified by:
      scrolled in interface InputProcessor
      Overrides:
      scrolled in class InputAdapter
      Parameters:
      amountX - the horizontal scroll amount, negative or positive depending on the direction the wheel was scrolled.
      amountY - the vertical scroll amount, negative or positive depending on the direction the wheel was scrolled.
      Returns:
      whether the input was processed.

    • keyDown

      public boolean keyDown(int keyCode)
      Applies a key down event to the actor that has keyboard focus, if any, and returns true if the event was handled.
      Specified by:
      keyDown in interface InputProcessor
      Overrides:
      keyDown in class InputAdapter
      Parameters:
      keyCode - one of the constants in Input.Keys
      Returns:
      whether the input was processed

    • keyUp

      public boolean keyUp(int keyCode)
      Applies a key up event to the actor that has keyboard focus, if any, and returns true if the event was handled.
      Specified by:
      keyUp in interface InputProcessor
      Overrides:
      keyUp in class InputAdapter
      Parameters:
      keyCode - one of the constants in Input.Keys
      Returns:
      whether the input was processed

    • keyTyped

      public boolean keyTyped(char character)
      Applies a key typed event to the actor that has keyboard focus, if any, and returns true if the event was handled.
      Specified by:
      keyTyped in interface InputProcessor
      Overrides:
      keyTyped in class InputAdapter
      Parameters:
      character - The character
      Returns:
      whether the input was processed

    • addTouchFocus

      public void addTouchFocus(EventListener listener, Actor listenerActor, Actor target, int pointer, int button)
      Adds the listener to be notified for all touchDragged and touchUp events for the specified pointer and button. Touch focus is added automatically when true is returned from touchDown. The specified actors will be used as the listener actor and target for the touchDragged and touchUp events.

    • removeTouchFocus

      public void removeTouchFocus(EventListener listener, Actor listenerActor, Actor target, int pointer, int button)
      Removes touch focus for the specified listener, pointer, and button. Note the listener will not receive a touchUp event when this method is used.

    • cancelTouchFocus

      public void cancelTouchFocus(Actor listenerActor)
      Cancels touch focus for all listeners with the specified listener actor.
      See Also:

    • cancelTouchFocus

      public void cancelTouchFocus()
      Removes all touch focus listeners, sending a touchUp event to each listener. Listeners typically expect to receive a touchUp event when they have touch focus. The location of the touchUp is Integer.MIN_VALUE. Listeners can use InputEvent.isTouchFocusCancel() to ignore this event if needed.

    • cancelTouchFocusExcept

      public void cancelTouchFocusExcept(@Null EventListener exceptListener, @Null Actor exceptActor)
      Cancels touch focus for all listeners except the specified listener.
      See Also:

    • addActor

      public void addActor(Actor actor)
      Adds an actor to the root of the stage.
      See Also:

    • addAction

      public void addAction(Action action)
      Adds an action to the root of the stage.
      See Also:

    • getActors

      public Array<Actor> getActors()
      Returns the root's child actors.
      See Also:

    • addListener

      public boolean addListener(EventListener listener)
      Adds a listener to the root.
      See Also:

    • removeListener

      public boolean removeListener(EventListener listener)
      Removes a listener from the root.
      See Also:

    • addCaptureListener

      public boolean addCaptureListener(EventListener listener)
      Adds a capture listener to the root.
      See Also:

    • removeCaptureListener

      public boolean removeCaptureListener(EventListener listener)
      Removes a listener from the root.
      See Also:

    • clear

      public void clear()
      Removes the root's children, actions, and listeners.

    • unfocusAll

      public void unfocusAll()
      Removes the touch, keyboard, and scroll focused actors.

    • unfocus

      public void unfocus(Actor actor)
      Removes the touch, keyboard, and scroll focus for the specified actor and any descendants.

    • setKeyboardFocus

      public boolean setKeyboardFocus(@Null Actor actor)
      Sets the actor that will receive key events.
      Parameters:
      actor - May be null.
      Returns:
      true if the unfocus and focus events were not cancelled by a FocusListener.

    • getKeyboardFocus

      @Null public Actor getKeyboardFocus()
      Gets the actor that will receive key events.
      Returns:
      May be null.

    • setScrollFocus

      public boolean setScrollFocus(@Null Actor actor)
      Sets the actor that will receive scroll events.
      Parameters:
      actor - May be null.
      Returns:
      true if the unfocus and focus events were not cancelled by a FocusListener.

    • getScrollFocus

      @Null public Actor getScrollFocus()
      Gets the actor that will receive scroll events.
      Returns:
      May be null.

    • getBatch

      public Batch getBatch()

    • getViewport

      public Viewport getViewport()

    • setViewport

      public void setViewport(Viewport viewport)

    • getWidth

      public float getWidth()
      The viewport's world width.

    • getHeight

      public float getHeight()
      The viewport's world height.

    • getCamera

      public Camera getCamera()
      The viewport's camera.

    • getRoot

      public Group getRoot()
      Returns the root group which holds all actors in the stage.

    • setRoot

      public void setRoot(Group root)
      Replaces the root group. This can be useful, for example, to subclass the root group to be notified by Group.childrenChanged().

    • hit

      @Null public Actor hit(float stageX, float stageY, boolean touchable)
      Returns the Actor at the specified location in stage coordinates. Hit testing is performed in the order the actors were inserted into the stage, last inserted actors being tested first. To get stage coordinates from screen coordinates, use screenToStageCoordinates(Vector2).
      Parameters:
      touchable - If true, the hit detection will respect the touchability.
      Returns:
      May be null if no actor was hit.

    • screenToStageCoordinates

      public Vector2 screenToStageCoordinates(Vector2 screenCoords)
      Transforms the screen coordinates to stage coordinates.
      Parameters:
      screenCoords - Input screen coordinates and output for resulting stage coordinates.

    • stageToScreenCoordinates

      public Vector2 stageToScreenCoordinates(Vector2 stageCoords)
      Transforms the stage coordinates to screen coordinates.
      Parameters:
      stageCoords - Input stage coordinates and output for resulting screen coordinates.

    • toScreenCoordinates

      public Vector2 toScreenCoordinates(Vector2 coords, Matrix4 transformMatrix)
      Transforms the coordinates to screen coordinates. The coordinates can be anywhere in the stage since the transform matrix describes how to convert them. The transform matrix is typically obtained from Batch.getTransformMatrix() during Actor.draw(Batch, float).
      See Also:

    • calculateScissors

      public void calculateScissors(Rectangle localRect, Rectangle scissorRect)
      Calculates window scissor coordinates from local coordinates using the batch's current transformation matrix.
      See Also:

    • setActionsRequestRendering

      public void setActionsRequestRendering(boolean actionsRequestRendering)
      If true, any actions executed during a call to act()) will result in a call to Graphics.requestRendering(). Widgets that animate or otherwise require additional rendering may check this setting before calling Graphics.requestRendering(). Default is true.

    • getActionsRequestRendering

      public boolean getActionsRequestRendering()

    • getDebugColor

      public Color getDebugColor()
      The default color that can be used by actors to draw debug lines.

    • setDebugInvisible

      public void setDebugInvisible(boolean debugInvisible)
      If true, debug lines are shown for actors even when Actor.isVisible() is false.

    • setDebugAll

      public void setDebugAll(boolean debugAll)
      If true, debug lines are shown for all actors.

    • isDebugAll

      public boolean isDebugAll()

    • setDebugUnderMouse

      public void setDebugUnderMouse(boolean debugUnderMouse)
      If true, debug is enabled only for the actor under the mouse. Can be combined with setDebugAll(boolean).

    • setDebugParentUnderMouse

      public void setDebugParentUnderMouse(boolean debugParentUnderMouse)
      If true, debug is enabled only for the parent of the actor under the mouse. Can be combined with setDebugAll(boolean).

    • setDebugTableUnderMouse

      public void setDebugTableUnderMouse(@Null Table.Debug debugTableUnderMouse)
      If not Table.Debug.none, debug is enabled only for the first ascendant of the actor under the mouse that is a table. Can be combined with setDebugAll(boolean).
      Parameters:
      debugTableUnderMouse - May be null for Table.Debug.none.

    • setDebugTableUnderMouse

      public void setDebugTableUnderMouse(boolean debugTableUnderMouse)
      If true, debug is enabled only for the first ascendant of the actor under the mouse that is a table. Can be combined with setDebugAll(boolean).

    • dispose

      public void dispose()
      Description copied from interface: com.badlogic.gdx.utils.Disposable
      Releases all resources of this object.
      Specified by:
      dispose in interface Disposable