tonegodGUI Documentation (Pre-Alpha Release)

Placeholder for LoginBox

Abstract Event Methods:
[java]
public void onButtonLoginPressed(MouseButtonEvent evt, boolean toggled)
public void onButtonCencelPressed(MouseButtonEvent evt, boolean toggled)
[/java]

ChatBox

Again, this can be expected with the first update. I have a few additions I would like to add to the existing version + it still requires a once over for styles implementation.

Abstract Event Methods:
[java]
public void onSendMsg(String msg)
[/java]

ChatBoxExt
@Override Event Methods:
[java]
public void onSendMsg(String command, String msg)
[/java]

Indicator Class

An indicator is a highly customizable progress bar, which can be used showing/displaying player stats, etc

The Indicator uses the 3 standard contructors with the addition of one extra parameter:
Indicator.Orientation appended to the end of the param list for each

Features include:
Clipping + an alpha mask to create any shaped indicator you would like
Display the indicator in any color you choose.
Image based indicators in place of color+clipping
An overlay image for transparent indicator containers

Constructor example:
[java]
/**

  • Parameters:
  • Screen screen
  • String UID
  • Vector2f position
  • Indicator.Orientation orientation
    */
    Indicator ind1 = new Indicator(
    screen,
    “SomeID”,
    new Vector2f(10,10),
    Indicator.Orientation.VERTICAL
    );
    [/java]

Methods specific to the Indicator class
[java]
// Get the indicators oritentation
getOrientation();

// Configuration methods
setIndicatorColor(ColorRGBA indicatorColor);
setIndicatorAlphaMap(String alphaMapPath);
setIndicatorImage(String imgPath);

// Adjust value ranges
setMaxValue(float maxValue);
setCurrentValue(float currentValue);

// Get current info
getCurrentPercentage();
getCurrentValue();
getMaxValue();
getTextDisplayElement(); // Return the text element for formatting purposes
setDisplayValues(); // Display value in format: current/max or 10/100
setDisplayPercentage(); // Displays percentage: 82% etc
setHideText(); // removes display text (default)
[/java]

OSRViewPort (Off Screen Rendered ViewPort)

This makes use of the standard 3 constructors. The default image is used as an overlay image… think transparent with a border. Use null for no overlay.

Once the constructor is called, you will want to call:

[java]
/** Params:

  • Node node - the node containing your scene
  • float width - the render width
  • float height - the render height
    */
    setOSRBridge(Node root, int width, int height);
    [/java]

The ViewPort’s Camera control methods:
[java]
setUseCameraControlRotate(boolean rotateEnabled); // enable/disable rotation control
setUseCameraControlZoom(boolean zoomEnabled); // enable/disable zoom control

setCameraDistance(float distance);
setCameraHorizonalRotation(float angleInRads);
setCameraVerticalRotation(float angleInRads);
setCameraMinDistance(float distance);
setCameraMaxDistance(float distance);
setCameraMinVerticalRotation(float angleInRads);
setCameraMaxVerticalRotation(float angleInRads);
[/java]

Other methods:
[java]
setBackgroundColor(ColorRGBA color); // ViewPort is transparent by default
[/java]

1 Like

Building Custom Controls

When creating a custom control, the first thing to consider is which existing control already contains the basic functionality of the new control… and extend it! If nothing does the job, extend the basic Element class. We’ll start there.

[java]
public class MyNewControl extends Element {

}
[/java]

Now you can cut & past the standard three constructors from any existing class: Remember to update the the style calls to reflect the style sheet you will create for the new control

[java]
/**

  • Creates a new instance of the MyNewControl control
  • @param screen The screen control the Element is to be added to
  • @param UID A unique String identifier for the Element
  • @param position A Vector2f containing the x/y position of the Element
    */
    public MyNewControl(Screen screen, String UID, Vector2f position) {
    this(screen, UID, position,
    screen.getStyle(“MyNewControl”).getVector2f(“defaultSize”),
    screen.getStyle(“MyNewControl”).getVector4f(“resizeBorders”),
    screen.getStyle(“MyNewControl”).getString(“defaultImg”)
    );
    }

