libgdx API

com.badlogic.gdx.scenes.scene2d.ui
Class Container

java.lang.Object
  extended by com.badlogic.gdx.scenes.scene2d.Actor
      extended by com.badlogic.gdx.scenes.scene2d.Group
          extended by com.badlogic.gdx.scenes.scene2d.ui.tablelayout.Table
              extended by com.badlogic.gdx.scenes.scene2d.ui.Container
All Implemented Interfaces:
Layout
Direct Known Subclasses:
Pane, Window

public class Container
extends Table

Functionality

A Container is a Group capable of layouting inserted Actor instances in a table layout. See http://code.google.com/p/table-layout/

Layout

Actors added to the Container will be layouted in rows and columns. To start a new row call the row() method. To insert an Actor into the current row call the add(Actor) method. Actors are added from left to right to the current row. Do not use the Group.addActor(Actor), Group.addActorAfter(Actor, Actor), Group.addActorAt(int, Actor), Group.addActorBefore(Actor, Actor) methods!

CellProperties

Each added Actor is contained within a cell, which has Container.CellProperties defining the layout of that Actor within the cell as well as the layout of the cell within the table.

To specify how an Actor should be layouted within the cell, one can manipulate the Container.CellProperties instance returned by the add(Actor) method. It allows to define the alignment, padding, minimum and maximum size of the Actor within the cell. By default an Actor's width and height are taken. If the Actor is a Widget its preferred width and height are taken (see Widget.getPrefWidth() and Widget.getPrefWidth(). To let an Actor fill the entire cell on either or both the x- and y-axis one can use the Container.CellProperties.fill(boolean, boolean) method. The layouting process may resize the Actor according to the Container.CellProperties as well as the available space of the cell within the table.

To specify how a cell should be layouted within the table the Container.CellProperties class offers the methods Container.CellProperties.expand(boolean, boolean), Container.CellProperties.spacing(int, int, int, int) and Container.CellProperties.colspan(int) method.

The Container.CellProperties.expand(boolean, boolean) method will make the cell take up any remaining space in the layout. If multiple cells are configured to expand, the sizes of each cell determined by its contained Actor are used as weightings. Additionally one can use the Container.CellProperties.expand(int, int) method to directly specify a weight.

The Container.CellProperties.spacing(int, int, int, int) method allows to define how much space should be left empty between adjacent cells.

The Container.CellProperties.colspan(int) method allows to define how many columns a cell should span in the table. Note that a table does not necessarily have to have the same amount of columns in every row.

To set the Container.CellProperties for all cells in an entire row, one can manipulate the Container.CellProperties instance returned by the row() method.

Container Size

A Container's size is usually determined by the dimensions given in its constructor. Unless the Container is nested inside another Container, its width and height will stay constant. To programmatically change the size of a Container call the setPrefSize(float, float) method.

Layout Invalidation

When a Container is resized, its layout has to be recomputed. For this process to work the Container has to be invalidated, which will trigger a relayouting in the next call to either Table.layout() or Table.draw(com.badlogic.gdx.graphics.g2d.SpriteBatch, float). Consequently, if a Container is nested inside another Container, the parent Container also has to be invalidated.

To perform the invalidation of a Container call the invalidate() method. To also invalidate a Container's parent Container call the invalidateHierarchically() method, which will invalidate the Container and all its parents.

An Actor added to a container can also change its (preferred) size. In this case the Container has to be informed of this circumstance by a explicitely calling either invalidate() or invalidateHierarchically().

Restrictions

Once an Actor is added to a Container, it's width and height controlled by the Container (unless you chose to use the method described in the last paragraph). For this reason, applying an Action to an Actor contained in a Container will not work. It is advised to not change the size of contained Actors during runtime, as layouting every frame might be a costly operation.

Actors should also not be scaled or rotated when contained inside a Container. The layouting algorithm will simply ignore these properties!

Style

A Container has no graphical representation. See Window and Pane for styled Containers.

Author:
mzechner

Nested Class Summary
static class Container.CellProperties
          Class specifying the layout of an Actor within a cell as well as the behaviour of th cell within the entire layout.
 
