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

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



== Creating a new Theme


=== Understanding Styles

The Style class is set up to be as open ended as possible for creating custom controls.

Each property of a style can be one of the following data type:

*  String
*  float
*  int
*  boolean
*  ColorRGBA
*  Vector2f
*  Vector3f
*  Vector4f
*  Effect
*  Object

To retrieve a tag from a style you must use the get method for the data type you trying to retrieve like so:

[source,java]
----

screen.getStyle("StyleName").getColorRGBA("TagNameInStyle");

----

These can be used as flags for configuring you control, or style specific info for default Look & Feel

Lets look at the Button.xml file as an example:

[source,htmlblock]
----

<root>
    <element name=”Button”>
        <font>
            <property name=”fontSize” type=”float” value=”18″ />
            <property name=”fontColor” type=”ColorRGBA”>
                <r value=”0.8″ />
                <g value=”0.8″ />
                <b value=”0.8″ />
                <a value=”1.0″ />
            </property>
            <property name=”textAlign” type=”String” value=”Center” />
            <property name=”textVAlign” type=”String” value=”Center” />
            <property name=”textWrap” type=”String” value=”Clip” />
            <property name=”hoverColor” type=”ColorRGBA”>
                <r value=”1.0″ />
                <g value=”1.0″ />
                <b value=”1.0″ />
                <a value=”1.0″ />
            </property>
            <property name=”pressedColor” type=”ColorRGBA”>
                <r value=”0.6″ />
                <g value=”0.6″ />
                <b value=”0.6″ />
                <a value=”1.0″ />
            </property>
        </font>
        <attributes>
            <property name=”resizeBorders” type=”Vector4f”>
                <x value=”5″ />
                <y value=”5″ />
                <z value=”5″ />
                <w value=”5″ />
            </property>
            <property name=”defaultSize” type=”Vector2f”>
                <x value=”100″ />
                <y value=”30″ />
            </property>
        </attributes>
        <images>
            <property name=”defaultImg” type=”String” value=”tonegod/gui/style/def/Button/button_x_u.png” />
            <property name=”hoverImg” type=”String” value=”tonegod/gui/style/def/Button/button_x_h.png” />
            <property name=”pressedImg” type=”String” value=”tonegod/gui/style/def/Button/button_x_d.png” />
        </images>
        <effects>
            <property name=”event0″ type=”Effect”>
                <event value=”Hover” />
                <effect value=”Pulse” />
                <speed value=”3″ />
            </property>
            <property name=”event1″ type=”Effect”>
                <event value=”Press” />
                <effect value=”ImageSwap” />
                <speed value=”0″ />
            </property>
            <property name=”event2″ type=”Effect”>
                <event value=”LoseFocus” />
                <effect value=”ImageSwap” />
                <speed value=”0″ />
            </property>
        </effects>
    </element>
</root>

----

The Style XML file for any given control can contain as many element tags as you would like.  Each becomes another style that can be retrieved via:

[source,java]
----

screen.getStyle("styleName");

----

Each element tag is divided into 4 sections:

*  fonts
*  attributes
*  images
*  effects

The first 3 are interchangeable and only there for organizational purposes.

The 4th (effects) is more specific, as the effects are stored and retrieved via the EffectManage of the Screen.

The tags for storing properties are formatted as follows:

*  If the data type has a single value, the value is stored in the single property tag:

[source,htmlblock]
----

<property name="ID" type="float" value="0.5" />

----

*  If the data type has multiple value, the property tag would contain inner tags named after the value, like such:

[source,htmlblock]
----

<property name="ID" type="Vector4f />
    <x value="0.5 />
    <y value="0.5 />
    <z value="0.5 />
    <w value="0.5 />
</property>

----

Again, to retrieve this you would call:

[source,java]
----

screen.getStyle("styleName").getVector4f("ID");

----



=== The 'effects' Tag

To add a default effect to a control, you would add a property tag under the 'effects' tag, like so:

[source,htmlblock]
----

<property name=”event0″ type=”Effect”>
    <event value=”Hover” />
    <effect value=”Pulse” />
    <speed value=”3″ />
</property>

----

Using Effects can be found HERE.


=== style_map.xml

The style_map.xml file consists of a list of all other XML documents that contain style information for controls. All other XMLdocs could very well could be a single XML document containing all styles, however, for organization purposes, I read in as many from this list as you would like to add.

Each entry in the style_map.xml file are formatted as follows:

[source,htmlblock]
----

<style control=”CustomControl” path=”somePath/MyNewControl.xml” />

----

[NOTE]
====
The control= property is not enforced, it is their for you to keep track of what XML file is used for what control.
====



=== To set up a custom global Look & Feel for your UI



==== STEP 1: Copy the style_map.xml file to a local directory in your Project Assets folder.

[source,htmlblock]
----

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<cursors path="somePath/Cursors.xml" />
	<audio path="somePath/Audio.xml" />
	<style control="Font" path="somePath/Fonts.xml" />
	<style control="Common" path="somePath/Common.xml" />
	<style control="Scrolling" path="somePath/Scrolling.xml" />
	<style control="Window" path="somePath/Window.xml" />
	<style control="Button" path="somePath/Button.xml" />
	<style control="Menu" path="somePath/Menu.xml" />
	<style control="Label" path="somePath/Label.xml" />
	<style control="Slider" path="somePath/Slider.xml" />
	<style control="TextField" path="somePath/TextField.xml" />
	<style control="ChatBox" path="somePath/ChatBox.xml" />
	<style control="Indicator" path="somePath/Indicator.xml" />
</root>

----


==== STEP 2: Point your Screen class to the new style_map.xml file.

[source,java]
----

Screen screen = new Screen(this, "somePath/style_map.xml");

----

You can now copy the existing XML docs for each listed in the style_map.xml file and make the adjustments you would like as default styles.


[IMPORTANT]
====
Don't forget to update the path in the style_map.xml file to point to your local copy for each control XML file you copy/edit.
====