wingS User Guide

If you took a look at Section 2.1, “Get ready - Writing a wingS Frame” you probably realized that the main thing the entry class does, is simply constructing a new SFrame container component (see also Section 3.3.3, “SContainer”), adding further wingS components to it and finally calling setVisible(true) on this frame. So you probably already guessed that the root of all wingS applications is a frame, constructed in the root class of your application:

public class MyWingSApp {
        public MyWingSApp() {
            SFrame rootFrame = new SFrame("Window title");
            rootFrame.getContentPane().add(...);
            // ...
            rootFrame.setVisible(true);
        }
    }

Hence you can think of SFrame as an equivalent to a window in common desktop environments like Microsoft Windows or KDE.

Equally, at a more technical level, an SFrame corresponds directly with the dynamically created HTML document that is delivered to the browser as the current view of your web application. During the lifecycle of a typical wingS application session most of the time there will exist exactly one root frame. This root frame contains all the widgets currently visible and can be retrieved at any time via the session manager:

SFrame rootFrame = SessionManager.getSession().getRootFrame();

Though in most cases every session has only exactly one instance of SFrame, there are situations where multiple frames may exist, sequentially or concurrently, during a session. This is especially the case for frameset based applications^[4] or wingS applications opening new browser windows for sub dialogs.

Besides regular, single-framed single-windowed web applications wingS offers a great feature: It can simulate Multiple Document Interface (MDI) applications. MDI applications are applications hosting multiple documents or windows inside one parent application.

In wingS this can be achieved easily using SInternalFrame inside a SDesktopPane. The desktop demo shipped with wingS demonstrates in a very impressive way how internal frames can be used to build a multi-document Editor with RSS reader and Drag & Drop support.

Please refer to the source code of the desktop demo for an example of how to use internal frames. It can be found in the demo/desktop directory of the wingS distribution.

Please note that the frameset support in wingS is currently experimental!

Using framesets is a way to separate the content displayed by the browser into two or more different and independent documents. Using framesets you can split the available space of the browser window in different sub-areas each called a Frame. In each Frame the browser displays an independent document. This corresponds exactly with the usage of the HTML frameset tag.

The following code snippet shows how to construct a new frameset split horizontally into two inner frames:

SFrameSet frameset = new SFrameSet(new SFrameSetLayout("50%,50%", null));
SFrame leftFrame = new SFrame("left frame");
SFrame rightFrame = new SFrame("right frame");
horizontal.add(leftFrame);
horizontal.add(rightFrame);
frameset.setVisible(true);

This example created two new inner frames. Each of this frame will probably contain further displayed components. As an action in one frame may influence the presentation of a component in the other frame, this would mean that on every request the whole frameset will get reloaded, i.e. both inner frames will refresh.

Avoiding unnecessary reloads with the Reload Manager

The reload manager offers a way to avoid this. To use the reload manager you will need to add an additional, invisible frame to your frameset. In contrast to the default case, only this invisible frame will be used to fire the initial request on any user action. On the server side the reload manager determines which of the inner frames contain modified components, and returns a list of the inner frames to be updated to this invisible inner frame. Hence after receiving the response the hidden reload manager frame will trigger only explicit reloads of those frames whose visual representation has changed.

For a detailed example of how to use framesets and the reload manager please refer to the frameset demo available in the demo/frameset directory of the wingS distribution.

Contrary to other web applications framework, wingS is tries to be as component oriented as possible. One main concept of component-oriented application design is that you take simple component and arrange them to more complex compound components until you built up your complete application. Hence containers are the key feature for a hierarchical component-oriented design approach. The figure below shows how you can used and nest components to a complete screen dialog.

Figure 3.1. Example of how to build complex application via nesting components

Similar to Swing the containers are only responsible for holding and managing the list of contained inner components. The layouting of the contained components inside the space taken up by the container component will be delegated to the layout manager. Refer to Section 3.7, “Layout Managers” for more information about details regarding the different layout managers.

