# Creating User Interfaces with Nifty GUI

You may want your players to press a button to save a game, you want a scrolling text field for highscores, a text label to display the score, drop-downs to select keymap preferences, or checkboxes to specify multi-media options. Usually you solve these tasks by using Swing controls. Although it is possible to embed a jME3 canvas in a Swing GUI, a 3D game typically runs full-screen, or in a window of its own.

This document introduces you to
, a Java library for building interactive graphical user interfaces (GUIs) for games or similar applications. Nifty GUI (the `de.lessvoid.nifty` package) is well integrated with jME3 through the `com.jme3.niftygui` package. You define the base GUI layout in XML, and control it dynamically from your Java code. The necessary JAR libraries are included in your jME3 download, you do not need to install anything extra. (Just make sure they are on the classpath.)

## Overview

To add a Nifty GUI to your jME3 game:

1. Understand the Nifty GUI Concepts described on this page.
2. Lay out your graphical user interface:
   - Lay out the GUI in XML
   - Lay out the GUI in Java
3. Integrate the GUI into the game:
   - Overlay the User Interface Over the Screen – or –
   - Project the User Interface Onto a Texture
4. Interact with the GUI from Java

## Nifty GUI Concepts

Nifty GUIs are made up of the following elements:

- A Nifty GUI is made up of one or more screens.
  - Nifty displays exactly one screen at a time.
  - Name the first screen `start`. Name any others whatever you like.
  - Every screen is controlled by a Java Controller class.
- A screen contains one or more layers.
  - Layers are containers that impose an alignment on their content (vertical, horizontal, centered)
  - Layers overlap (z-order), and cannot be nested.
- A layer contains panels.
  - Panels are containers that impose an alignment on their content (vertical, horizontal, centered)
  - Panels can be nested, and cannot overlap.
- A panel contains images, text, or controls (buttons, etc).

General usage tips about elements:

- You give an element an ID String if you want to interact with it.
  You can also use transparent, ID-less panels as spacers.
- For layers and panels, you specify width and height in percent, or use `*` to fill the remaining space automatically.
- Screen, layers, and panels…
  - can have an RGBA background color: You can use colors during layout development to highlight which container is which.
  - can be transparent: In the finished GUI, the visible elements are images, text, and controls inside the panels.
- The jMonkeyEngine SDK's Nifty editor lets you switch between the XML editor and a GUI preview, so you see the effects of your code changes.

## Some Pro Tips...

#### XML or Java? Both!

The XML and Java syntax are equivalent, so is it an either-or choice? Not quite. We recommend to use XML to lay out the static parts of the GUI. Then use Java syntax to control the dynamic parts of the GUI at runtime.

#### Activate Debug Highlighting

During development (and during this tutorial), the following debug code makes all panels visible. This helps you arrange them and find errors.

    nifty.setDebugOptionPanelColors(true);

Before the release, and for testing, set it to false again.

#### Use the jMonkeyEngine SDK

The SDK includes an XML editor and previewer for Nifty GUI files. Open an XML file, and switch between XML and Preview mode.

#### Use XML Schema

Include the following XML schema in the first line of your NiftyGUI XML files and your IDE gives you hints and code completion.

    <?xml version="1.0" encoding="UTF-8"?>
    <nifty xmlns="http://nifty-gui.sourceforge.net/nifty-1.3.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://nifty-gui.sourceforge.net/nifty-1.3.xsd http://nifty-gui.sourceforge.net/nifty-1.3.xsd">
         <!-- Your IDE now tells you that one <screen></screen> element is expected here, etc. -->
    </nifty>

## JME-Nifty Sample Code

- XML examples
- Java examples
- jME3-ready version of the Nifty GUI 1.3 demo (sample code, Java)
- Find more sample code in the

## External Documentation

Learn more from the NiftyGUI page!

## Next Steps

Next, learn how to lay out your graphical user interface. Typically, you start with XML.

- Lay out the GUI in XML (recommended)
- Lay out the GUI in Java (optional)

gui, documentation, nifty, hud

view online version