A gentle introduction to SWT and JFace, Part 1: How to create a simple SWT application

And create simple SWT GUIs using basic controls and layouts

Barry Feigenbaum, Programming Advisor, IBM, Software Group

Barry Feigenbaum is a member of the IBM Worldwide Accessibility Center, where he serves as a member of a team that helps IBM make its products accessible to people with disabilities. He has published several books and articles, holds several patents, and has spoken at industry conferences such as JavaOne. He has served as an adjunct assistant professor of computer science at the University of Texas, Austin, and other schools.

Summary: In this first article of "A gentle introduction to SWT and JFace," find out how to create a simple Standard Widget Toolkit (SWT) application using Java™, Eclipse, and the SWT and JFace libraries. Also learn how to create simple SWT GUIs using basic controls and layouts.

View more content in this series

Tag this!

Date: 16 Dec 2004 (Published 03 May 2005)
Level: Introductory
Activity: 4875 views

The Standard Widget Toolkit (SWT) and JFace libraries are used to develop graphical user interfaces (GUIs) for the Eclipse environment, and also to develop stand-alone GUI native applications. In this article, I introduce some of the basic SWT (the name for the basic GUI object) types and show how to combine them to create a working application.

About Eclipse, SWT, and JFace

About this series

This "A gentle introduction to SWT and JFace" series includes basic articles on developing applications using the Standard Widget Toolkit (SWT) and JFace libraries that come with the base Eclipse software development kit. This series concentrates on using SWT and JFace for stand-alone applications. However, most of what you learn will apply to using them inside the Eclipse workbench.

We will start out with simple GUIs that have limited function and progress toward useful applications. We will introduce most of the standard and custom SWT widgets and many JFace features. Our discussion will include at least one example use of the technology.

This series assumes that you are familiar with the Java programming language and Java technology-based development, and have some understanding of the Java AWT or Swing GUI tool kits.

As noted on the Eclipse Web site, Eclipse is a kind of universal tool platform. It's an open, extensible IDE for anything and nothing in particular, and provides tool developers with flexibility and control over their software technologies.

Eclipse provides a base for developers to produce rich GUI-driven tools and applications. Fundamental to this capability are the Eclipse GUI libraries SWT and JFace.

SWT is a library that creates a Java view of the native host operating system GUI controls. It is host implementation-dependent. This means SWT-based applications have several key characteristics:

They look, act, and perform like "native" applications.
The widgets provided reflect the widgets (the components and controls) provided on the host operating system.
Any special behavior of the host GUI libraries is reflected in SWT GUIs.

These goals make SWT different from Java technology's Swing, which was designed to hide operating system differences.

The SWT library reflects the basic widgets of the host operating system. In many circumstances, this approach is too low-level. The JFace library helps by adding many services to SWT applications. JFace does not hide SWT; it just extends it. As you will see later in this series, one of its most important extensions is to isolate the application's data model from the GUI that displays and changes it.

Before we begin, I need to introduce some SWT terminology:

Widget — The basic SWT GUI component (like Component in Java AWT and JComponent in Swing). Widget is an abstract class.
Control — A widget that has an operating system peer (in other words, has an identity in the operating system). Control is an abstract class.
Composite — A control that can contain other controls (like Container in Java AWT and JPanel in Swing).
Item — A widget contained by other controls (that may not be composites), such as a list or a table. Note that controls that contain items rarely also contain controls and vice-versa. Item is an abstract class.

Installing SWT and JFace

See Resources to find the Eclipse Web site. To install Eclipse and make the SWT libraries available for use in your programs:

From the Eclipse home page select Downloads, then select the desired Eclipse version for your platform. Download the associated zip file.
Expand the ZIP into a top-level directory (I suggest a name like "EclipseX.Y.Z" where X, Y, and Z are the Eclipse version you selected).
Use the DIR command or Search to find the swt.jar file and place it on your CLASSPATH (or use it on your java -cp command).
Also find all the SWT-*.DLL files and make sure they are accessible (put the directory they are in on the PATH or copy the DLL files into a directory already on the PATH).

Similar steps are needed for other platforms.

These widgets are arranged in an inheritance hierarchy. See figures 1, 2, and 3 to see how this is done. In Figure 2, the Basic1 class is the class from this article; all the other classes are standard SWT widgets.

Figure 1. SWT Widget Tree

Figure 2. SWT Composite Tree

Figure 3. SWT Item List

