jMonkeyEngine-wiki/docs/modules/contributions/pages/gui/tonegodgui/quickstart.adoc

= quickstart
:revnumber: 2.0
:revdate: 2020/07/27



== Quick Start Guide:

For anyone who just wants to jump right in and read as you go, here are the basics for getting a UI up and running in minutes.



=== Step 1: Creating the Screen Control

This can be done one of two ways.

*Method 1* - Using the provided default style information:

[source,java]
----

// this = any JME Application
Screen screen = new Screen(this);
guiNode.addControl(screen);

----

*Method 2* - Providing a path to another Style map:

[source,java]
----

// this = any JME Application
Screen screen = new Screen(this, "tonegod/gui/style/def/style_map.xml");
guiNode.addControl(screen);

----

[NOTE]
====
style_map.xml consists of a list of xml documents containing varied styles for varied use. You can copy the default style map and replace one, many, all with project specific style (Covered later in this tutorial).
====



=== Step 2: Adding a Control to the Screen

Might as well start with something interesting as all control constructors follow the same format. Let go with a window and then we’ll add a button to it.

*Constructor 1:* +
Here are the three constructor choices for creating the window:

[source,java]
----

/** Parameters:
  * Screen screen,
  * String UID,
  * Vector2f position
  */

Window win = new Window(screen, "win", new Vector2f(15, 15));
screen.addElement(win);

----

And… boom! You have a fancy new resizable, movable window as part of you’re UI. Now, let’s take a look at the two additional constructors.

*Constructor 2:* +
The second adds a 4th parameter to specify the windows dimensions, like such:

[source,java]
----

/** Additional Parameter:
  * Vector2f dimensions  */

Window win = new Window(screen, "win", new Vector2f(15, 15),
    new Vector2f(400, 300)
);
screen.addElement(win);

----

*Constructor 3:* +
The third option adds 2 more parameters and looks like this:

[source,java]
----

/** Additional Parameters:
  * Vector4f resizeBorders,
  * String defaultImg
  */

Window win = new Window(screen, "win", new Vector2f(15, 15), new Vector2f(400, 300),
    new Vector4f(14,14,14,14),
    "tonegod/gui/style/def/Window/panel_x.png"
);
screen.addElement(win);

----

[NOTE]
====
3 new constructor options have been added recently.  They are the same as the 3 above minus the UID parameter.
====

Any parameters not specified are derived from the defaults specified in the Window style information.

[NOTE]
====
The occasional control extends this constructor format, adding an additional Orientation parameter or possibly a boolean flag for controls that provide multiple configurable layouts.
====



=== Step 3: Adding a Button to the Window

Now we can add a button to the window that will create even MORE windows!

The Button class is one of the only +++<abbr title="Graphical User Interface">GUI</abbr>+++ control classes that implements JME’s Control interface. The Control only becomes active if setInterval is called because the Button requires the use of stillPressed events. This and much more will be cover in later documentation. Again, you ave the three options above for creating an instance of the button control.

[NOTE]
====
The button control (like many controls) is abstract and provides methods for handling user input.
====


First, lets setup a method to create new windows:

[source,java]
----

private int winCount = 0;

public final void createNewWindow(String someWindowTitle) {
    Window nWin = new Window(
        screen,
        "Window" + winCount,
        new Vector2f( (screen.getWidth()/2)-175, (screen.getHeight()/2)-100 )
    );
    nWin.setWindowTitle(someWindowTitle);
    screen.addElement(nWin);
    winCount++;
}

----

Now we can add the button will call our create window method.

[source,java]
----

/** Parameters:
  * Screen screen,
  * String UID,
  * Vector2f position
  */

ButtonAdapter makeWindow = new ButtonAdapter( screen, "Btn1", new Vector2f(15, 55) ) {
    @Override
    public void onButtonMouseLeftUp(MouseButtonEvent evt, boolean toggled) {
        createNewWindow("New Window " + winCount);
    }
};

// Add it to out initial window
win.addChild(makeWindow);

----

[TIP]
====
For layout purposes, it is suggested that you add all child Elements to a control PRIOR to adding the control to the screen… so, create a window, add a button, add window to screen.
====


*A Bit More Info:* +
All controls are based on the Element class which has access to all default behaviors. Behaviors can be enabled disabled on ANY control or primitive Element.


== A Few of the Common Behaviors:

[source,java]
----

// Makes control resizable from defined borders
element.setIsResizable(boolean);

// Makes the control movable
element.setIsMovable(boolean);

// Constrained to parent dimensions
element.setLockToParentBounds(boolean);

// On interaction effects direct parent instead of self
element.setEffectParent(boolean);

// On interaction effects absolute parent (screen lvl) instead of self
element.setEffectAbsoluteParent(boolean);

// allows the control to scale north/south from any encapsulating parent resize
element.setScaleNS(boolean);
// allows the control to scale east/west from any encapsulating parent resize
element.setScaleEW(boolean);

element.setDockN(boolean); // also enables/disables dock south
element.setDockS(boolean); // also enables/disables dock north
element.setDockE(boolean); // also enables/disables dock west
element.setDockW(boolean); // also enables/disables dock east

// Forcing the element to ignore the mouse
element.setIgnoreMouse(boolean);

----

[NOTE]
====
There are more behaviors, however, these are the most critical when creating custom controls to ensure that nested Elements react as you would like when a parent Element is altered.
====



== Quick Start Example In Full

[source,java]
----

public int winCount = 0;
private Screen screen;

public final void createNewWindow(String someWindowTitle) {
    Window nWin = new Window(
        screen,
        "Window" + winCount,
        new Vector2f( (screen.getWidth()/2)-175, (screen.getHeight()/2)-100 )
    );
    nWin.setWindowTitle(someWindowTitle);
    screen.addElement(nWin);
    winCount++;
}

public void simpleInitApp() {
    screen = new Screen(this, "tonegod/gui/style/def/style_map.xml");
    screen.initialize();
    guiNode.addControl(screen);

    // Add window
    Window win = new Window(screen, "win", new Vector2f(15, 15));

    // create button and add to window
    ButtonAdapter makeWindow = new ButtonAdapter( screen, "Btn1", new Vector2f(15, 55) ) {
        @Override
        public void onButtonMouseLeftUp(MouseButtonEvent evt, boolean toggled) {
            createNewWindow("New Window " + winCount);
        }
    };

    // Add it to our initial window
    win.addChild(makeWindow);

    // Add window to the screen
   screen.addElement(win);
}

----