Working With The GUI Builder

Important

This section refers to the "old" GUI builder. Codename One is in the process of replacing the GUI builder with a new version that uses a radically different architecture. We recommend migrating to the new GUI builder and don’t recommend starting new projects with this tool. We are leaving this section for reference at this time

Basic Concepts

The basic premise is this: the designer creates a UI version and names GUI components. It can create commands as well, including navigation commands (exit, minimize). It can also define a long running command, which will, by default, trigger a thread to execute.

All UI elements can be loaded using the UIBuilder class. Why not just use the Resources API?

Since the Resources class is essential for using Codename One, adding the UIBuilder as an import would cause any application (even those that don’t use the UIBuilder) to increase in size! We don’t want people who aren’t using the feature to pay the penalty for its existence!

The UIBuilder is designed for use as a state machine, carrying out the current state of the application, so when any event occurs a subclass of the UIBuilder can just process it. The simplest way and most robust way for changes is to use the Codename One Designer to generate some code for you (yes, we know it’s not a code generation tool, but there is a hack).

When using a GUI builder project, it will constantly regenerate the state machine base class, which is a UIBuilder subclass containing most of what you need.

Warning

The trick is not to touch that code! DO NOT CHANGE THAT CODE!

Sure, you can change it and everything will be just fine, however if you make changes to the GUI, regenerating that file will obviously lose all those changes, which is not something you want!

To solve it, you need to write your code within the State machine class, which is a subclass of the state machine base class, and just override the appropriate methods. Then, when the UI changes, the GUI builder just safely overwrites the base class, since you didn’t change anything there.

Using Lists In The GUI Builder

The Codename One GUI builder provides several simplifications to the concepts outlined below, you can build all portions of the list through the GUI builder, or build portions of them using code if you so desire.

This is a step-by-step guide with explanations on how to achieve this. Again, you might prefer using the MultiList component mentioned below, which is even easier to use.

Start by creating a new GUI form, set its scrollable Y to false, and set its layout to border layout.

Figure 1. Set border layout

Next, drag a list into the center of the layout and you should now have a functioning basic list with 3 items.

Figure 2. Drag list onto form

Next, we will create the Renderer, which indicates how an individual item in the list appears, start by pressing the Add New GUI Element button and select the “Blank Container” option! Fill the name as “MyRenderer” or anything like that.

Figure 3. Set list renderer

Within the renderer you can drag any component you would like to appear, labels, checkboxes, etc. You can nest them in containers and layouts as you desire. Give them names that are representative of what you are trying to accomplish, e.g. firstName, selected, etc.

Figure 4. Add to renderer

You can now go back to the list, select it and click the Renderer property in order to select the render container you created previously, resulting in something like this.

Figure 5. Preview list

You’ll notice that the data doesn’t match the original content of the list, that is because the list contains strings instead of Hashtables. To fix this we must edit the list data.

You can place your own data in the list using the GUI builder, which is generally desired regardless of what you end up doing, since this allows you to preview your design in the GUI builder.

If you wish to populate your list from code, just click the events tab and press the ListModel button, you can fill up the model with an array of Hashtables, as we will explain soon enough (you can read more about the list model below).

To populate the list via the GUI builder, click the properties of the list, and within them, click the ListItems entry. The entries within can be Strings or Hashtables, however in order to be customizable in the rendering stage, we will need them all to be Hashtables. Remove all the current entries and add a new entry:

Figure 6. Add to list

After adding two entries as such:

Figure 7. Add items to list

We now have a customized list that’s adapted to its renderer.