After construction you can simply add the components which should be contained inside using one of the add(SComponent component) methods. Please note the variants of the add method allowing you to pass a Layout constraint as additional parameter. Some layout managers, such as the SBorderLayout or the STemplateLayout need additional information about where exactly you want to place the passed component inside their provided layout style, while simpler ones like the SGridLayout will just choose the next available place.

Finally you just need to attach your newly created container to the root container as shown in Section 2.1, “Get ready - Writing a wingS Frame” to make it visible to the user.

The type of container you'll probably encounter most of the times during you every-day writing of wingS application is SPanel. This is the simplest form a container and like every SContainer it will be initialized with a default layout manager (SFlowLayout, can be overridden via default.properties) but you probably will prefer to define your own layout manager.

SPanel panel = new SPanel();
SGridLayout gridLayout = new SGridLayout(2);

panel.setLayout(gridLayout);
panel.add(new SLabel("First name:"));
panel.add(new STextField());
panel.add(new SLabel("Last name:"));
panel.add(new STextField());
panel.add(new SButton("Submit"));

SForm inputForm = new SForm();
inputForm.add(panel);

In this example we created a SPanel container, assigned a two-columed grid layout as layout manager and added several components to this container. In the last step we wrapped this container inside another container: SForm.

What's the reason behind the SForm instance in the previous example? If you are aware of HTML and already designed some web pages by coding HTML code directly, you'll probably know that input elements like text fields, submit buttons, radio buttons and so on require to be surrounded by a <FORM> HTML tag.

The SForm container is the object-oriented equivalent for this HTML tag. So if you want to place input elements on your screen you must ensure that the container or one of its parent container is a SForm. Please be aware that contrary to the other containers available in wingS you are not allowed to nest SForm containers into each others! This reflects the same HTML restriction.

Typically it's sufficient if you use one SForm container on the very top of your component hierarchy. The SForm container has also a property which advises the browser to send the input via HTTP POST or HTTP GET calls.

There are some more containers available in wingS. Below you find a short summary of them including a short description of their characteristics.

The simplest way to present information to the user is by using labels. You already encountered instances of SLabel in the preceding examples so we will explain in a bit more depth the usage and capabilities of this widget component. Here are some usage examples

// You can just pass the text to display as parameter of the constructor
SLabel simpleLabel = new SLabel("A simple label");

// ...but it can be changed at any time
SLabel emptyLabel = new SLabel();
// ... i.e. when something happened:
emptyLabel.setText("The trigger event occured! \n"+
                   "Second line of label");

// Extensive formatting can be done done during runtime
SLabel fancyLabel = new SLabel("A green, bold italic label");
fancyLabel.setForeground(Color.green);
fancyLabel.setFont(new SFont(SFont.BOLD + SFont.ITALIC));
fancyLabel.setWordWrap(true); // allow word wrapping

As you can see, the text inside a label can be changed at any time using the setText() bean property setter. Using the properties declared in SComponent the font size, style, face as well as the text and background color can be easily controlled using pure Java code.

Please note that starting with version 2.0 the labels word wrapping behaviour changed to be in sync with Swing. To allow the browser to line-break a label call setWordWrap(true) on it.

Advanced usages

As in the Swing JLabel, the SLabel component in wingS also accepts HTML formatting directives like <b>...</b> or <i>...</i>inside the text if you prefix the text with an <HTML> tag. You should use this carefully to avoid mixing of view and logic.

If you assign specific styles on a regular basis to a component like a label, you should consider to declare a static new CSS style class and assign this to the label. This allows you on the one hand to modify this style globally in the style declaration, and avoids on the other hand the generation of many dynamically generated CSS styles generated by the wingS framework. Think for example of error labels you might want to have in a specific style. In your programming code you would additional assign a new CSS class to a label:

