You can find some pieces in the Nifty wiki, on the blog that you’re reading right now, in forums like the Nifty Forum at sf.net or the jMonkeyEngine GUI Forum. Basically you have some bits of knowledge here and others somewhere else.

Therefore something we’d really like to do was to consolidate all of Niftys documentation into one single information hub. And so we did … and we’re now proud to present to you:

Nifty GUI 1.3.1 – The Missing Manual

Nifty GUI 1.3.1 - The Missing Manual

The PDF is an epic 110 pages book hosted at sf.net that explains (almost) everything that you ever wanted to know about Nifty! The book will act as both a tutorial/introduction to Nifty as well as an in depth reference of the more complicated matters. The PDF contains lots of code examples, screenshots and illustrations.

I hope you had a great christmas 2011 and that you’ll enjoy reading the manual!

void

PS: In other news Nifty 1.3.1 has been released! Get it at sf.net while it’s hot! I’ll write a proper blog post about 1.3.1 as soon as I’ve got the complete changelog together

Example

You can check the first example of the new ListBox online with the following Webstart URL:

The source code of this project is available online. You can check out the source directly from SVN using https://nifty-gui.svn.sourceforge.net/svnroot/nifty-gui/nifty-default-controls-examples/trunk or you can browse it online here: http://nifty-gui.svn.sourceforge.net/viewvc/nifty-gui/nifty-default-controls-examples/trunk/.

And if that is not enough … we’ve done the same new API treatment to the CheckBox and we plan to do the same to the remaining Nifty Standard Controls!

Reference in the Wiki

You can find a complete reference about the new standard controls in Nifty 1.3 already on the Wiki (for the ListBox and the CheckBox):

http://sourceforge.net/apps/mediawiki/nifty-gui/index.php?title=Nifty_Standard_Controls_%28Nifty_1.3%29

And you can keep reading about all the little Nifty details we’ve changed and improved and especially why.

It all started with a feature request for Nifty 1.3 which seems easy to add at first. Removing all or single elements from a Nifty ListBox sounds like a reasonable feature to have available. So I’d try to add this … and failed miserable! The closer I looked into it the more despaired I’ve become.

What a mess!

Something I’d really love to do with Nifty 2.0 is to add a nice and clean API to the standard Nifty controls. The current way of interacting with most of the Nifty controls is kinda awkward (at least) and I want to improve this. So, I thought, hey, why not try to define a new API for the ListBox as a preparation for this and see how everything works out. Well, it turns out that in the end I’ve pretty much rewrote the whole ListBox! =) And that the new one is way better than what you currently have available!

One of the shortcomings of the old ListBox was speed. Internally it directly added the Nifty element tree adding elements dynamically and then used a Scrollpanel to scroll around that (maybe) huge list of elements. So basically it always rendered all elements and used the clipping of the element to hide everything that was not currently seen. Not a great idea after all

Another problem was the API and that’s a little difficult to interact with Niftys internal screen representation. Although it’s not impossible to dynamically add/remove elements from Nifty this might not be the ideal solution to the ListBox problem.

So what did we changed? Well, actually a lot!

The new ListBox:

• Instead of relying upon the scroll panel we now only use Nifty elements for what you can see and simply replace the content of the elements when you scroll to a big list of items. So, when your ListBox only display 4 elements there really are only 4 Nifty elements allocated. Of course the ListBox allows many more Items to be added but in that case only the content of the 4 elements are replaced. You can now specify how many elements you want your display to show with the “displayItems” attribute.

• Scrollbars are now optional and you can disable them completly with the “vertical” and “horizontal” attributes. Simply adding for instance vertical=”false” to the ListBox will hide the vertical Scrollbar.

• The ListBox now supports single as well as multiple selections. This means you can now configure your ListBox to allow the selection of only a single item or that you want to select multipe items. If you don’t want to allow selection at all you can even disable the selection completly.

• Instead of relying on storing Strings the new ListBox allows you to story your own Objects directly. So say you want your user to select different space ships by the name of the ship you could simply store your “Ship” instances directly in the ListBox. Nifty determines what text it should display for your instance by calling toString() of your objects. If this is not suitable for you, you can change this by setting a specifc ListBoxViewConverter for your class.

• The new ListBox now features a pretty complete API ListBox that allows you to dynamically add, remove, select, clear items to the ListBox. This is now all available using generics..

EventBus Notification

In the process of updating the ListBox we’ve noticed that we’re missing a nice way to allow the controls to notify other components of the system about things happening. If the selection of the ListBox is changed we’d like other parts to be notified about that event. Well, the first thing that comes to ones mind is of course the Listener/Observer pattern. But there are some problems with this approach, mostly the strong binding between the objects that communicate. There is a great PDF available from the OSGI people that discusses some of the problems of the Listener pattern.

