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());
    }
});

The border layout is quite similar to the Swing version of the border layout. Contrary to the other dynamic layout managers, it offers only a limited number of five layout positions which can be used to place exactly one component in each. These positions are named North, South, East, West and Center and must be specified as layout constraints on adding components to a border layout.

The border layout tries to take up the full space of the surrounding container component if the owning container has no preferred size defined. As in Swing the Center position is preferred in taking up remaining space, while East and West try to be as narrow, North and South as flat as possible.

The implementation of the border layout tries to achieve the desired layout using an invisible HTML table. Optionally you can define horizontal or vertical spacings between the different sections. Find a commented example usage in the code snippet below

// Example usage of a border layout
SBorderLayout borderLayout = new SBorderLayout();
SPanel borderLayoutPanel = new SPanel(borderLayout);
borderLayoutPanel.add(new SLabel("Center"), SBorderLayout.CENTER);
borderLayoutPanel.add(new SLabel("Top"), SBorderLayout.NORTH);
// add a right-aligned component in the EAST section
SLabel rightLabel = new SLabel("Right");
rightLabel.setHorizontalAlignment(SConstants.RIGHT_ALIGN);
borderLayoutPanel.add(rightLabel, SBorderLayout.EAST);

// Demonstration of additional capabilities of SBorderLayout:
//  o Define horizontal/vertical spacings
borderLayout.setHgap(10); // pixels
//  o Draw borders around sections. Invisible by default
borderLayout.setBorder(1); // pixels

The box layout it a very simple layout allowing to take an arbitrary number of components. It simply arranges the contained components either in a row or in a column. Similar to the border layout this is achieved using an invisible HTML table, so a horizontal/vertical spacing can be optionally defined as well as the option to draw a border around the different boxes.

The box layout does not wrap in either horizontal or vertical direction. If you want your components to wrap to the next line if the space is not sufficient you might take a look at Section 3.7.1.4, “SFlowLayout and SFlowDownLayout”. Here is a short code snippet to demonstrate the usage of the box layout in wingS

// Align components in a line
SBoxLayout horizontalLayout = new SBoxLayout(SBoxLayout.HORIZONTAL);
horizontalLayout.setHgap(10); // spacing of 10px between components
horizontalLayout.setBorder(1); // show borders around boxes
SPanel panel1 = new SPanel(horizontalLayout);
panel1.add(new SLabel("Horizontal box layout with padding & border"));
panel.add(new SLabel("Next column"));

// Very simple default usage
SPanel panel2 = new SPanel(new SBoxLayout(SBoxLayout.VERTICAL));
panel2.add(new SLabel("Component 1"));
panel2.add(new SLabel("Component 2"));

The grid layout is some sort of a combined vertical and horizontal box layout. It takes a column count as argument in the constructor and will line break when the maximum column count has been reached.

Similar to the preceding layout it is implemented using an invisible layout table. Border and spacing can be defined in the same manner as demonstrated before.

// A 3-columned grid layout
SPanel gridPanel = new SPanel(new SBoxLayout(SBoxLayout.VERTICAL));
gridPanel.add(new SLabel("Component 1"));
gridPanel.add(new SLabel("Component 2"));
gridPanel.add(new SLabel("Component 3"));
gridPanel.add(new SLabel("Component 4"));
// ...

A special property renderFirstLineAsHeader allows you to render the first line of the invisible HTML table with <TH> elements versus the default <TD> elements. This might be useful if you want to apply special CSS styles to the first row in these layouts.