SLabel errorLabel = new SLabel();
errorLabel.setStyle(errorLabel.getStyle() + " errorLabel");
errorLabel.setVisible(false); // hide by default

//.. an error occured
errorLabel.setText("An error occured during the last operation");
errorLabel.setVisible(true);

This will allow the web designer in your project to declare a new static CSS style an optional application-specific CSS style sheet.

.errorLabel {
    color: #f00;
    font-weight: bold;
    border: 1px solid #ddd;
}

Please refer to Section 3.8, “Styling your application using CSS” for more information about using CSS to style your application in detail.

The SIcon interface is your friend if you want to include images in your wingS application. An SIcon can be an image retrieved from an arbitrary source and used in conjunction with various wingS widgets. By default wingS comes with five different implementations of icon providers, each capable of handling a different source as source for the image data to be displayed. Possible sources are

Please note an important difference between the SImageIcon and the other mentioned SIcon implementations: While the content of the others images cannot change during runtime, an ImageIcon can have an updated image content during every request. Allowing you to display any dynamically generated image this has the side-effect that wingS needs to create and send new graphic data to the browser. So to include just image files in your application ensure that you use one of the other implementations as demonstrated in the example below:

// image contained in the class path
SResourceIcon javaCupIcon = new SResourceIcon("org/wings/icons/JavaCup.gif");
// image deployed in a icons directory of you application
SURLIcon okButtonIcon = new SURLIcon("../icons/ok-button.png");
// a file in the file system
SFileIcon background = new SFileIcon(new File("/home/blueshift/background.jpg"));

// Use i.e. just for display
SLabel javaCup = new SLabel(javaCupIcon);
// ..or as clickable button
SButton okButton = new SButton(okButtonIcon);
// or i.e. as container background
panel.setBackgroundImage(background);

SIcon images can be used in conjunction with many wingS widgets. But the most commons usage are in combination with SLabel for just displaying a graphic or with SButton to create graphical buttons in your application.

Below you'll just find a list of further pure display-only widgets.

To create and display a button just create a new SButton instance and add it to a visible container. By default buttons will appear as regular buttons if they are nested inside a SForm container, otherwise they will appear as simple text links due to constraints of the browser. Please refer to Section 3.3.3.3, “The SForm container for input elements” to learn more about the role of the SForm container. You can force SButtonto render as text links even if contained inside a form using a setShowAsFormComponent(false) method call. Alternatively you can use images as clickable buttons (perhaps dynamically modified at runtime). Below you will find a few example of how to create buttons

// a simple default button
SButton simpleButton = new SButton("ok");

// text link button
SButton textLinkButton = new SButton("Request support");
textLinkButton.setShowAsFormComponent(false);

// a graphical button
SButton graphicalButton = new SButton(
        new SResourceIcon("org/wings/icons/JavaCup.gif"));

The default style of form buttons are modified in the default CSS files delivered with the wingS default PLAF. You might want to attach a new custom CSS file and modify their appearance there.

Most widgets provide various "listener" interfaces so that you can supply your own callbacks in order to handle these. Here we create a push button and register a callback to receive notification when the button is pushed. Note that the button is declared final so that we can access it within the anonymous callback class

final SButton submit = new SButton("Search");
form.add(submit);
ActionListener al = new ActionListener() {
  public void actionPerformed(ActionEvent e) {
     // ... trigger search
  }
};

submit.addActionListener(al);

In the above example the callback only receives events when the button is pushed. An alternative is to make the form the listener, since if the form is to have a "default" button (when the user hits the enter key) then it is the form which will be notified. In this case you would add the listener callback to the form instead of the button:

form.addActionListener(al);

The ActionEvent.getSourctree() will determine whether the event comes from the button or the form so you can use the following tests in your callback:

public void actionPerformed(ActionEvent e) {
  if(submit == e.getSource())
  // submit button pushed
  if(form == e.getSource())
  // user hit enter key
}

You can extract data from the text field as shown above with a call to STextField.getText().

