libgdx API

com.badlogic.gdx.scenes.scene2d
Class Stage

java.lang.Object
  extended by com.badlogic.gdx.InputAdapter
      extended by com.badlogic.gdx.scenes.scene2d.Stage
All Implemented Interfaces:
InputProcessor, Disposable

public class Stage
extends InputAdapter
implements Disposable

A 2D scenegraph containing hierarchies of actors. Stage handles the viewport and distributing input events.

A stage fills the whole screen. setViewport(float, float, boolean) 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.

Author:
mzechner, Nathan Sweet

Nested Class Summary
static class Stage.TouchFocus
          Internal class for managing touch focus.
 
Constructor Summary
Stage()
          Creates a stage with a viewport equal to the device screen resolution.
Stage(float width, float height, boolean keepAspectRatio)
          Creates a stage with the specified viewport.
Stage(float width, float height, boolean keepAspectRatio, SpriteBatch batch)
          Creates a stage with the specified viewport and SpriteBatch.
 
Method Summary
 void act()
          Calls act(float) with Graphics.getDeltaTime().
 void act(float delta)
          Calls the Actor.act(float) method on each actor in the stage.
 void addAction(Action action)
          Adds an action to the root of the stage.
 void addActor(Actor actor)
          Adds an actor to the root of the stage.
 boolean addCaptureListener(EventListener listener)
          Adds a capture listener to the root.
 boolean addListener(EventListener listener)
          Adds a listener to the root.
 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.
 void cancelTouchFocus()
          Sends a touchUp event to all listeners that are registered to receive touchDragged and touchUp events and removes their touch focus.
 void cancelTouchFocus(EventListener listener, Actor actor)
          Cancels touch focus for all listeners except the specified listener.
 void clear()
          Clears the stage, removing all actors.
 void dispose()
          Releases all resources of this object.
 void draw()
           
 Array<Actor> getActors()
          Returns the root's child actors.
 Camera getCamera()
           
 float getGutterHeight()
          Half the amount in the y direction that the stage's viewport was lengthened to fill the screen.
 float getGutterWidth()
          Half the amount in the x direction that the stage's viewport was lengthened to fill the screen.
 float getHeight()
          The height of the stage's viewport.
 Actor getKeyboardFocus()
          Gets the actor that will receive key events.
 Group getRoot()
          Returns the root group which holds all actors in the stage.
 Actor getScrollFocus()
          Gets the actor that will receive scroll events.
 SpriteBatch getSpriteBatch()
           
 float getWidth()
          The width of the stage's viewport.
 Actor hit(float stageX, float stageY, boolean touchable)
          Returns the Actor at the specified location in stage coordinates.
 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.
 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.
 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.
 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.
 boolean removeCaptureListener(EventListener listener)
          Removes a listener from the root.
 boolean removeListener(EventListener listener)
          Removes a listener from the root.
 void removeTouchFocus(EventListener listener, Actor listenerActor, Actor target, int pointer, int button)
          Removes the listener from being notified for all touchDragged and touchUp events for the specified pointer and button.
 Vector2 screenToStageCoordinates(Vector2 screenCoords)
          Transforms the screen coordinates to stage coordinates.
 boolean scrolled(int amount)
          Applies a mouse scroll event to the stage and returns true if an actor in the scene handled the event.
 void setCamera(Camera camera)
          Sets the stage's camera.
 void setKeyboardFocus(Actor actor)
          Sets the actor that will receive key events.
 void setScrollFocus(Actor actor)
          Sets the actor that will receive scroll events.
 void setViewport(float width, float height, boolean keepAspectRatio)
          Sets the dimensions of the stage's viewport.
 Vector2 stageToScreenCoordinates(Vector2 stageCoords)
          Transforms the stage coordinates to screen coordinates.
 Vector2 toScreenCoordinates(Vector2 coords, Matrix4 transformMatrix)
          Transforms the coordinates to screen coordinates.
 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.
 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.
 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.
 void unfocus(Actor actor)
          Removes the touch, keyboard, and scroll focus for the specified actor and any descendants.
 void unfocusAll()
          Removes the touch, keyboard, and scroll focused actors.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Stage

public Stage()
Creates a stage with a viewport equal to the device screen resolution. The stage will use its own SpriteBatch.


Stage

public Stage(float width,
             float height,
             boolean keepAspectRatio)