Field Summary
 
Fields inherited from class com.badlogic.gdx.scenes.scene2d.ui.tablelayout.Table
layout
 
Fields inherited from class com.badlogic.gdx.scenes.scene2d.Group
children, debug, debugTexture, focusedActor, groups, immutableChildren, immutableGroups, keyboardFocusedActor, lastTouchedChild, namesToActors, oldBatchTransform, scenetransform, scrollFocusedActor, tmp4, transform
 
Fields inherited from class com.badlogic.gdx.scenes.scene2d.Actor
actions, color, height, name, originX, originY, parent, rotation, scaleX, scaleY, touchable, width, x, y
 
Constructor Summary
Container(java.lang.String name, int prefWidth, int prefHeight)
          Creates a new container with the given name and (preferred) width.
 
Method Summary
 Container.CellProperties add(Actor actor)
          Adds a new Actor to this Container.
 Container align(int align)
          Sets the alignment of this container's content within the container.
 void invalidate()
          Invalidates this layout.
 void invalidateHierarchically()
          Invalidates this layout and all parents that implement the Layout interface.
 Container padding(int top, int left, int bottom, int right)
          Sets the padding of this container.
 Container.CellProperties row()
          Adds a new row to the table layout of this Container.
 void setPrefSize(float width, float height)
          Sets the (preferred) size of this Container.
 
Methods inherited from class com.badlogic.gdx.scenes.scene2d.ui.tablelayout.Table
applyLayout, draw, drawDebug, getPrefHeight, getPrefWidth, layout
 
Methods inherited from class com.badlogic.gdx.scenes.scene2d.Group
act, addActor, addActorAfter, addActorAt, addActorBefore, clear, disableDebugging, drawChild, drawChildren, enableDebugging, findActor, focus, getActors, getGroups, hit, keyboardFocus, keyDown, keyTyped, keyUp, removeActor, removeActorRecursive, resetTransform, scrolled, scrollFocus, setupTransform, sortChildren, swapActor, swapActor, toChildCoordinates, touchDown, touchDragged, touchMoved, touchUp, unfocusAll, unfocusAll, updateTransform
 
Methods inherited from class com.badlogic.gdx.scenes.scene2d.Actor
action, clearActions, isMarkedToRemove, markToRemove, remove, toLocalCoordinates, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Container

public Container(java.lang.String name,
                 int prefWidth,
                 int prefHeight)
Creates a new container with the given name and (preferred) width. See the class documentation for more information (Container).

Parameters:
name - the name of the container.
prefWidth - the (preferred) width
prefHeight - the (preferred) height
Method Detail

add

public Container.CellProperties add(Actor actor)
Adds a new Actor to this Container. See the class documentation for more information (Container).

Parameters:
actor - the Actor
Returns:
the Container.CellProperties of the cell containing the Actor.

row

public Container.CellProperties row()
Adds a new row to the table layout of this Container. All subsequent calls to add(Actor) will add the Actors to this row. See the class documentation for more information (Container).

Returns:
the Container.CellProperties for all cells within this row.

padding

public Container padding(int top,
                         int left,
                         int bottom,
                         int right)
Sets the padding of this container. The padding will take away space from the cells container in the Container.

Parameters:
top - the top padding
left - the left padding
bottom - the bottom padding
right - the right padding
Returns:
this container

align

public Container align(int align)
Sets the alignment of this container's content within the container.

Parameters:
align - combination of TableLayout.TOP, TableLayout.LEFT, etc.
Returns:
this container

invalidateHierarchically

public void invalidateHierarchically()
Invalidates this layout and all parents that implement the Layout interface. See the class documentation for more information (Container).


invalidate

public void invalidate()
Invalidates this layout. See the class documentation for more information (Container)

Specified by:
invalidate in interface Layout
Overrides:
invalidate in class Table

setPrefSize

public void setPrefSize(float width,
                        float height)
Sets the (preferred) size of this Container. Calls invalidateHierarchically() implicitely.

Parameters:
width - the width
height - the height

libgdx API

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