Whenever a listener is attached to a component or its model, wingS assures, that the listener is invoked immediately after the user modifies the component. For example, if you add a DocumentListener to a textfield's document, wingS will add a form submission javascript listener (onchange) to the respective input field.

The example below demonstrates that you can restrict the number of columns independently from the physical size a text input field. Furthermore text areas can be advised to line-wrap the entered text at their physical, virtual size or not to wrap the text themselves at all (default).

// A text field restricted to 40 character and
// a fixed width of 400px
STextField simpleField = new STextField("default text");
simpleField.setMaxColumns(40);
simpleField.setPreferredSize(new SDimension(400, SDimension.AUTO_INT));

// An multilines input field with 6 lines and 40 colmns
// Line will wrap after 40 colums
STextArea textArea = new STextArea(6,40);
textArea.setLineWrap(STextArea.VIRTUAL_WRAP);

// A read only textfield
STextField readonlyField = new STextField("read only");
readonlyField.setEditable(false);

You can retrieve the entered text via the getText() method i.e. as an reaction of an "O.K." or "Save" button click as already drafted in the previous examples.

It is worth mentioning a less obvious source of event triggers - the text fields/areas themselves ! You can attach Swing-like document change listeners which will notify every value update of a text component.

textArea.addDocumentListener(new SDocumentListener() {
    public void insertUpdate(SDocumentEvent e) {
        STextComponent source = (STextComponent) e.getSource();
        System.out.println("Text after insertion of " +
                e.getLength()+" characters: "+source.getText());
    }

    public void removeUpdate(SDocumentEvent e) {
        STextComponent source = (STextComponent) e.getSource();
        System.out.println("Text after removal of " +
                e.getLength()+" characters: "+source.getText());
    }

    public void changedUpdate(SDocumentEvent e) {
        // won't happen - refers to style changes, not text changes
    }
});                                                                 

Check boxes and radio boxes are widgets that can be either selected or unselected. While check boxes can be checked and unchecked independently, radio boxes always allow only one instance to be selected within a button group.

Similar to the behaviour of SButton, their appearance differs depending on if they are contained inside a form or not. If those input elements are not contained inside a Section 3.3.3.3, “The SForm container for input elements” element, they will be rendered as graphical widgets. You can force the graphical version, as well as customising the used images for this case.

// You gotta' decide yourself for exact one gender ;-)
SButtonGroup buttonGroup = new SButtonGroup();
SRadioButton optionF = new SRadioButton("Female");
SRadioButton optionM = new SRadioButton("Male");
buttonGroup.add(optionF);
buttonGroup.add(optionM);

// a checked checkbox
SCheckBox agreedBox = new SCheckBox("accept disclaimer");
agreedBox.setSelected(true);

// an unmodifyable checkbox rendered as graphic
SCheckBox disabledCheckBox = new SCheckBox("Umodifyable checkbox");
disabledCheckBox.setEnabled(false);
disabledCheckBox.setShowAsFormComponent(false);
disabledCheckBox.setDisabledIcon(new SResourceIcon(...));

Comboboxes are one-lined item selection widgets with further options to choose via a drop-down menu. SLists have two and more lines and support multiple item selection modes^[5] additionally to the single selection mode offered also by the combobox.

// A combo box containing a coloured label and two string values
SLabel color = new SLabel(Color.green.toString());
color.setForeground(Color.green);

SComboBox comboBox = new SComboBox();
comboBox.setModel(new DefaultComboBoxModel(new Object[]{ "element1", color, "element3" }));

// A simple selection list
SList multiSelectionList = new SList();
multiSelectionList.setName("multiple");
multiSelectionList.setSelectionMode(SList.MULTIPLE_SELECTION);
multiSelectionList.setListData(new String[] {"Item 1", "Item 2", "Item 3"});

You can attach ListSelectionListener to SList instances and ItemListener to SComboBox instances to receive events on selection changes.

