Laying out the GUI in XML

  1. Nifty GUI Concepts
  2. Nifty GUI XML Layout or Nifty GUI Java Layout
  3. Nifty GUI Overlay or Nifty GUI Projection
  4. Interact with the GUI from Java

You can "draw" the GUI to the screen by writing XML code (alternatively you can also use Java).

Plan Your GUI Layout

In this tutorial, you want to create two game screens: An out-of-game StartScreen that the players see before the game starts; and an in-game that displays info during the game. Before writing code, you plan the GUI layout, either on paper or in a graphic application.

The StartScreen contains:

The HUD contains:

Implement Your GUI Layout

Create an empty screen.xml file in the assets/Interfaces/ directory of your project. One XML file can contain several, or even all screens. As a reminder: Nifty displays one screen at a time; a screen contains several layers on top of one another; each layer contains panels that are embedded into another; the panels contain the actual content (text, images, or controls).

Make Screens

The following minimal XML file contains a start screen and a HUD screen. (Neither has been defined yet.)

<?xml version="1.0" encoding="UTF-8"?>
<nifty xmlns="http://nifty-gui.sourceforge.net/nifty.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
       xsi:schemaLocation="http://nifty-gui.sourceforge.net/nifty.xsd http://nifty-gui.sourceforge.net/nifty.xsd">
  <screen id="start">
    <!-- ... -->
  </screen>
  <screen id="hud">
    <!-- ... -->
  </screen>
</nifty>

Every Nifty GUI must have a start screen. The others (in this example, the HUD screen) are optional.

Note: In the following examples, the XML schema header is abbreviated to just <nifty>.

Make Layers

The following minimal XML file shows how we added layers to the start screen and HUD screen:

<nifty>
  <screen id="start">
    <layer id="background" backgroundColor="#000f">
      <!-- ... -->
    </layer>
    <layer id="foreground" backgroundColor="#0000" childLayout="vertical">
      <!-- ... -->
    </layer>
  </screen>
  <screen id="hud">
    <layer id="background" backgroundColor="#000f">
      <!-- ... -->
    </layer>
    <layer id="foreground" backgroundColor="#0000" childLayout="vertical">
      <!-- ... -->
    </layer>
  </screen>
</nifty>

In a layer, you can now add panels and arrange them. Panels are containers that mark the areas where you want to display text, images, or controls (buttons etc) later.

Make Panels

A panel is the inner-most container (that will contain the actual content: text, images, or controls). You place panels inside layers. The following panels go into in the start screen's foreground layer:

      <panel id="panel_top" height="25%" width="75%" align="center" childLayout="center"
             backgroundColor="#f008">  
      </panel>
      <panel id="panel_mid" height="50%" width="75%" align="center" childLayout="center"
             backgroundColor="#0f08">  
      </panel>
      <panel id="panel_bottom" height="25%" width="75%" align="center" childLayout="horizontal"
             backgroundColor="#00f8">  
        <panel id="panel_bottom_left" height="50%" width="50%" valign="center" childLayout="center" 
             backgroundColor="#44f8">  
        </panel>
        <panel id="panel_bottom_right" height="50%" width="50%" valign="center" childLayout="center"
             backgroundColor="#88f8">  
        </panel>
      </panel>

The following panels go into in the hud screen's foreground layer:

      <panel id="panel_left" width="80%" height="100%" childLayout="vertical" 
      backgroundColor="#0f08">  
        <!-- spacer -->
      </panel>
      <panel id="panel_right" width="20%" height="100%" childLayout="vertical" 
      backgroundColor="#00f8" >  
        <panel id="panel_top_right1" width="100%" height="15%" childLayout="center"
             backgroundColor="#00f8">  
        </panel>
        <panel id="panel_top_right2" width="100%" height="15%" childLayout="center"
             backgroundColor="#44f8">  
        </panel>
        <panel id="panel_bot_right" width="100%" height="70%" valign="center"
             backgroundColor="#88f8">  
        </panel>
      </panel>

The result should look as follows:

Adding Content to Panels

See also on the Nifty GUI site.

Add Images

The start-background.png image is a fullscreen background picture. In the start screen, add the following image element:

    <layer id="background" childLayout="center">
        <image filename="Interface/tutorial/step2/start-background.png"></image>
    </layer>

The hud-frame.png image is a transparent frame that we use as HUD decoration. In the hud screen, add the following image element:

    <layer id="background" childLayout="center">
        <image filename="Interface/tutorial/step2/hud-frame.png"></image>
    </layer>

The face1.png image is an image that you want to use as a status icon. In the hud screen's foreground layer, add the following image element:

        <panel id="panel_bottom_left" height="75%" width="20%" valign="center" childLayout="center">  
            <image filename="Interface/tutorial/step2/face1.png" 
                valign="center" align="center" height="50%" width="30%" >
            </image>
        </panel>

This image is scaled to use 50% of the height and 30% of the width of its container.

Add Static Text

The game title is a typical exmaple of static text. In the start screen, add the following text element:

      <panel id="panel_top" height="25%" width="75%" align="center" childLayout="center">  
          <text text="My Cool Game" font="Interface/Fonts/Default.fnt" width="100%" height="100%" />
      </panel>

For longer pieces of static text, such as an introduction, you can use wrap="true". Add the following text element to the Start screen:

      <panel id="panel_mid" height="50%" width="75%" align="center" childLayout="center">       
        <text text="Here goes some text describing the game and the rules and stuff. Incidentally, 
         the text is quite long and needs to wrap at the end of lines. ..." 
        font="Interface/Fonts/Default.fnt" width="100%" height="100%" wrap="true" />
      </panel>

The font used is jME3's default font "Interface/Fonts/Default.fnt" which is included in the jMonkeyEngine.JAR. You can add your own fonts to your own assets/Interface directory.

Add Controls

Before you can use any control, you must load a Control Definition first. Add the following two lines before your screen definitions:

  <useControls filename="nifty-default-controls.xml" />
  <useStyles filename="nifty-default-styles.xml" />

Label Control

Use label controls for text that you want to edit dynamically from Java. One example for this is the score display. In the hud screen's foreground layer, add the following text element:

        <panel id="panel_top_right" height="100%" width="15%" childLayout="center">  
            <control name="label" color="#000" text="123" width="100%" height="100%" />
        </panel>

Note that the width and height do not scale the bitmap font, but the make indirectly certain it is centered. If you want a different size for the font, you need to provide an extra bitmap font (they come with fixes sizes and don't scale well).

Button Control

Our GUI plan asks for two buttons on the start screen. You add the Start and Quit buttons to the bottom panel of the start screen using the <control> element:

        <panel id="panel_bottom_left" height="50%" width="50%" valign="center" childLayout="center">  
          <control name="button" label="Start" id="StartButton" align="center" valign="center"> 
          </control>
        </panel>
        <panel id="panel_bottom_right" height="50%" width="50%" valign="center" childLayout="center">  
          <control name="button" label="Quit" id="QuitButton" align="center" valign="center"> 
          </control>
        </panel>

Note that these controls don't do anything yet – we'll get to that soon.

Other Controls

Nifty additionally offers many customizable controls such as check boxes, text fields, menus, chats, tabs, … See also on the Nifty GUI site.

Intermediate Result

When you preview this code in the jMonkeyEngine SDK, our tutorial demo should looks as follows: A start screen with two buttons, and a game screen with a simple HUD frame and a blue cube (which stands for any jME3 game content).

Compare this result with the layout draft above.

Next Steps

Integrate the GUI into the game. Typically, you will overlay the GUI.

gui, documentation, nifty, hud

view online version