jMonkeyEngine-wiki/docs/modules/ROOT/pages/jme3/advanced/nifty_gui_overlay.adoc

= Integrating Nifty GUI: Overlay
:author:
:revnumber:
:revdate: 2016/03/17 20:48
:keywords: gui, documentation, nifty, hud
:relfileprefix: ../../
:imagesdir: ../..
:experimental:
ifdef::env-github,env-browser[:outfilesuffix: .adoc]


.  <<jme3/advanced/nifty_gui#,Nifty GUI Concepts>>
.  <<jme3/advanced/nifty_gui_best_practices#,Nifty GUI Best Practices>>
.  <<jme3/advanced/nifty_gui_xml_layout#,Nifty GUI XML Layout>> or <<jme3/advanced/nifty_gui_java_layout#,Nifty GUI Java Layout>>
.  *Nifty +++<abbr title="Graphical User Interface">GUI</abbr>+++ Overlay* or <<jme3/advanced/nifty_gui_projection#,Nifty GUI Projection>>
.  <<jme3/advanced/nifty_gui_java_interaction#,Interact with the GUI from Java>>


image::jme3/advanced/nifty-gui-example.png[nifty-gui-example.png,width="300",height="200",align="left"]


Typically, you define a key (for example escape) that switches the +++<abbr title="Graphical User Interface">GUI</abbr>+++ on and off. The +++<abbr title="Graphical User Interface">GUI</abbr>+++ can be a StartScreen, OptionsScreen, CharacterCreationScreen, etc. While the +++<abbr title="Graphical User Interface">GUI</abbr>+++ is up, you pause the running game, and then overlay the +++<abbr title="Graphical User Interface">GUI</abbr>+++. You also must switch to a different set of user inputs while the game is paused, so the player can use the mouse pointer and keyboard to interact with the +++<abbr title="Graphical User Interface">GUI</abbr>+++.

You can also <<jme3/advanced/nifty_gui_projection#,project>> the +++<abbr title="Graphical User Interface">GUI</abbr>+++ as a texture onto a mesh texture (but then you cannot click to select).
On this page, we look at the overlay variant, which is more commonly used in games.


== Sample Code


*  link:https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-examples/src/main/java/jme3test/niftygui/TestNiftyGui.java[TestNiftyGui.java]

[TIP]
====
The jme3-niftygui library is included in jMonkeyEngine. If you installed jMonkeyEngine using one of the <<documentation#install,optional methods>>, it will be added to your projects Library folder as part of the installation. If you're using the jMonkeyEngine SDK, you add it to any project by btn:[RMB] selecting your projects `Library` folder, choosing `menu:Add Library[jme-niftygui]` followed by `Add Library`.
====


== Overlaying the User Interface Over the Screen

This code shows you how to overlay anything on the screen with the +++<abbr title="Graphical User Interface">GUI</abbr>+++. This is the most common usecase.

[source,java]
----

NiftyJmeDisplay niftyDisplay = NiftyJmeDisplay.newNiftyJmeDisplay(
    assetManager, inputManager, audioRenderer, guiViewPort);
/** Create a new NiftyGUI object */
Nifty nifty = niftyDisplay.getNifty();
/** Read your XML and initialize your custom ScreenController */
nifty.fromXml("Interface/tutorial/step2/screen.xml", "start");
// nifty.fromXml("Interface/helloworld.xml", "start", new MySettingsScreen(data));
// attach the Nifty display to the gui view port as a processor
guiViewPort.addProcessor(niftyDisplay);
// disable the fly cam
flyCam.setDragToRotate(true);

----

Currently you do not have a ScreenController – we will create one in the next exercise. As soon  as you have a screen controller, you will use the commented variant of the XML loading method:

[source,java]
----
nifty.fromXml("Interface/helloworld.xml", "start", new MySettingsScreen());
----

The `MySettingsScreen` class is a custom de.lessvoid.nifty.screen.ScreenController in which you will implement your +++<abbr title="Graphical User Interface">GUI</abbr>+++ behaviour.

If you have many screens or you want to keep them organized in separate files there is a method available that will just load an additional XML file. The content of the files are
simply added to whatever XML data has been loaded before.

[source,java]
----
nifty.addXml("Interface/mysecondscreen.xml");
----


== Next Steps

Now that you have layed out and integrated the +++<abbr title="Graphical User Interface">GUI</abbr>+++ in your app, you want to respond to user input and display the current game. Time to create a ScreenController!

*  <<jme3/advanced/nifty_gui_java_interaction#,Interact with the GUI from Java>>