Having previously worked with GWT 2.x and its event bus architecture we’d like to have someting similar for Nifty too. What we want is a loose coupling between Nifty (as the creator of events) and your application (as the receiver of the events). As it turns out a publish/subscribe mechanism allows us to do just that! Nifty publishes events to some “global” EventBus. And your application on the other hand subscribes to this EventBus for all the events that it needs to handle. 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 objects that communicate! Which helps a lot 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 to the EventBus and everybody interessted in it will be notified.

As it turns out there is a neat little project available that implements that mechanism for us. It is called EventBus and 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. Nifty is now using the EventBus project for ListBox and CheckBox notifications which worked very very well so far! You subscribe to the EventBus using the id of the element as a topic and you’ll receive all events that the control with the given id produces. In the case of the ListBox this means that you receive instances of the ListBoxSelectionChangedEvent. This basically sends you the current selection of the ListBox everytime the selection has been changed

Good Times,
void

PS: And if you NOW don’t feel like christmas is already here then I can’t help you =)

In order to improve the usability of Nifty, Nifty user arielsan of gemserk has started creating a “Builder Pattern” based way to create Nifty GUIs. These classes can be used from within java to create a Nifty GUI without the need for an external xml file.

We have improved the solution together and there is a Nifty ScreenBuilder class available as your starting point. Here is a quick example what you can do with it:

Screen mainScreen = new ScreenBuilder("main") {{
  controller(new ScreenControllerExample());

  layer(new LayerBuilder("layer") {{
    backgroundColor("#003f");
    childLayoutCenter();

    panel(new PanelBuilder() {{
      id("panel");
      childLayoutCenter();
      height(percentage(25));
      width(percentage(80));
    }});
  }});
}}.build(nifty);

Look no further!

The Nifty GUI Wiki has been updated and the <screen> Tag and all of its attributes have been explained and documented!

You can find the reference here: http://sourceforge.net/apps/mediawiki/nifty-gui/index.php?title=Elements

Have fun,
void

Hudson will svn checkout all relevant nifty projects and will then “mvn clean deploy” them to the nifty maven repository at sf.net. This means that all projects that are already being build with maven and have this in their pom.xml:

<repositories>
    <repository>
      <id>nifty-maven-repo.sourceforge.net</id>
      <url>http://nifty-gui.sourceforge.net/nifty-maven-repo</url>
    </repository>
</repositories>

will automatically get the latest nifty builds!

Currently this means 1.2-SNAPSHOT for Nifty as well as the Nifty Default Controls and the black Style projects and 1.0-SNAPSHOT for the new Nifty Renderer Projects.

Currently the following projects are build each night.

Nifty
http://nifty-gui.sourceforge.net/nifty-maven-repo/lessvoid/nifty/
http://nifty-gui.sourceforge.net/nifty-maven-repo/lessvoid/nifty-default-controls/
http://nifty-gui.sourceforge.net/nifty-maven-repo/lessvoid/nifty-style-black/

Nifty Renderer
http://nifty-gui.sourceforge.net/nifty-maven-repo/lessvoid/nifty-lwjgl-slick-renderer/
http://nifty-gui.sourceforge.net/nifty-maven-repo/lessvoid/nifty-lwjgl-renderer/
http://nifty-gui.sourceforge.net/nifty-maven-repo/lessvoid/nifty-slick-renderer/
http://nifty-gui.sourceforge.net/nifty-maven-repo/lessvoid/nifty-java2d-renderer/

The JME2 Renderer currently has some weird problems being automatically build. So this is not yet available – still working on it:
http://nifty-gui.sourceforge.net/nifty-maven-repo/lessvoid/nifty-jme-renderer/

If you’re not using Maven you should still be able to get the SNAPSHOT jars from the URLs mentioned above. Just find the sub directory 1.2-SNAPSHOT or 1.0-SNAPSHOT and get the latest JAR from there. Don’t mind the name of the jar tho. It’s automatically generated by Maven and it’s just named with the build date and time.

Good luck!
void

When using Nifty together with Slick2d this is represented by the NiftyGameState class. Using this class your Slick2d StateBasedGame can easliy switch from your in game state to the NiftyGameState and display the GUI.

But this is not the only way Nifty can be used. You can easily use Nifty to render your in-game GUI too! Nifty plays well with others (as long as they use OpenGL/lwjgl for rendering that is).

