SWT and JFace, Part 1: A gentle introduction

Basic Controls

Almost all SWT GUIs are created out of a few basic parts. All SWT widgets are found in the org.eclipse.swt.widgets or org.eclipse.swt.custom packages. (Some Eclipse plug-ins also supply custom widgets in other packages.) The widgets package contains controls based on the operating system controls, while the custom package contains controls that extend beyond the operation system control set. Some custom package controls are similar to controls in the widgets package. To avoid name collision, the custom control names starts with "C" (CLabel vs. Label).

In SWT, all controls (except for top-level controls like shells, to be discussed later) must have a parent control (a composite instance) at creation time. Controls are automatically "added" to the parent upon creation, unlike in AWT/Swing where they must be explicitly added, resulting in a "top-down" approach to GUI construction. Thus, all controls take a composite parent (or a sub-class) as an argument to the constructor.

Most controls have flag options that must be set when created. Thus, most controls also have a second constructor argument, often called style, that provides flags to set these options. All the flag values are static final ints and are defined in the SWT class in the org.eclipse.swt package. If no options are needed, use the SWT.NONE value.

Labels

Perhaps the simplest control, a label is used to display plain (with no color or special fonts or styles) text or a small image called an icon. Labels do not receive focus (in other words, a user cannot move to the label with the Tab key or a mouse) and, thus, do not generate input events.

Listing 1 shows how to create a simple text label.

Listing 1. Create a label with text

import org.eclipse.swt.widgets.*;
:
Composite parent = ...;
:
// create a center aligned label
Label label = new Label(parent, SWT.CENTER);
label.setText("This is the label text");

Notice that the text is set in a separate method from the constructor. This is typical of all SWT controls. Only the parent and style are set in the constructor; all other properties are set on the created object.

Due to platform limitation standard label controls cannot have text and an icon. To support both of these together, use the CLabel control as shown in Listing 2.

Listing 2. Create a label with text and image

import com.eclipse.swt.graphics.*;
import org.eclipse.swt.widgets.*;
import org.eclipse.swt.custom.*;
:
Composite parent = ...;
Image image = ...;
:
// create a left aligned label with an icon
CLabel Clabel = new CLabel(parent, SWT.LEFT);
label.setText("This is the imaged label text"");
label.setImage(image);

Texts

While labels show text, often, you want to allow users to input text. The text control is used to do this. Text can be single-line (a text field) or multiline (a text area). Text can also be read-only. Text fields have no description; thus, they are often proceeded by a label control to identify their purpose. The text control can also have a "tool tip" that can provide information about its use (all controls support this feature).

Listing 3 shows how to create a simple text field with a limit on the number of characters allowed. The default text is selected to allow easy erasure.

Listing 3. Create a text with selected default text and a limit

import org.eclipse.swt.widgets.*;
:
Composite parent = ...;
:
// create a text field
Text name = new Text(parent, SWT.SINGLE);
name.setText("<none>");
name.setTextLimit(50);
name.setToolTipText("Enter your name -- Last, First");
name.selectAll(); // enable fast erase

Buttons

Often, you want the user to indicate when an action should occur. The most common way to do this is via the button control. There are several styles of buttons:

  • ARROW -- Shows as an arrow in up, down, left, or right directions
  • CHECK -- A labeled check mark
  • FLAT -- A push button without a raised appearance
  • PUSH -- A momentary push button (most common event source)
  • RADIO -- A sticky mark that is exclusive with all other radio buttons in the same group
  • TOGGLE -- A sticky push button

Listing 4 creates a "Clear" push button:

Listing 4. Create a button

import org.eclipse.swt.widgets.*;
:
Composite parent = ...;
:
// create a push button
Button clear = new Button(parent, SWT.PUSH);
clear.setText("Clea&r");

The & in the name causes an accelerator to be created using the next character that allows the button to be pushed by a Ctrl+<letter> sequence (the control sequence is host operating system-dependent).

Event listeners

Often, you want to do some action when a button (especially one of the push types) is selected. You do this by adding a SelectionListener (in the org.eclipse.swt.events package) to the button. When the button state is changed (often by being pushed), the event will be generated. Listing 5 prints a message when the Clear button is clicked.

Listing 5. Button event handler

import org.eclipse.swt.events.*;
:
// Clear button pressed event handler
clear.addSelectionListener(new SelectionListener() {
public void widgetSelected(selectionEvent e) {
System.out.println("Clear pressed!");
}
public void widgetDefaultSelected(selectionEvent e) {
widgetSelected(e);
}
});

This code uses an anonymous inner class, but you may also use named inner classes or independent classes as listeners. Most ...Listener classes that contain two or more methods also have a parallel ...Adapter class that provide empty implementations of the methods and can reduce the amount of code you need to write. For example, there is also a SelectionAdapter class that implements SelectionListener.

Note that the action taken in these methods must happen quickly (generally, sub-second) or the GUI will be unresponsive. Longer actions, such as doing file access, require separate threads, but that is the subject of a future installment.

You might also like...

Comments

Contribute

Why not write for us? Or you could submit an event or a user group in your area. Alternatively just tell us what you think!

Our tools

We've got automatic conversion tools to convert C# to VB.NET, VB.NET to C#. Also you can compress javascript and compress css and generate sql connection strings.

“There's no test like production” - Anon