#4 - libgdx Tutorial: TableLayout

Libgdx version used on this post: 0.9.2 (download)

It's time to start coding our great menu screen. Before digging into it, let's have a look at some important changes I made to the source code.

As of libgdx 0.9.6 some of the classes used on this post were modified or removed. You may want to read the post #13 after reading this post, which covers those changes.

Important changes

• Updated the version of libgdx to the latest version available. All I had to do was download the latest build and replace the JARs and .so files on both projects (tyrian-android and tyrian-game). We should get used to this procedure.
• Changes on AbstractScreen:
  • The collaborators (BitmapFont, SpriteBatch, Skin) are now lazily loaded.
  • The show() method redirects the input processing to our Stage object through: Gdx.input.setInputProcessor( stage );
  • The hide() method calls dispose(), or the dispose() method would never be called at all.

TWL - Themable Widget Library

Libgdx includes a library called TWL. This is the description copied from their official web-site: TWL is a graphical user interface library for Java built on top of OpenGL. It provides a rich set of standard widgets including labels, edit fields, tables, popups, tooltips, frames and a lot more. Different layout container are available to create even the most advanced user interfaces.

When compared to libgdx's scene2d's UI abstractions, TWL is way more powerful. It contains even an HTML renderer capable of processing CSS configuration. You can fully customize your widgets using a tool called TWL Theme Editor (Java Web-Start link). For the sake of simplicity we'll stick to scene2d, but in the future we can move up to TWL.

Some examples of TWL GUIs:

Creating the Menu Screen with scene2d

Using the TextButton (com.badlogic.gdx.scenes.scene2d.ui.TextButton) actor that comes with libgdx we could create a simple menu screen with three buttons: "Start game", "Options" and "Hall of Fame". Let's remember the screen flow published on a previous post:

We'll use the following screen layout:

• A welcome message should be displayed at the top.
• The three buttons should appear sequentially.
• All components should be vertically aligned on the center of the screen.

I know, a designer would be welcome here. But let's focus on the code. :)
The most straightforward way of implementing this would be to assign absolute values to the (x,y) coordinates of each actor. If we did that, we'd come up with the following code:

package com.blogspot.steigert.tyrian.screens;

import com.badlogic.gdx.scenes.scene2d.Actor;
import com.badlogic.gdx.scenes.scene2d.ui.ClickListener;
import com.badlogic.gdx.scenes.scene2d.ui.Label;
import com.badlogic.gdx.scenes.scene2d.ui.TextButton;
import com.blogspot.steigert.tyrian.Tyrian;

public class MenuScreen
    extends
        AbstractScreen
{
    // setup the dimensions of the menu buttons
    private static final float BUTTON_WIDTH = 300f;
    private static final float BUTTON_HEIGHT = 60f;
    private static final float BUTTON_SPACING = 10f;

    public MenuScreen(
        Tyrian game )
    {
        super( game );
    }

    @Override
    public void resize(
        int width,
        int height )
    {
        super.resize( width, height );
        final float buttonX = ( width - BUTTON_WIDTH ) / 2;
        float currentY = 280f;

        // label "welcome"
        Label welcomeLabel = new Label( "Welcome to Tyrian for Android!", getSkin() );
        welcomeLabel.x = ( ( width - welcomeLabel.width ) / 2 );
        welcomeLabel.y = ( currentY + 100 );
        stage.addActor( welcomeLabel );

        // button "start game"
        TextButton startGameButton = new TextButton( "Start game", getSkin() );
        startGameButton.x = buttonX;
        startGameButton.y = currentY;
        startGameButton.width = BUTTON_WIDTH;
        startGameButton.height = BUTTON_HEIGHT;
        stage.addActor( startGameButton );

        // button "options"
        TextButton optionsButton = new TextButton( "Options", getSkin() );
        optionsButton.x = buttonX;
        optionsButton.y = ( currentY -= BUTTON_HEIGHT + BUTTON_SPACING );
        optionsButton.width = BUTTON_WIDTH;
        optionsButton.height = BUTTON_HEIGHT;
        stage.addActor( optionsButton );

        // button "hall of fame"
        TextButton hallOfFameButton = new TextButton( "Hall of Fame", getSkin() );
        hallOfFameButton.x = buttonX;
        hallOfFameButton.y = ( currentY -= BUTTON_HEIGHT + BUTTON_SPACING );
        hallOfFameButton.width = BUTTON_WIDTH;
        hallOfFameButton.height = BUTTON_HEIGHT;
        stage.addActor( hallOfFameButton );
    }
}

And the following result:

