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

= tonegodgui_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.

The first step is to create the screen control. This can be done one of two ways.

. Using the provided default style information:
+
[source,java]
----

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

----

. 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");
screen.initialize();
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).

Next, we add a control. 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. 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.

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);

----

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);

----

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.

So, now lets add a button to the window that will create 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. All events can be consumed by using evt.setConsumed();

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 lets add the button to allow users to create new window:

[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);

----

[NOTE]
====
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
setIsResizable(boolean);

// Makes the control movable
setIsMovable(boolean);

// Constrained to parent dimensions
setLockToParentBounds(boolean);

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

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

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

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

setIgnoreMouse(boolean);

----

NOTE: There are far 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.