It’s not complicated at all and I wanted to write example code that demonstrates how easy it is for a long time. Motivated by a question at the Nifty Forum at souceforge.net I did now

What’s demonstrated in the new slick example is, how you can use Nifty to render a GUI on top of a normal slick GameState.

Here is a screenshot of the example which renderes Text from within Slick that changes color when you press the keys 1-3. On top of this it renders a Nifty GUI that responds to mouse events. Additionally if you press 1-3 the colored Nifty boxes start to shake

Slick Overlay with Nifty GUI

You can try it out with the Webstart:

http://nifty-gui.sourceforge.net/webstart/nifty-slick-overlay-demo.jnlp

and you can find the example in svn or you can browse it online here:

http://nifty-gui.svn.sourceforge.net/viewvc/nifty-gui/nifty-examples/trunk/src/main/java/de/lessvoid/nifty/examples/slick/niftyoverlay/ (Java classes)

http://nifty-gui.svn.sourceforge.net/viewvc/nifty-gui/nifty-examples/trunk/src/main/resources/slick/niftyoverlay/overlay.xml?revision=534&view=markup (Nifty XML for the Screen – overlay.xml)

Keep reading the full Article to see the details on how we get this to work and what you need to consider.

The way it works is pretty easy and it even works with anything you’ve rendered in lwjgl. Slick is not required but as shown it works very well with Slick too.

So you just need to:

1. Save your current OpenGL-State and enable 2d Mode
   You have to make sure you save your current OpenGL state and make sure you are in 2d “mode” before calling Nifty. Which means that everything is setup for 2d OpenGL rendering (orthogonal projection, modelview matrix aligned with the screen, etc. In Slick this is all handled by a single call to SlickCallable.enterSafeBlock(). This makes sure that the current Slick state is saved and changes in Slick or Nifty don’t disturb each other (we’re already in 2d mode too because of slick).
2. Call Nifty to render its GUI
   You call Nifty.render() to render the Nifty GUI. You can call render() with a boolean parameter that tells Nifty to clear the screen (parameter = true) or if it should not clear the screen at all (parameter = false). If you are rendering an overlay you probably want to leave the screen as is and render your GUI on top. So in this case simply call nifty.render(false).
3. Restore your State and continue your own Rendering
   When nifty.render() returns you can reset your state so that you can continue rendering 3d triangles or whatever you want to render on top (!) of Nifty GUI. Again in Slick this is a single SlickCallable.leaveSafeBlock() call.
4. Forward KeyEvents
   You decide if keyEvents get past through to Nifty by calling nifty.keyEvent() with the events you want that Nifty gets. If you don’t call keyEvent() no key events will get to Nifty what might or might not be what you want.
5. Forward MouseEvents
   Handling mouse events are a bit trickier because they are handled through the InputSystem interface which you need to call the Nifty constructor with. But creating an implementation of the InputSystem is easy because at the moment it only consists of one method that Nifty uses to request a List of current available MouseEvents. So you’re implementation can decide when and what mouse events get through to Nifty in the InputSystem-Implementation.

The example in nifty-examples svn demonstrates how to forward MouseEvents but does not care about keyboard Events.

And that’s it! Nifty GUI playing together with others! Nifty!

void

Effect Tutorial/Introduction

It’s not completly finished yet but should give you some more informations about effects in Nifty.

Additionally we’ve removed the old Screenshots Page from the sf.net Nifty project website and enabled the much cooler gallery feature. And there is now a sf.net standard forum enabled for the Nifty project too:

Nifty Gallery at Sourceforge

Nifty Forum at Sourceforge

Have fun,
void =)

Building Nifty from Source Wiki Page

• Slick #239
• Lwjgl 2.0.1

Besides that I realized that I’ve already had setup a Nifty Maven Repository at Sourceforge. This was meant to store Nifty releases to allow other Projects that use Maven and Nifty to easily access the Nifty libs. So for instance you just need to add:

<repositories>
  <repository>
    <id>nifty-maven-repo.sourceforge.net</id>
    <url>http://nifty-gui.sourceforge.net/nifty-maven-repo</url>
  </repository>
</repositories>

to your applications pom.xml and it will automatically find the Nifty dependency So far so good.

BUT

Today I realized that I could use the same approach to get Lwjgl and Slick2D easily under Maven control. So when switching the Versions to Slick #239 und Lwjgl 2.0.1 I deployed both libs to the Nifty Maven Repo at Sourceforge!

So what does this mean for you?

It means just one thing. It’s now easier then ever to build Nifty! Just “svn co” it from Sourceforge and execute “mvn package” and it should automatically download all required libs without any changes!

Nifty!

void