Note that although Eclipse is cross-platform (in that it runs on many operating systems), this article is based on the Microsoft® Windows® version of Eclipse. Even so, every example included in this article should work unchanged on other platforms. Also note that this article is based on Eclipse V3.0. Eclipse V3.1 adds a few GUI widget types and features.

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.

Composites

So far, we have been talking about individual controls. In most GUIs, multiple controls are grouped together to provide a rich user experience. In SWT, this grouping is implemented by using the Composite class.

Composites can be nested to any level, and can mix and match controls and composites as children. This can greatly reduce GUI development complexity and create opportunities for GUI code reuse (by encapsulating the inner GUI). Composites can have borders and be easily distinguished visually or can be borderless and seamlessly integrate into even larger groups.

Listing 6 creates a bordered composite.

Listing 6. Create a bordered composite


import org.eclipse.swt.widgets.*;
 :
Composite parent = ...;
 :
Composite border = new Composite(parent, SWT.BORDER);

In addition to a border, the Group composite sub-class supports a title. Groups are often used to contain radio-type buttons as they define the set of exclusive buttons.

Listing 7 creates a bordered group.

Listing 7. Create a bordered group


import org.eclipse.swt.widgets.*;
 :
Composite parent = ...;
 :
Group border = new Group(parent, SWT.SHADOW_OUT);
border.setText("Group Description");

Shells

A shell is a top-level composite (frame or window) that may have no parent composite; instead, it has a Display as a parent, often set by default. Shells come in many styles, but the most popular are SWT.SHELL_TRIM or SWT.DIALOG_TRIM. Shells may be modal or modeless. Modal shells, which are most often used for dialogs, prevent the parent GUI (if any) from proceeding until the child shell is closed.

Listing 8 creates a top-level nonmodal shell in frame style.

Listing 8. Create a top-level shell


import org.eclipse.swt.widgets.*;
 :
Shell frame = new Shell(SWT.SHELL_TRIM);
 :

Shells can have child shells. These are independent desktop windows associated with the parent shell (i.e., if the parent is closed, all of its children will also be closed).

Listing 9 creates a child shell in dialog style.

Listing 9. Create a dialog shell


:
Shell dialog = new Shell(frame, SWT.DIALOG_TRIM);
 :

See Figure 4 shell with SWT.SHELL_TRIM and Figure 5 shell with SWT.DIALOG_TRIM to see how these values affect the shell trim.

Figure 4. Shell with SWT.SHELL_TRIM
SWT shell with shell trim

Figure 5. Shell with SWT.DIALOG_TRIM
SWT shell with dialog trim

Layout managers

Composites often contain more than one control. These controls can be arranged in two ways:

Absolute positioning — Each control is set to an explicit X and Y position, and a certain width and height by your code.
Managed positioning — Each control's X, Y, width, and height is set by a LayoutManager.

In most situations, you would choose to use LayoutManagers, as they make adjusting to variable-size GUIs much easier. SWT provides several layout managers for you to use; in this installment, we will talk about two of the more basic ones: FillLayout and GridLayout. In both cases, positioning takes place whenever the containing composite is resized.

Layout managers are uniquely assigned to a composite. Some layout managers are controlled by parameters just on themselves, and others also require additional parameters, LayoutData, specified on each control in the composite they manage.

FillLayout

FillLayout arranges controls in a row or a column. Each control is sized to be as wide or tall as needed to fill the composite, and space is divided evenly among the controls. A special case is when there is only one child control, in which case the control is sized to fill the entire parent composite.

Listing 10 creates a composite using a column FillLayout.

Listing 10. Create a column of controls using FillLayout


import org.eclipse.swt.widgets.*;
import org.eclipse.swt.layouts.*;
 :
Composite composite = ...;
FillLayout fillLayout = new FillLayout(SWT.VERTICAL);
composite.setLayout(fillLayout);

GridLayout

GridLayout offers a more powerful layout approach that resembles using HTML tables. It creates a 2-D grid of cells. Controls can be placed in one or more cells (called cell spanning). Cells can be made equal size or be given varying percentage of the grid's width or height. Controls are added to the next available column in a row; if no more columns exist in the row, the control moves to the first column of the next row.

Listing 11 creates a composite of two rows and two columns containing two labeled text fields. The columns can have different widths.

Listing 11. Create a table of controls


import org.eclipse.swt.widgets.*;
import org.eclipse.swt.layouts.*;
 :
Composite composite = ...;
GridLayout gridLayout = new GridLayout(2, false);
composite.setLayout(gridLayout);
Label l1 = new Label(composite, SWT.LEFT);
l1.settext("First Name: ");
Text first = new Text(composite, SWT.SINGLE);
Label l1 = new Label(composite, SWT.LEFT);
l2.setText("Last Name: ");
Text last = new Text(composite, SWT.SINGLE);