All right, it does the job. But is this code easy to read and maintain? It contains many mathematical calculations just to come up with screen coordinates for a simple design. Let's try something better.

Introducing the TabletLayout

We could use the TableLayout project, which: is a lightweight library for describing a hierarchy of GUI widgets and laying them out using rows and columns. Assembling GUI widgets in code is clumsy and obfuscates the widget hierarchy. TableLayout provides its own simple and concise language for expressing the GUI. TableLayout cleanly describes an entire object graph of GUI widgets, leaving the Java code clean and uncluttered.

That's exactly what we want, and these are the steps to follow:

1. Open the TableLayout Editor application (Java Web-Start link).
2. Write the layout we want following the editor's language.
3. Save the layout descriptor to a text file inside our resources folder.
4. On the MenuScreen class, load this layout descriptor and make final configurations.

With the following layout descriptor:

debug
* spacing:10 padding:0 align:center
'Welcome to Tyrian for Android!' spacingBottom:20
---
[startGameButton] width:300 height:60
---
[optionsButton] width:300 height:60
---
[hallOfFameButton] width:300 height:60

I got the following preview:

Now we should save this layout descriptor inside our resources folder. I saved it under: tyrian-android/assets/layout-descriptors/menu-screen.txt
The final step is to modify our MenuScreen class to read this file, as follows:

package com.blogspot.steigert.tyrian.screens;

import com.badlogic.gdx.Gdx;
import com.badlogic.gdx.scenes.scene2d.Actor;
import com.badlogic.gdx.scenes.scene2d.ui.ClickListener;
import com.badlogic.gdx.scenes.scene2d.ui.Label;
import com.badlogic.gdx.scenes.scene2d.ui.Skin;
import com.badlogic.gdx.scenes.scene2d.ui.TextButton;
import com.badlogic.gdx.scenes.scene2d.ui.tablelayout.Table;
import com.badlogic.gdx.scenes.scene2d.ui.tablelayout.TableLayout;
import com.blogspot.steigert.tyrian.Tyrian;

public class MenuScreen
    extends
        AbstractScreen
{
    public MenuScreen(
        Tyrian game )
    {
        super( game );
    }

    @Override
    public void resize(
        int width,
        int height )
    {
        super.resize( width, height );

        // retrieve the skin (created on the AbstractScreen class)
        Skin skin = super.getSkin();

        // create the table actor
        Table table = new Table( getSkin() );
        table.width = width;
        table.height = height;

        // add the table to the stage and retrieve its layout
        stage.addActor( table );
        TableLayout layout = table.getTableLayout();

        // [edit] this section is not needed
        // register the label "welcome"
        // Label welcomeLabel = new Label( "Welcome to Tyrian for Android!", skin );
        // layout.register( "welcomeMessage", welcomeLabel );

        // register the button "start game"
        TextButton startGameButton = new TextButton( "Start game", skin );
        startGameButton.setClickListener( new ClickListener() {
            @Override
            public void click(
                Actor actor,
                float x,
                float y )
            {
                game.setScreen( game.getStartGameScreen() );
            }
        } );
        layout.register( "startGameButton", startGameButton );

        // register the button "options"
        TextButton optionsButton = new TextButton( "Options", skin );
        optionsButton.setClickListener( new ClickListener() {
            @Override
            public void click(
                Actor actor,
                float x,
                float y )
            {
                game.setScreen( game.getOptionsScreen() );
            }
        } );
        layout.register( "optionsButton", optionsButton );

        // register the button "hall of fame"
        TextButton hallOfFameButton = new TextButton( "Hall of Fame", skin );
        hallOfFameButton.setClickListener( new ClickListener() {
            @Override
            public void click(
                Actor actor,
                float x,
                float y )
            {
                game.setScreen( game.getHallOfFameScreen() );
            }
        } );
        layout.register( "hallOfFameButton", hallOfFameButton );

        // finally, parse the layout descriptor
        layout.parse( Gdx.files.internal( "layout-descriptors/menu-screen.txt" ).readString() );
    }
}

And that's it! All mathematical calculations are gone. I also set the listeners to the buttons, so that they move the player to other screens. Note that I'm just adding the table to the stage. The other actors are registered on the table's layout, using the same IDs contained in the layout descriptor.

Conclusion

In this post we saw how to implement a screen layout separating the presentation (layout descriptor) from the controller (MenuScreen) code using TableLayout. Now we can easily read it and modify it when necessary. It took us some effort to learn a new component, but this effort will certainly pay off as we create and maintain the other screens. I didn't detail the Skin object we used because it's not so important at this moment, and I would need an entire post for it. This is the tag on Subversion for this post. Thanks!