/**

  • Creates a new instance of the MyNewControl control
  • @param screen The screen control the Element is to be added to
  • @param UID A unique String identifier for the Element
  • @param position A Vector2f containing the x/y position of the Element
  • @param dimensions A Vector2f containing the width/height dimensions of the Element
    */
    public MyNewControl(Screen screen, String UID, Vector2f position, Vector2f dimensions) {
    this(screen, UID, position, dimensions,
    screen.getStyle(“MyNewControl”).getVector4f(“resizeBorders”),
    screen.getStyle(“MyNewControl”).getString(“defaultImg”)
    );
    }

/**

  • Creates a new instance of the MyNewControlcontrol
  • @param screen The screen control the Element is to be added to
  • @param UID A unique String identifier for the Element
  • @param position A Vector2f containing the x/y position of the Element
  • @param dimensions A Vector2f containing the width/height dimensions of the Element
  • @param resizeBorders A Vector4f containg the border information used when resizing the default image (x = N, y = W, z = E, w = S)
  • @param defaultImg The default image to use for the Slider’s track
    */
    public MyNewControl (Screen screen, String UID, Vector2f position, Vector2f dimensions, Vector4f resizeBorders, String defaultImg) {
    super (screen, UID, position, dimensions, resizeBorders, defaultImg);

}
[/java]

Note: Vector2f defaultSize, Vector4f resizeBorders, String defaultImg must be defined in your new style.

Next, you should decide on the necessary events you’ll need to make the control function the way you want and implement the appropriate interfaces

[java]
public class MyNewControl extends Element implements MouseWheelListener {

// Which will add the following methods to your new Control:
@Override
public void onMouseWheelPressed(MouseButtonEvent evt) {
	// Add your custom code 
	// remember to call the abstract method for event passthrough
	onMyNewControlMouseWheelPressed(MouseButtonEvent evt);
}
@Override
public void onMouseWheelReleased(MouseButtonEvent evt) {  }
@Override
public void onMouseWheelUp(MouseMotionEvent evt) {  }
@Override
public void onMouseWheelDown(MouseMotionEvent evt) {  }

// You may want to provide passthrough abstract methods for certain events.  Pass along the event if you wish
public abstract void onMyNewControlMouseWheelPressed(MouseButtonEvent evt);

}
[/java]

Add nested elements: Note!! Remeber to check how you control reacts inside a movable, resizable window to ensure you set the default behaviors to react the way you want.

