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 stage is a container for Actors and handles distributing touch events, animating actors and asking them to render themselves. A stage is 2D scenegraph with hierarchies of Actors.

A stage fills the whole screen. It has a width and height given in device independent pixels. It has a Camera that maps this viewport to the given real screen resolution. If the stretched attribute is set to true then the viewport is enforced no matter the difference in aspect ratio between the stage object and the screen dimensions. In case stretch is disabled then the viewport is extended in the bigger screen dimensions.

Actors have a z-order which is equal to the order they were inserted into the stage. Actors inserted later will be drawn on top of actors added earlier. Touch events that will get distributed to later actors first.

Actors can be focused. When your game pauses and resumes be sure to call the unfocusAll() method so that the focus states get reset for each pointer id. You also have to make sure that the actors that were focused reset their state if the depend on being focused, e.g. wait for a touch up event. An easier way to tackle this is to recreate the stage if possible.

Author:
mzechner

Field Summary
protected  SpriteBatch batch
           
protected  Camera camera
           
protected  float centerX
           
protected  float centerY
           
protected  float height
           
protected  boolean ownsBatch
           
protected  Group root
           
protected  boolean stretch
           
protected  float width
           
 
Constructor Summary
Stage(float width, float height, boolean stretch)
          Constructs a new Stage object with the given dimensions.
Stage(float width, float height, boolean stretch, SpriteBatch batch)
          Constructs a new Stage object with the given dimensions.
 
Method Summary
 void act(float delta)
          Calls the Actor.act(float) method of all contained Actors.
 void addActor(Actor actor)
          Adds an Actor to this stage
 float bottom()
           
 float centerX()
           
 float centerY()
           
 void clear()
          Clears this stage, removing all Actors and Groups.
 void dispose()
          Disposes the stage
 void draw()
          Renders the stage
 Actor findActor(java.lang.String name)
          Finds the Actor with the given name in the stage hierarchy.
 java.util.List<Actor> getActors()
           
 Camera getCamera()
           
 java.util.List<Group> getGroups()
           
 Actor getKeyboardFocus()
           
 Actor getLastTouchedChild()
           
 Group getRoot()
           
 Actor getScrollFocus()
           
 SpriteBatch getSpriteBatch()
           
 Actor getTouchFocus(int pointer)
           
 java.lang.String graphToString()
           
 float height()
           
 Actor hit(float x, float y)
          Returns the Actor intersecting with the point (x,y) in stage coordinates.
 boolean isStretched()
           
 boolean keyDown(int keycode)
          Called when a key was pressed
 boolean keyTyped(char character)
          Called when a key was typed
 boolean keyUp(int keycode)
          Called when a key was released
 int left()
           
 void removeActor(Actor actor)
          Removes the given Actor from the stage by trying to find it recursively in the scenegraph.
 float right()
           
 boolean scrolled(int amount)
          Call this to distribute a mouse scroll event to the stage.
 void setCamera(Camera camera)
          Sets the Camera this stage uses.
 void setKeyboardFocus(Actor actor)
           
 void setScrollFocus(Actor actor)
           
 void setTouchFocus(Actor actor, int pointer)
           
 void setViewport(float width, float height, boolean stretch)
          Sets the viewport dimensions in device independent pixels.
 float top()
           
 void toStageCoordinates(int x, int y, Vector2 out)
          Transforms the given screen coordinates to stage coordinates
 boolean touchDown(int x, int y, int pointer, int button)
          Call this to distribute a touch down event to the stage.
 boolean touchDragged(int x, int y, int pointer)
          Call this to distribute a touch dragged event to the stage.
 boolean touchMoved(int x, int y)
          Call this to distribute a touch moved event to the stage.
 boolean touchUp(int x, int y, int pointer, int button)
          Call this to distribute a touch Up event to the stage.
 void unfocus(Actor actor)
           
 void unfocus(Actor actor, int pointer)
           
 void unfocusAll()
           
 float width()
          8
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