comboBox.addScriptListener(ComboBoxCG.JS_ON_CHANGE_SUBMIT);

Last but not least we have to mention two more special input component SFormattedTextField and SPasswordField. The latter one is simply the password entry variant of a STextField meaning that typed characters will appear obfuscated i.e. as asterix instead of being displayed plain-text.

The SFormattedTextField is a conceptual very interesting example of an AJAX based components. To work correctly you must deploy and register the DWR jar and servlet correctly as shown in WingSet example. Below you'll find a usage example

SFormattedTextField numberFormattedField =
           new SFormattedTextField(new NumberFormatter());

private static class NumberFormatter extends SAbstractFormatter {
    NumberFormat format = NumberFormat.getNumberInstance(
            SessionManager.getSession().getLocale());

    public Object stringToValue(String text) throws ParseException {
        return text == null || text.trim().length() == 0
                ? null : format.parse(text.trim());
    }

    public String valueToString(Object value) throws ParseException {
        return value == null ? "" : format.format(value);
    }
}

This component does the following: If you enter the SFormattedTextField you can enter or modify the current value of the text field. If you entered a parseable value, the value of the text field will be updated to the parsed value. Otherwise the input field will regain the input focus and be marked red to indicate an input error.

Technical background

This is realized in the following way: When you try to leave the text field, e.g. by pressing the Tab key to jump to the next input field, the text field will trigger a XML encoded request to the server in the background. There the DWR servlet takes the request and delegates it to the Java listener (here: NumberFormatter). If it succeeds the value of the text field will be updated with the formatted value returned by this. If it fails and indicates this by throwing a ParseException the cursor will be set back to the input field and it will be marked red to grab the user's attention.

Before you can present a table of data you first have to create a data provider for the table data. The used TableModel data model is actually the one declared by Swing, so the Swing tutorial might give you additional hints about implementing and using a table model.

In the example below we just create a very simple table model showing just a list of names hard coded in a static array. In typical real-life table models you would probably implement table models which operate on a list of objects and implement the getValueAt() in that way that it retrieves the according object from this list and returns an according object property value depending on the column.

// a very simple table model implementation
private static class MyTableModel extends AbstractTableModel {
    private final String[] COLUMN_NAMES = new String[]
            {"First name", "Last name", "Male"};
    private final Object[][] DATA = new Object[][] {
            new Object[] {"Michael","Bolton",Boolean.TRUE},
            new Object[] {"Samantha","Fox",Boolean.FALSE},
            new Object[] {"Eric","Clapton",Boolean.TRUE},
            new Object[] {"David","Bowie",null}
    };
    public int getRowCount() {
        return DATA.length;
    }

    public int getColumnCount() {
        return 3;
    }

    public String getColumnName(int i) {
        return COLUMN_NAMES[i];
    }

    public Object getValueAt(int row, int column) {
        return DATA[row][column];
    }
}

// .... in the main code

  // create new table instance and add to visible container
  final STable table = new STable(new MyTableModel());
  form.add(table);

Below you'll find a screenshot of the resulting visual representation

Having shown a list of data to the object we might want to allow the user to do some operations on the data show. In the first step we'll allow the user to select single rows and offer him operations on them like e.g. deletion. Modifying the table to accept row selections is just as simple as

// allow single-line selection in table
table.setSelectionMode(STable.SINGLE_SELECTION);

After this statement you can select rows just by clicking the numbers in the first column. Now we also add a delete button and a status label telling us about the this event

// create a status label and a delete button
final SLabel statusLabel = new SLabel();
final SButton deleteButton = new SButton("Delete selected row");
deleteButton.addActionListener(new ActionListener() {
    public void actionPerformed(ActionEvent actionEvent) {
        statusLabel.setText("Currently selected row: "+table.getSelectedRow());
        // business logic for operation
    }
});
// add them
form.add(statusLabel);
form.add(deleteButton);