[java]
public class MyNewControl extends Element implements MouseWheelListener {
Button btn;

/**
 * Creates a new instance of the MyNewControl control
 * 
 * @param screen The screen control the Element is to be added to
 * @param UID A unique String identifier for the Element
 * @param position A Vector2f containing the x/y position of the Element
 */
public MyNewControl(Screen screen, String UID, Vector2f position) {
	this(screen, UID, position,
		screen.getStyle("MyNewControl").getVector2f("defaultSize"),
		screen.getStyle("MyNewControl").getVector4f("resizeBorders"),
		screen.getStyle("MyNewControl").getString("defaultImg")
	);
}

/**
 * Creates a new instance of the MyNewControl control
 * 
 * @param screen The screen control the Element is to be added to
 * @param UID A unique String identifier for the Element
 * @param position A Vector2f containing the x/y position of the Element
 * @param dimensions A Vector2f containing the width/height dimensions of the Element
 */
public MyNewControl(Screen screen, String UID, Vector2f position, Vector2f dimensions) {
	this(screen, UID, position, dimensions,
		screen.getStyle("MyNewControl").getVector4f("resizeBorders"),
		screen.getStyle("MyNewControl").getString("defaultImg")
	);
}

/**
 * Creates a new instance of the MyNewControlcontrol
 * 
 * @param screen The screen control the Element is to be added to
 * @param UID A unique String identifier for the Element
 * @param position A Vector2f containing the x/y position of the Element
 * @param dimensions A Vector2f containing the width/height dimensions of the Element
 * @param resizeBorders A Vector4f containg the border information used when resizing the default image (x = N, y = W, z = E, w = S)
 * @param defaultImg The default image to use for the Slider's track
 */
public MyNewControl (Screen screen, String UID, Vector2f position, Vector2f dimensions, Vector4f resizeBorders, String defaultImg) {
	super (screen, UID, position, dimensions, resizeBorders, defaultImg);
	
	// Add the button and set up default behaviors.
	// In this case we add a button that will be movable, however it will only move within the barent Element bounds
	// Perhaps add some code for stuff that needs to happen on different Button events
	btn = new Button ( screen, "SomeID", new Vector2f(5,5) ) {
		@Override
		public void onMouseLeftDown(MouseButtonEvent evt, boolean toggled) {  }
		@Override
		public void onMouseRightDown(MouseButtonEvent evt, boolean toggled) {  }
		@Override
		public void onMouseLeftUp(MouseButtonEvent evt, boolean toggled) {  }
		@Override
		public void onMouseRightUp(MouseButtonEvent evt, boolean toggled) {  }
		@Override
		public void onStillPressedInterval() {  }
		@Override
		public void onButtonFocus(MouseMotionEvent evt) {  }
		@Override
		public void onButtonLostFocus(MouseMotionEvent evt) {  }
	};
	// You may want to pull some of the settings from your style info
	btn.setLockToParentBounds(screen.getStyle("MyNewControl").getBoolean("lockToParent"));
	btn.setIsMovable(screen.getStyle("MyNewControl").getBoolean("isMovable"));
	btn.setScaleNS(screen.getStyle("MyNewControl").getBoolean("scaleNS"));
	btn.setScaleEW(screen.getStyle("MyNewControl").getBoolean("scaleEW"));
	btn.setDockN(true);
	btn.setDockW(true);

	// If you have edded effect definitions to your style, you must call populateEffects(String styleName)
	// in your constructor
	populateEffects("MyNewControl");
}

// Which will add the following methods to your new Control:
@Override
public void onMouseWheelPressed(MouseButtonEvent evt) {
	// Add your custom code 
	// remember to call the abstract method for event passthrough
	onMyNewControlMouseWheelPressed(MouseButtonEvent evt);
}
@Override
public void onMouseWheelReleased(MouseButtonEvent evt) {  }
@Override
public void onMouseWheelUp(MouseMotionEvent evt) {  }
@Override
public void onMouseWheelDown(MouseMotionEvent evt) {  }

// You may want to provide passthrough abstract methods for certain events.  Pass along the event if you wish
public abstract void onMyNewControlMouseWheelPressed(MouseButtonEvent evt);

}
[/java]

I’m thinking by now that you are thinking… “Um… this is looking awful familiar… java… yeah, I get it. I think I can take it from here, thanks.”

But! before continuing lets take a look at handling effects. To replace an effect that was set in the style information:

[java]
// From within the control
// first clear the effect associated with the event you want to replace: params: Effect.EffectEvent
removeEffect(Effect.EffectEvent.Show);

// Then create a new effect: params: Effect.EffectType, Effect.EffectEvent, speed
Effect effect = new Effect(
Effect.EffectType.ZoomIn,
Effect.EffectEvent.Show,
1.5f
);
// Now register the new effect: params: Effect.EffectEvent, Effect
addEffect(Effect.EffectEvent.Show, effect);
[/java]

At some later point you can fire off the effect by retrieving it and passing it to the EffectManager:

[java]
// From within the control:
Effect effect = getEffect(Effect.EffectEvent.Hover);
if (effect != null) {
// If the effect requires a blend image, set it before passing it along
effect.setBlendImage(hoverImg);
// Now, get the effect manager and run the effect
screen.getEffectManager().applyEffect(effect);
}
[/java]

Read on to see how to implement the style xml doc for your custom control.

1 Like

Setting Up Custom Global 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:

screen.getStyle(“StyleName”).getColorRGBA(“TagNameInStyle”);

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

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:

<style control=“CustomControl” path=“tonegod/gui/style/def/Fonts/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, copy the style_map.xml file to a local directory under the Assets folder and point your screen controls at this.

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

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

[java]
<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>
[/java]

2 Likes

Custom Styles cont.

The format for style XML documents is as follows:
There are 3 interchangeable tags for organization purposes, they are:
fonts
attributes
images

The 4th is actually rather specific, as these tags are read slightly different.
effects

The format entering data in the first 3 tags are as follows.

  1. if the data type only has a single value, the tag is a single line consisting of the following properties:
    • TagName
    • Data Type
    • Value
  2. The data type consists of multiple values and follows the following format:
    • Tag Name
    • Data Type
  3. The sub tags of these data type contain a tag named the value component. For example a ColorRGBA has the sub-tags:
    • <r value=“1.0” />
    • <g value=“1.0” />
    • <b value=“1.0” />
    • <a value=“1.0” />

