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

= Nifty GUI - Best Practices
:author:
:revnumber:
:revdate: 2016/03/17 20:48
:relfileprefix: ../../
:imagesdir: ../..
ifdef::env-github,env-browser[:outfilesuffix: .adoc]


This page is a short list of best practices that you should know of when starting to use Nifty +++<abbr title="Graphical User Interface">GUI</abbr>+++. The JME3 tutorials focus on JME3-Nifty integration related details. You will find more features in the link:https://github.com/nifty-gui/nifty-gui/raw/1.4/nifty-core/manual/nifty-gui-the-manual-1.3.2.pdf[Nifty GUI Manual].

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


== XML or Java?

You can build Nifty GUIs using XML or Java syntax. Which one should you choose? The XML and Java syntax are equivalent, so is it an either-or choice? Not quite. You typically use XML and Java together.

*  Build your basic static UI layout using XML - it's cleaner to write and read.
*  Use Java syntax to control the dynamic parts of the +++<abbr title="Graphical User Interface">GUI</abbr>+++ at runtime - it's easier to interact with object-oriented code.
*  *Example:* You design two UIs with slightly different XML layouts for mobile and desktop. If you use the same IDs for equivalent elements, your dynamic Java code works the same no matter which of the two base XML layout you use it on. This allows you to switch between a phone and a desktop UI by simply swapping one base XML file.


//== Edit and Preview XML in the SDK

//*  Use the <<sdk#,jMonkeyEngine SDK>> New File wizard to create a new XML file (from the +++<abbr title="Graphical User Interface">GUI</abbr>+++ category, "`Empty Gui`").
//*  The <<sdk#,jMonkeyEngine SDK>> includes an XML editor and a special previewer for Nifty +++<abbr title="Graphical User Interface">GUI</abbr>+++ files.
*  When you open an XML file, you can switch between XML Editor and +++<abbr title="Graphical User Interface">GUI</abbr>+++ Preview mode.

//TIP: The +++<abbr title="Graphical User Interface">GUI</abbr>+++ category in the New File wizard also contains Nifty code samples.


== Validate the XML before loading

The link:http://nifty-gui.sourceforge.net/projects/1.4.2/nifty/nifty/apidocs/index.html?de/lessvoid/nifty/Nifty.html[Nifty class] has _validateXml()_ method that takes the same input XML argument as _fromXml()_. Nifty does not validate the Xml by default, and will blow up in surprising ways if your XML does not conform to the schema. Adding the validation step will save you debugging time. You can validate right before loading, or in your unit tests.


== Use Code Completion

*  Include the following XML schema in the first line of your NiftyGUI XML files
[source,xml]
----

<?xml version="1.0" encoding="UTF-8"?>
<nifty xmlns="http://nifty-gui.lessvoid.com/nifty-gui" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://raw.githubusercontent.com/void256/nifty-gui/1.4/nifty-core/src/main/resources/nifty.xsd https://raw.githubusercontent.com/void256/nifty-gui/1.4/nifty-core/src/main/resources/nifty.xsd">
     <!-- Your IDE now tells you that one <screen></screen> element is expected here, etc. -->
</nifty>

----

*  Now your IDE (including the jMonkeyEngine SDK) will display extra info and do code completion for the Nifty +++<abbr title="Graphical User Interface">GUI</abbr>+++ +++<abbr title="Application Programming Interface">API</abbr>+++.


== Use the ID String Right

*  If you want to interact with an element, give it an ID (String).
*  Use transparent ID-less panels as anonymous spacers.


== Sizing Layers and Panels

*  Specify widths and heights in percent to allow the +++<abbr title="Graphical User Interface">GUI</abbr>+++ to scale.
*  Use `*` instead of a fixed value to make the element fill the remaining space automatically.
*  Be cautious when specifying fixed sizes, and test the outcome in various resolutions.


== Colorcode for Clarity

Screens, layers, and panels…

*  … can have an RGBA background color. +
You can use temporary colors during the design phase to highlight which container is which.
*  … can be transparent. +
In the finished +++<abbr title="Graphical User Interface">GUI</abbr>+++, screens, layers, and panels are typically transparent; the visible elements are the images, text fields, and controls, inside the panels.


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

[source,java]
----
nifty.setDebugOptionPanelColors(true);
----

Before the release, and during testing, set the debug view to false again.
====