So each time we click on the new presented delete button a status label will be updated telling us the index of the currently selected row. If no row has been selected then we will receive -1 as value. As well as single row selections, tables can also allow selection of continuous intervals (STable.SINGLE_INTERVAL_SELECTION) or discontinuous intervals (STable.MULTIPLE_INTERVAL_SELECTION). According to Swing the SListSelectionModel allows you to retrieve the necessary information about the selected rows via getMin/MaxSelectionIndex() methods for the continuous case, and an isSelectedIndex(int rownum) for the discontinuous case.

The comfortable way: Get notified about selections

Besides explicitly asking the table's selection model about the current selected rows, we can also use a ListSelectionListener to get notified via explicits events when the selection changes. The code below will update the status label every time the selection changes.

table.addSelectionListener(new ListSelectionListener() {
     public void valueChanged(ListSelectionEvent listSelectionEvent) {
           statusLabel.setText("Selection changed to: "+table.getSelectedRow());
     }
});

But now we want allow the user to be able to edit the table content. This is quite easy in our simple demo. We have to modify the implementation of the table model so that it tells the table which cells are editable. In our case we just allow all cells to be editable. Furthermore we must overwrite the empty default implementation of the setValueAt() method in AbstractTableModel to accept and store the changed data. Last but not least the getColumnClass() returns the class type of the column values so that the framework knows to choose the right cell editor for the value type. Adding the few lines below to MyTableModel do this job

public boolean isCellEditable(int row, int column) {
    return true; // allow for all cells
}

public void setValueAt(Object object, int row, int column) {
    DATA[row][column] = object; // just take the canged value
}

public Class getColumnClass(int column) {
    return column == 2 ? Boolean.class : String.class;
}

And below you see the final outcome of our efforts

Until now the creation of our table was really painless. As we did not override them, the table uses the default cell renderer and editors for rendering the cell contents and providing the appropriate components for editing a cell value. In our simple case this is absolutely fine as we have very simple data types.

3.4.1.4.1. Custom table cell renderer

But look at the last column. Wouldn't it be better to display this boolean value as checkable check box instead of the toString() representation of the boolean values? This can be easily achieved by overwriting the default cell renderer to return a accordingly checked SCheckBox instead of the default creating cell renderer implementation which just renders a SLabel with the cell content toString() value.

private static class MyCellRenderer extends SDefaultTableCellRenderer {
    private final SCheckBox checkBox = new SCheckBox();

    public MyCellRenderer() {
        // set icon to indicate editable, empty cells
        setEditIcon(getSession().getCGManager().getIcon("TableCG.editIcon"));
        // render always as graphic icon
        checkBox.setShowAsFormComponent(false);
    }

    public SComponent getTableCellRendererComponent(
            STable table, Object value, boolean selected, int row, int col) {
        if (value instanceof Boolean && row != -1) {
            checkBox.setSelected(((Boolean)value).booleanValue());
            return checkBox;
        }
        else
            return super.getTableCellRendererComponent(table, value, selected, row, col);
    }
}

After implementing our own, extended table cell renderer we just have to assign it to our table and we're done.

table.setDefaultRenderer(new MyCellRenderer());

See the result

Beware that the checkbox is readonly. Clicking it will not update the table model. Making cells editable is the job of a cell editor. Look at the wingSet Table example and XTable example to learn more about editable tables.

3.4.1.4.2. Customizing the table

Further customization can be applied to tables. Many tables contain a large count of data rows which result in large table size. In this case it is a good idea to make the table scrollable. Please refer to Section 3.4.3, “SScrollPane” for details how this can be done.

As already demonstrated the cell renderers can be exchanged as a whole or for specific column classes. If necessary you can exchange the cell editors in the same way as demonstrated for the cell renderers.

STable also allows to exchange the renderer component for the header cells as well to turn the display of the header cell.