Creates a stage with the specified viewport. The stage will use its own SpriteBatch, which will be disposed when the stage is disposed.


Stage

public Stage(float width,
             float height,
             boolean keepAspectRatio,
             SpriteBatch batch)
Creates a stage with the specified viewport and SpriteBatch. This can be used to avoid creating a new SpriteBatch (which can be somewhat slow) if multiple stages are used during an applications life time.

Parameters:
batch - Will not be disposed if dispose() is called. Handle disposal yourself.
Method Detail

setViewport

public void setViewport(float width,
                        float height,
                        boolean keepAspectRatio)
Sets the dimensions of the stage's viewport. The viewport covers the entire screen. If keepAspectRatio is false, the viewport is simply stretched to the screen resolution, which may distort the aspect ratio. If keepAspectRatio is true, the viewport is first scaled to fit then the shorter dimension is lengthened to fill the screen, which keeps the aspect ratio from changing. The getGutterWidth() and getGutterHeight() provide access to the amount that was lengthened.


draw

public void draw()

act

public void act()
Calls act(float) with Graphics.getDeltaTime().


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

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(int amount)
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:
amount - the scroll amount, -1 or 1 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. The actor will be used as the listener actor and target.


removeTouchFocus

public void removeTouchFocus(EventListener listener,
                             Actor listenerActor,
                             Actor target,
                             int pointer,
                             int button)
Removes the listener from being notified for all touchDragged and touchUp events for the specified pointer and button. Note the listener may never receive a touchUp event if this method is used.


cancelTouchFocus

public void cancelTouchFocus()
Sends a touchUp event to all listeners that are registered to receive touchDragged and touchUp events and removes their touch focus. The location of the touchUp is Integer.MIN_VALUE. This method removes all touch focus listeners, but sends a touchUp event so that the state of the listeners remains consistent (listeners typically expect to receive touchUp eventually).


cancelTouchFocus

public void cancelTouchFocus(EventListener listener,
                             Actor actor)
Cancels touch focus for all listeners except the specified listener.

See Also:
cancelTouchFocus()

addActor

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

See Also:
Group.addActor(Actor), Actor.remove()

addAction

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

See Also:
Actor.addAction(Action)

getActors

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

See Also:
Group.getChildren()

addListener

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

See Also:
Actor.addListener(EventListener)

removeListener

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

See Also:
Actor.removeListener(EventListener)

addCaptureListener

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

See Also:
Actor.addCaptureListener(EventListener)

removeCaptureListener

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

See Also:
Actor.removeCaptureListener(EventListener)

clear

public void clear()
Clears the stage, removing all actors.


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 void setKeyboardFocus(Actor actor)
Sets the actor that will receive key events.

Parameters:
actor - May be null.

getKeyboardFocus

public Actor getKeyboardFocus()
Gets the actor that will receive key events.

Returns:
May be null.

setScrollFocus

public void setScrollFocus(Actor actor)
Sets the actor that will receive scroll events.

Parameters:
actor - May be null.

getScrollFocus

public Actor getScrollFocus()
Gets the actor that will receive scroll events.

Returns:
May be null.

getWidth

public float getWidth()
The width of the stage's viewport.

See Also:
setViewport(float, float, boolean)

getHeight

public float getHeight()
The height of the stage's viewport.

See Also:
setViewport(float, float, boolean)

getGutterWidth

public float getGutterWidth()
Half the amount in the x direction that the stage's viewport was lengthened to fill the screen.

See Also:
setViewport(float, float, boolean)

getGutterHeight

public float getGutterHeight()
Half the amount in the y direction that the stage's viewport was lengthened to fill the screen.

See Also:
setViewport(float, float, boolean)

getSpriteBatch

public SpriteBatch getSpriteBatch()

getCamera

public Camera getCamera()

setCamera

public void setCamera(Camera camera)
Sets the stage's camera. The camera must be configured properly or setViewport(float, float, boolean) can be called after the camera is set. draw() will call Camera.update() and use the Camera.combined matrix for the SpriteBatch projection matrix.


getRoot

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


hit

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 - Stores the result.

stageToScreenCoordinates

public Vector2 stageToScreenCoordinates(Vector2 stageCoords)
Transforms the stage coordinates to 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 SpriteBatch.getTransformMatrix().


dispose

public void dispose()
Description copied from interface: Disposable
Releases all resources of this object.

Specified by:
dispose in interface Disposable

libgdx API

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