width

protected float width

height

protected float height

centerX

protected float centerX

centerY

protected float centerY

stretch

protected boolean stretch

root

protected final Group root

ownsBatch

protected final boolean ownsBatch

batch

protected final SpriteBatch batch

camera

protected Camera camera
Constructor Detail

Stage

public Stage(float width,
             float height,
             boolean stretch)
Constructs a new Stage object with the given dimensions. If the device resolution does not equal the Stage objects dimensions the stage object will setup a projection matrix to guarantee a fixed coordinate system. If stretch is disabled then the bigger dimension of the Stage will be increased to accomodate the actual device resolution.

Parameters:
width - the width of the viewport
height - the height of the viewport
stretch - whether to stretch the viewport to the real device resolution

Stage

public Stage(float width,
             float height,
             boolean stretch,
             SpriteBatch batch)
Constructs a new Stage object with the given dimensions. If the device resolution does not equal the Stage objects dimensions the stage object will setup a projection matrix to guarantee a fixed coordinate system. If stretch is disabled then the bigger dimension of the Stage will be increased to accomodate the actual device resolution.

Parameters:
width - the width of the viewport
height - the height of the viewport
stretch - whether to stretch the viewport to the real device resolution
batch - the SpriteBatch this Stage should use. Will not be disposed if dispose() is called.
Method Detail

setViewport

public void setViewport(float width,
                        float height,
                        boolean stretch)
Sets the viewport dimensions in device independent pixels. If stretch is false and the viewport aspect ratio is not equal to the device ratio then the bigger dimension of the viewport will be extended (device independent pixels stay quardatic instead of getting stretched).

Parameters:
width - thew width of the viewport in device independent pixels
height - the height of the viewport in device independent pixels
stretch - whether to stretch the viewport or not

width

public float width()
8

Returns:
the width of the stage in dips

height

public float height()
Returns:
the height of the stage in dips

left

public int left()
Returns:
the x-coordinate of the left edge of the stage in dips

right

public float right()
Returns:
the x-coordinate of the right edge of the stage in dips

top

public float top()
Returns:
the y-coordinate of the top edge of the stage in dips

bottom

public float bottom()
Returns:
the y-coordinate of the bottom edge of the stage in dips

centerX

public float centerX()
Returns:
the center x-coordinate of the stage in dips

centerY

public float centerY()
Returns:
the center y-coordinate of the stage in dips

isStretched

public boolean isStretched()
Returns:
whether the stage is stretched

findActor

public Actor findActor(java.lang.String name)
Finds the Actor with the given name in the stage hierarchy.

Parameters:
name -
Returns:
the Actor or null if it couldn't be found.

getActors

public java.util.List<Actor> getActors()
Returns:
all top level Actors

getGroups

public java.util.List<Group> getGroups()
Returns:
all top level Groups

touchDown

public boolean touchDown(int x,
                         int y,
                         int pointer,
                         int button)
Call this to distribute a touch down event to the stage.

Specified by:
touchDown in interface InputProcessor
Overrides:
touchDown in class InputAdapter
Parameters:
x - the x coordinate of the touch in screen coordinates
y - the y coordinate of the touch in screen coordinates
pointer - the pointer index
button - the button that's been pressed
Returns:
whether an Actor in the scene processed the event or not

touchUp

public boolean touchUp(int x,
                       int y,
                       int pointer,
                       int button)
Call this to distribute a touch Up event to the stage.

Specified by:
touchUp in interface InputProcessor
Overrides:
touchUp in class InputAdapter
Parameters:
x - the x coordinate of the touch in screen coordinates
y - the y coordinate of the touch in screen coordinates
pointer - the pointer index
button - the button
Returns:
whether an Actor in the scene processed the event or not

touchDragged

public boolean touchDragged(int x,
                            int y,
                            int pointer)
Call this to distribute a touch dragged event to the stage.