The visibility of the horizontal and vertical separator lines can be easily modified using the setShowHorizontalLines() and setShowVerticalLines() methods of STable.

The spacing and padding between the table cells can be modified with the setIntercellPadding() and setIntercellSpacing() methods.

Colouring

Extensive adjusting of the table colours is possible. The recommended way is to add a custom static CSS style overwriting the wingS default styles for tables. Look at Section 3.8, “Styling your application using CSS” for details. As alternative there exists also the convenient possibility to all the styling via the Java API and the CSS Pseudo selector objects provided by STable. Just look at the example below

// Really fancy and colourful table
table.setAttribute(STable.SELECTOR_HEADER, CSSProperty.BACKGROUND, Color.blue);
table.setAttribute(STable.SELECTOR_NUMBERING_COLUMN, CSSProperty.BACKGROUND, Color.gray);
table.setAttribute(STable.SELECTOR_ODD_ROWS, CSSProperty.BACKGROUND, Color.orange);
table.setAttribute(STable.SELECTOR_EVEN_ROWS, CSSProperty.BACKGROUND, Color.magenta);
// Special marking as !important necessary due to existing !imporant declaration
// in wingS default styles. Might be obsolete already
table.setAttribute(STable.SELECTOR_SELECTION, CSSProperty.BACKGROUND,
        CSSStyleSheet.getAttribute(Color.yellow)+ " !important");

... and here is the result

Similarly to the STable component, the STree component stores its data in a separate model. Therefore it uses the Swing TreeModel for retrieving the data presented in the tree and a STreeSelectionModel object to store the currently selected items.

TreeModel is an interface of Swing declaring methods to retrieve a root object of a logical tree of objects, as well as methods to retrieve the child objects of these node objects. Typical node objects are instances of the TreeNode interface. In most cases you'll just deal with the default implementations of these interfaces provided by Swing: DefaultTreeModel and DefaultMutableTreeNode.

So let's look at a very simple example tree model constructed using these default implementations:

// Create a root node
DefaultMutableTreeNode root = new DefaultMutableTreeNode("STree");
DefaultMutableTreeNode parent;

// Add first child node with more sub nodes
parent = new DefaultMutableTreeNode("colors");
root.add(parent);
parent.add(new DefaultMutableTreeNode("blue"));
parent.add(new DefaultMutableTreeNode("violet"));
parent.add(new DefaultMutableTreeNode("red"));
parent.add(new DefaultMutableTreeNode("yellow"));

// ... second child node ...
parent = new DefaultMutableTreeNode("sports");
root.add(parent);
parent.add(new DefaultMutableTreeNode("basketball"));
parent.add(new DefaultMutableTreeNode("soccer"));
parent.add(new DefaultMutableTreeNode("football"));
parent.add(new DefaultMutableTreeNode("hockey"));

// ... and third and last root child node
parent = new DefaultMutableTreeNode("food");
root.add(parent);
parent.add(new DefaultMutableTreeNode("hot dogs"));
parent.add(new DefaultMutableTreeNode("pizza"));
parent.add(new DefaultMutableTreeNode("ravioli"));
parent.add(new DefaultMutableTreeNode("bananas"));

Note that in this example we used simple String object as data model objects for each node. But you can use any custom object type as data model objects but you should ensure that the used STreeCellRenderer is capable of rendering them nicely.

With creation of our tree model much is already done. Just wrap this tree model in a new instance of a STree component, and you receive an expandable visual tree with selectable nodes.

STree tree = new STree(treeModel);
form.add(tree);

final SLabel treeEvent = new SLabel();
form.add(treeEvent);
tree.addTreeSelectionListener(new TreeSelectionListener() {
    public void valueChanged(TreeSelectionEvent treeSelectionEvent) {
        TreePath path = treeSelectionEvent.getPath();
        String action = treeSelectionEvent.isAddedPath() ? "Added " : "Removed ";
        treeEvent.setText(action + path.getLastPathComponent().toString());
    }
});