The flow layout come in the two flavours of SFlowLayout and SFlowDownLayout. Due to browser limitations SFlowDownLayout is in wingS actually semantically the same as a vertical box layout (we can't flow vertically in web browsers). But the SFlowLayout might be an interesting alternative to your for a horizontal box layout if you don't know the horizontal space available to a container but nevertheless want to utilise it as best as possible without imposing horizontal scrollbars if the components don't fit in a row.

Actually the flow layout advises the browser to flow every of its contained components. This means that the browser should start a new row if a component doesn't fit into the previous row anymore. Just look at the WingSet demo section Dynamic Layouts. Choose SFlowLayout in the drop down box and look how the layouted components behave on resizing your browser window.

The usage is as simple as it could be

// A horizontal flowing layout
SPanel flowPanel = new SPanel(new SFlowLayout());
flowPanel.add(new SLabel("Component 1"));
flowPanel.add(new SLabel("Component 2"));
flowPanel.add(new SLabel("Component 3"));
// ...

The flow layout follows the alignment of the previous layout for horizontal and vertical spacing. Hence you can also apply a horizontal alignment to the layout. Why this? Actually the flow layout only takes up the width it requires. So the horizontal alignment of components affects the alignment inside this taken up width. In contrast the alignment defined in the flow layout instance itself affects the horizontal alignment of this composite in the parent container. Take a look at WingSet if you didn't get it already.

Caveats

Please be aware that this layout might act somewhat surprisingly regarding the preferred sized of contained or surrounded components, and when in combination with table based layouts.

Suppose you put a component with a preferred size of 100% inside a flow layout you'll notice that your components won't flow anymore. This is just because in this case the sized component will adapt the available width rather than the flow layout being able to know that it should use the available space. A similar effect can happen on put a flow layout managed container together with other components inside a parent container. Some components will take up a minimum width though it may visibility not be apparent.

So just in case you encounter problems with non-flowing flow layouts try to play with the preferred sizes of the surrounding or contained components as well as the nesting of your containers. Advanced users may use the techniques described in Section 3.8.5, “CSS live editing” together with a peek into the generated HTML sources to debug the responsible components or size disabling the flowing more effectively.

The gridbag layout is the most powerful dynamic layout manager available in wingS. Similar to SGridLayout the SGridBagLayout allows to align components in a tabular manner but offers many more options to influence the structure of the generated (invisible) layout table. Namely these options are

Actually this layout managers can be used in so many different ways that we won't describe them in detail but present some commented usage examples. Please refer to the WingSet demo or the documentation of the Swing variant for an in-depth explanation of it usage.

The code below is the code for the first grid in the screen shot above

// Vertical adding using pre-defined gridx
SGridBagLayout layout = new SGridBagLayout();
layout.setBorder(1); // to show grid structure
SPanel gridBagPanel = new SPanel(layout);

GridBagConstraints c = new GridBagConstraints();
c.gridx = 0;
c.gridheight = GridBagConstraints.REMAINDER;
gridBagPanel.add(new SLabel("1"), c);
c.gridheight = 1;

c.gridx = 1;
gridBagPanel.add(new SLabel("2"), c);
c.gridheight = GridBagConstraints.REMAINDER;
gridBagPanel.add(new SLabel("3"), c);
c.gridheight = 1;

c.gridx = 2;
gridBagPanel.add(new SLabel("4"), c);
gridBagPanel.add(new SLabel("5"), c);
c.gridheight = GridBagConstraints.REMAINDER;
gridBagPanel.add(new SLabel("6"), c);
c.gridheight = 1;

c.gridx = 3;
gridBagPanel.add(new SLabel("7"), c);
gridBagPanel.add(new SLabel("8"), c);
gridBagPanel.add(new SLabel("9"), c);
c.gridheight = GridBagConstraints.REMAINDER;
gridBagPanel.add(new SLabel("10"), c);

The SCardLayout is again a very simple layout manager nearly identical with the according Swing variant java.awt.CardLayout. It can be understood as a deck of 'cards' with exactly one 'card' visible at once. So you just add your various components to components to a card layout and from the start it will just show the first added one. Using special show(), next() and previous() methods you can 'flip' to another card during runtime.

So actually naming this manager a layout manager is somehow exaggerated as the only thing it does is to ensure that only component in the 'card deck' is visible at one time. Anyhow this layout might be useful if you have a set of different dialogue components you alternately want to present to the user without the need to add and remove them from an empty container. Again you'll find for illustrational purpose a few example code lines below

// A card deck layout
SCardLayout cardLayout = new SCardLayout();
SPanel stackedPanel = new SPanel(cardLayout);
SLabel label1 = new SLabel("Component 1");
stackedPanel.add(label1);
stackedPanel.add(new SLabel("Component 2"));
stackedPanel.add(new SLabel("Component 3"), "layoutconstraint3");

// select visible 'card' by passing specific object instance
cardLayout.show(label1);

// ... or select shown card using the layout constraint
cardLayout.show("layoutconstraint3");

// or flip to next, previous, first or last card
cardLayout.next(stackedPanel);
cardLayout.previous(stackedPanel);
cardLayout.first(stackedPanel);
cardLayout.last(stackedPanel);

Besides this simple inlining mechanism the STemplateLayout manager has also another very powerful feature - specific components bean attributes can be overwritten by specific optional inline attributes attached to your object HTML tags e.g. <object name="compname" background="#ff0000" text="new text"></object>

This feature can be very useful if a web developer is solely responsible for the whole application Look & Feel. Depending on the type of the arranged component they can modify different visual properties (background color, display text, etc.) just by modifying the template file. For example let us assume you are placing the label object from the previous example in your template file. The web designer can overwrite the component's background, display text, etc. by modifying the object inclusion tag to <object name="aConstraintName" background="#ff0000" text="new text"></object>

Please refer to the JavaDoc of the PropertyManager interface and its implementors to find out which properties are supported for which classes.

Just for the sake of completeness we need to mention SRootLayout here. Actually it is a derived variant of STemplateLayout which actually expects only one component named content. By default it uses a very simple default template file template/default.thtml which is provided in the default libraries with wingS. Use this layout for a quickstart of the layout of the root frame of your application if you intend to replace it later on with a more complex STemplateLayout based layout.

Section 3.7.2.1, “Setting component properties via the template” showed you already how you can set specific component properties via special attributes on the <OBJECT> tag in you template files. Additionally you can define Java code fragments in your template file. Just add an attribute SCRIPT on the OBJECT tag with the desired, arbitrary Java code parseable by bean shell^[6]. For security reasons bean scripting support is disabled by default and you have to enable it explicitly by setting a property in your web.xml

        <init-param>
            <param-name>wings.template.beanscript</param-name>
            <param-value>TRUE</param-value>
            <description>Enables bean scripting in templates files</description>
        </init-param>

After you enabled it, you can use the SCRIPT attribute in your template files on the OBJECT tags. The DefaultPropertyManager initializes the bean scripting environment with two variables: component is the inline wingS SComponent and session holds the current wingS Session object. Just look at the example template file fragment below

<object name="theLabel" foreground="#990000"
 script='component.setText("Value set via template: "+new java.util.Date());'></object>