Effects are specific and follow the following format (they must reside within the effects tags

[java]
<property name=“event0” type=“Effect”>
<event value=“Hover” />
<effect value=“Pulse” />
<speed value=“3” />
</property>
[/java]

Effects must be named:
event0
event1
event2
event3
and so on…

In conclusion:

You can edit any of these tags for existing controls, however adding new tags will have no effect as the class for the control will never retrieve the value or even know what to do with it.

When writing your own controls, you specify whatever data you would like to store and use:

screen.getStyle(“StyleName”).getFloat(“TagNameInStyle”);

etc…

1 Like

Placeholder for the Screen Class in more detail

Placeholder for Using the Effect Manager

Cool you documemt this but maybe you indeed want to do this in the wiki as you can at least get a html version for the SDK manual via ?do=export_xhtmlBody on the wiki. Also the code highlighting/syntax safety is better there.

2 Likes
@normen said: Cool you documemt this but maybe you indeed want to do this in the wiki as you can at least get a html version for the SDK manual via ?do=export_xhtmlBody on the wiki. Also the code highlighting/syntax safety is better there.

I can port it over at any time… and then update the OP with a link once it’s available. For getting the plugin out, it will give people a place to quickly get started and report bugs / ask questions / etc while trying it out.

Thanks for posting this.

Can’t wait to test-drive it and give my impressions back. :smiley:

1 Like

Really interesting.
As usual, I like what you show us in your videos
The documentation is pretty well done, simpa, I can’t wait to see what the effects system will be, which for me is a real (easy to use) plus with Nifty gui.
Indicators are really friendly! :slight_smile:
If I had to give a negative point, I would say that the xml files sdk preview systems will miss…it’s still super convenient to see in one click aspect of its interface to adjust /move the components of the interface without having to completely restart the game each time to 5pixels gap ^ ^.
However, I find your system very … JAVA … it really feels to find a swing interface, it’s very pleasant : p

I would certainly among those who try it right out :slight_smile: … if it comes out: s

Thank you and good job;)

3 Likes

Bump for first release.

Hum, it seems not appear in the plugin list…:’(

oh, i think…

What about the effect system…on the TODO list, bug fixing or already ready?

No documentation, no Video but a place holder in the doc :p…lack of time?

@haze said: oh, i think...

What about the effect system…on the TODO list, bug fixing or already ready?

No documentation, no Video but a place holder in the doc :p…lack of time?

Think I may have been to late for this build.

The basic effect system is in place. I’ll put together the documentation for it tomorrow =)

It seems indeed :’(

Great, tomorrow will be a good day :slight_smile:

Ps : You say “basic effect system”, what’s in place and what’s planned to evolve?

@haze said: It seems indeed :'(

Great, tomorrow will be a good day :slight_smile:

Ps : You say “basic effect system”, what’s in place and what’s planned to evolve?

First, I added some info about populating effects from style docs, adding and replacing effects in the section about building custom controls.

As for effects, the reason I say basic is, the original plan was to add the texture deformation effects from the GPUAnimationFactory shader to this as well… and I still might! Just haven’t had time to consider it yet… since BitmapText renders in a very odd way, applying texture deforms to them, doesn’t quite work. Soooo, for now… there is:

FadeIn - working fine
FadeOut - no clue actually
BlendTo - need to verify still, though, I think so
BlendFrom - same
ZoomIn - working correctly now
ZoomOut - working correctly now
SpinIn- works, just not as intended atm
SpinOut - same issue as SpinIn
Pulse - works fine
ColorSwap - works fine
PulseColor - works fine
ImageSwap - works fine

The problems associated with zooming, spinning, etc is the mesh starts at coord 0,0 so:
Rotation happens from the corner
Scaling happens from the corner
etc, etc.

I’ll eventually get around to making these work as I originally intended & probably add the texture deform effects as well.

Build failed last night due to pointing at a license file that apparently wasn’t pushed out with the project. This should be corrected and be available tonight.

I also meant to mention… please reread the original post, as it contains the current state of the plugin and what you can expect from this release.