Nifty Controls - relu91/nifty-gui GitHub Wiki

Nifty differs between the actual logic of the standard controls (stored in nifty-default-controls-<version></version>.jar) and the visual representation of the controls (stored for instance in nifty-style-black-<version></version>.jar). This way you could use the same version of the nifty-default-controls-<version></version>.jar and simply change the style jar to create or use a completly different look of the controls. You'll just need to make sure to use the same version for both the nifty-default-controls-<version></version>.jar and the nifty-style-black-<version></version>.jar to make sure they match.

This page describes the new standard controls 1.3 API and it is using the default style (nifty-style-black-<version></version>.jar) for all screenshots.

Name	Example	Link to API Page
Button		Button
Chat Control		Chat Control
CheckBox		CheckBox
Console		Console
Drag'n'Drop		Drag'n'Drop
DropDown		DropDown
ImageSelect		ImageSelect
Label		Label
ListBox		ListBox
Menu		Menu
Radiobutton		Radiobutton
Scrollbar		Scrollbar
ScrollPanel		ScrollPanel
Slider		Slider
Tabs		Tabs
TextField		TextField
TreeBox	/images/Standard-controls-treebox.png	TreeBox
Window		Window

Besides these real controls the default style file (nifty-style-black-<version></version>.jar) provides some additional styles for you to use. These are summarized in the following table.

Name	Example	Description
style="nifty-panel"		A Style you can add to any panel to add a nifty background image to the panel."<panel style="nifty-panel" childLayout="center" width="30%" height="20%"></panel>"
style="nifty-panel-no-shadow"		The same as the nifty-panel Style but without the shadow. <panel style="nifty-panel-no-shadow" childLayout="center" width="30%" height="20%"></panel>
style="nifty-panel-red"		The nifty-examples project uses this Style for popup dialogs. <panel style="nifty-panel-red" childLayout="center" width="30%" height="20%"></panel>
style="nifty-panel-red-no-shadow"		The same as the nifty-panel-red Style but without the shadow. <panel style="nifty-panel-red-no-shadow" childLayout="center" width="30%" height="20%"></panel>
style="nifty-panel-simple"		A simple grey panel background. <panel style="nifty-panel-simple" childLayout="center" width="30%" height="20%"></panel>
style="nifty-panel-bright"		A simple panel background that uses a light grey background gradient. <panel style="nifty-panel-bright" childLayout="center" width="30%" height="20%"></panel>

The new Nifty 1.3 Standard Controls API is slightly different.

All Nifty 1.3 standard controls implement the new NiftyControl Interface.

Each of the new Standard Controls provides an Interface specific to the particular control. This Interface can be retrieved with a new method on the Screen:

public class Screen {
  ...
  public < T extends NiftyControl > T findNiftyControl(final String elementName, final Class < T > requestedControlClass);
  ...
} 

and on the Element class:

public class Element {
  ...
  public < T extends NiftyControl > T getNiftyControl(final Class < T > requestedControlClass);
  ...
} 

This is different from the way controls have been retrieved prior to Nifty 1.3 which used a slightly different method name. The old method returned the Nifty Controller directly instead of the new NiftyControl hierarchy. The new Nifty 1.3 API provides specific Interfaces for all of the standard controls and does not expose the Nifty Control Controller directly anymore. You can view this as a more higher level access to the Controls. Instead of the old, more lower level Controller you'll now use the new control Interfaces which provide a much richer API.

So for the Nifty 1.3 standard controls you must use the methods that return NiftyControl. And you need to make sure that you request the specific API interfaces (see below).

Instead of registering single EventListeners on each and every control Nifty 1.3 utilizes the EventBus mechanism.

The EventBus mechanism favours loose coupling between Nifty (as the creator of events) and your application (as the receiver of the events) using a publish/subscribe mechanism. Nifty publishes events to some “global” EventBus. Your application subscribes to specific Events on the EventBus for all events that it is interessted in. What sounds not very different from the standard Listener pattern at first is in fact a great improvement. There is only a dependency to the EventBus and not between the actual objects that communicate. This helps to decouple the objects from one another. Nifty does not need to know who will receive the event in the end. It just creates the event and publishes it on the EventBus and everybody interessted in it will be notified.

Nifty uses the EventBus project for this. The project is available as Open Source under the Apache License, Version 2.0. It’s only 80KB in size, so it should not hurt the download/memory footprint of Nifty that much.

You subscribe to the EventBus using the id of the element as the topic. To make this process even easier Nifty 1.3 offers a special annotation for this. Here is an example:

/**
 * This event handler is directly listening to the ListBoxSelectionChangedEvent that is generated when
 * the ListBox selection is changed. This method is subscribed to the ListBox with the id="listBox".
 */
@NiftyEventSubscriber(id="listBox")
public void onListBoxSelectionChanged(final String id, final ListBoxSelectionChangedEvent<JustAnExampleModelClass> event) {
  // in here we can use the given event to access the new selection
  // event.getSelection(); ...
} 

It's even possible to use a regular expression to specify the Nifty ids you want to receive events for:

/**
 * This is an example how we could use a regular expression to select the elements we're interested in.
 * In this example all of our CheckBox IDs end with "CheckBox".
 *
 * This method will be called for all elements with matching IDs.
 */
@NiftyEventSubscriber(pattern=".*CheckBox")
public void onAllCheckBoxChanged(final String id, final CheckBoxStateChangedEvent event) {
  // do something in here (called for all CheckBoxes)
} 

Using the @NiftyEventSubscriber annotation is directly and automatically supported in all ScreenController and Controller implementation. This means all you need to do to add an Eventlistener in such classes is to annotate a method with the NiftyEventSubscriber annotations and that's all. Nifty will automatically subscribe/unsubscribe all matching methods for you.

On the other hand it is possible to use the @NiftyEventSubscriber annotations on any method in any object. There is just one additional step involved. You'll need to call the static method NiftyEventAnnotationProcessor.process() with your Object as the parameter. Nifty will scan the given Object for all @NiftyEventSubscriber annotations and subscribe them with the EventBus. If you don't need the event handler anymore you should call NiftyEventAnnotationProcessor.unprocess() to unsubscribe all methods again.

There is yet another method to subscribe/unsubscribe for Nifty events that is not using annotations. The method nifty.subscribe() can be used to directly subscribe a "org.bushe.swing.event.EventTopicSubscriber" implementation for a given Nifty-Id and the specific NiftyEvent implementation. There is a unsubscribe Method availabe to unsubscribe the EventTopicSubscriber there as well.

A complete example project that demonstrates the new Standard Controls and the EventBus mechanism is available online in SVN (nifty-default-controls-examples). You can directly access it with SVN:

https://nifty-gui.svn.sourceforge.net/svnroot/nifty-gui/nifty-default-controls-examples/trunk

or browse it online here:

http://nifty-gui.svn.sourceforge.net/viewvc/nifty-gui/nifty-default-controls-examples/trunk/