Specified by:
touchDragged in interface InputProcessor
Overrides:
touchDragged in class InputAdapter
Parameters:
x - the x coordinate of the touch in screen coordinates
y - the y coordinate of the touch in screen coordinates
pointer - the pointer index
Returns:
whether an Actor in the scene processed the event or not

touchMoved

public boolean touchMoved(int x,
                          int y)
Call this to distribute a touch moved event to the stage. This event will only ever appear on the desktop.

Specified by:
touchMoved in interface InputProcessor
Overrides:
touchMoved in class InputAdapter
Parameters:
x - the x coordinate of the touch in screen coordinates
y - the y coordinate of the touch in screen coordinates
Returns:
whether an Actor in the scene processed the event or not

scrolled

public boolean scrolled(int amount)
Call this to distribute a mouse scroll event to the stage. This event will only ever appear on the desktop.

Specified by:
scrolled in interface InputProcessor
Overrides:
scrolled in class InputAdapter
Parameters:
amount - the scroll amount.
Returns:
whether an Actor in the scene processed the event or not.

keyDown

public boolean keyDown(int keycode)
Called when a key was pressed

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)
Called when a key was released

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)
Called when a key was typed

Specified by:
keyTyped in interface InputProcessor
Overrides:
keyTyped in class InputAdapter
Parameters:
character - The character
Returns:
whether the input was processed

act

public void act(float delta)
Calls the Actor.act(float) method of all contained Actors. This will advance any Actions active for an Actor.

Parameters:
delta - the delta time in seconds since the last invocation

draw

public void draw()
Renders the stage


dispose

public void dispose()
Disposes the stage

Specified by:
dispose in interface Disposable

addActor

public void addActor(Actor actor)
Adds an Actor to this stage

Parameters:
actor - the Actor

graphToString

public java.lang.String graphToString()
Returns:
the Stage graph as a silly string

getRoot

public Group getRoot()
Returns:
the root Group of this Stage.

getSpriteBatch

public SpriteBatch getSpriteBatch()
Returns:
the SpriteBatch offers its Actors for rendering.

getCamera

public Camera getCamera()
Returns:
the Camera of this stage.

setCamera

public void setCamera(Camera camera)
Sets the Camera this stage uses. You are responsible for setting it up properly! The draw() will call the Camera's update() method and use it's combined matrix as the projection matrix for the SpriteBatch.

Parameters:
camera - the Camera

getLastTouchedChild

public Actor getLastTouchedChild()
Returns:
the Actor last hit by a touch event.

hit

public Actor hit(float x,
                 float y)
Returns the Actor intersecting with the point (x,y) 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 toStageCoordinates(int, int, Vector2).

Parameters:
x - the x-coordinate in stage coordinates
y - the y-coordinate in stage coordinates
Returns:
the hit Actor or null

toStageCoordinates

public void toStageCoordinates(int x,
                               int y,
                               Vector2 out)
Transforms the given screen coordinates to stage coordinates

Parameters:
x - the x-coordinate in screen coordinates
y - the y-coordinate in screen coordinates
out - the output Vector2.

clear

public void clear()
Clears this stage, removing all Actors and Groups.


removeActor

public void removeActor(Actor actor)
Removes the given Actor from the stage by trying to find it recursively in the scenegraph.

Parameters:
actor - the actor

unfocusAll

public void unfocusAll()

unfocus

public void unfocus(Actor actor)

unfocus

public void unfocus(Actor actor,
                    int pointer)

setKeyboardFocus

public void setKeyboardFocus(Actor actor)

getKeyboardFocus

public Actor getKeyboardFocus()

setScrollFocus

public void setScrollFocus(Actor actor)

getScrollFocus

public Actor getScrollFocus()

setTouchFocus

public void setTouchFocus(Actor actor,
                          int pointer)

getTouchFocus

public Actor getTouchFocus(int pointer)

libgdx API

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