GridData

Consider the case where you need to specify how each control uses excess space within its cell. To provide this type of refined control for each cell, the controls added to a GridLayout managed composite can have instances of GridData (a LayoutData sub-class).

Listing 12 sets the text fields to take any excess available space (based on the prior listing).

Listing 12. Configure a layout that expands to all available space


first.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, true));
last.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, true));

Building a running program

Now it is time to see all of the SWT controls we have discussed come together in a simple executable example: Basic1. See Download for the complete source of this application.

SWT GUIs require a configured environment to run in. This environment is provided by a display instance, which provides access to the host operating system display device. The display allows you to process each user input (mouse or keyboard) to drive your GUI.

Listing 13 creates the environment, creates a GUI, then displays it.

Listing 13. Create and launch a GUI application


import org.eclipse.swt.widgets.*;
 :
Display display = new Display();
Shell shell = new Shell(display);
shell.setText("Shell Title");

// *** construct Shell children here ***

shell.open();       // open shell for user access

// process all user input events
while(!shell.isDisposed()) {
   // process the next event, wait when none available
   if(!display.readAndDispatch()) {
       display.sleep();
   }
}
display.dispose();  // must always clean up

This code creates a window similar to Figure 6.

Figure 6. Example Application
SWT application

Conclusion

In this first installment of A gentle introduction to SWT and JFace, I have introduced the most basic SWT widget controls: label, text, button, composite, and shell. These controls, combined with the display class, allow fully functional GUIs to be created.

The second installment, "How to use combo, list, table, and tree controls," will show you how to create menus, and how to use additional input controls and information display controls like list, tree, and table.

Download

Description	Name	Size	Download method
Basic1 Java source	os-jface1Basic1.java	6.4KB	HTTP

Information about download methods

Resources

Learn

A good place to start looking for Java development information is the Sun Microsystems Web site. You'll find links to news, forums, articles, and downloads.
Sun's Java Foundation Classes (JFC/Swing) includes links to downloads, technical information, how-to articles, and news about JFC/Swing.
Sun offers a Web site for Java users. It contains games, previews, and other displays of Java technology, as well as downloads.
Eclipse In Action: A Guide for Java Developers (Independent Publishers Group, 2003) is a must-read for Java developers using Eclipse.
Read the entire "A gentle introduction to SWT and JFace" series.
To listen to interesting interviews and discussions for software developers, check out developerWorks podcasts.
Stay current with developerWorks' Technical events and webcasts.
Follow developerWorks on Twitter.
Check out upcoming conferences, trade shows, webcasts, and other Events around the world that are of interest to IBM open source developers.
Visit the developerWorks Open source zone for extensive how-to information, tools, and project updates to help you develop with open source technologies and use them with IBM's products.
Watch and learn about IBM and open source technologies and product functions with the no-cost developerWorks On demand demos.

Get products and technologies

Innovate your next open source development project with IBM trial software, available for download or on DVD.
Download IBM product evaluation versions or explore the online trials in the IBM SOA Sandbox and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.

Discuss

Participate in developerWorks blogs and get involved in the developerWorks community.

About the author

Comments (Undergoing maintenance)

Trademarks | My developerWorks terms and conditions

Close [x]

Help: Update or add to My dW interests

What's this?

This little timesaver lets you update your My developerWorks profile with just one click! The general subject of this content (AIX and UNIX, Information Management, Lotus, Rational, Tivoli, WebSphere, Java, Linux, Open source, SOA and Web services, Web development, or XML) will be added to the interests section of your profile, if it's not there already. You only need to be logged in to My developerWorks.

And what's the point of adding your interests to your profile? That's how you find other users with the same interests as yours, and see what they're reading and contributing to the community. Your interests also help us recommend relevant developerWorks content to you.

View your My developerWorks profile

Return from help

Close [x]

Help: Remove from My dW interests

What's this?

Removing this interest does not alter your profile, but rather removes this piece of content from a list of all content for which you've indicated interest. In a future enhancement to My developerWorks, you'll be able to see a record of that content.

View your My developerWorks profile

Return from help

static.content.url=http://www.ibm.com/developerworks/js/artrating/

SITE_ID=1

Zone=Open source, Java technology

ArticleID=82442

ArticleTitle=A gentle introduction to SWT and JFace, Part 1: How to create a simple SWT application

publish-date=12162004

author1-email=feigenba@us.ibm.com

author1-email-cc=