SWT includes many rich features, but a basic knowledge of the system's core - widgets, layouts, and events - is all that is needed to implement useful and robust applications.

Widget application structure

When you are contributing UI elements using platform workbench extensions, the mechanics of starting up SWT are handled for you by the workbench.

If you are writing an SWT application from scratch outside of the workbench, you must understand more about SWT's application structure.

A typical stand-alone SWT application has the following structure:

The following code snippet is adapted from the org.eclipse.swt.examples.helloworld.HelloWorld2 application. Since the application only displays the string "Hello World," it does not need to register for any widget events.

   public static void main (String [] args) {
      Display display = new Display ();
      Shell shell = new Shell (display);
      Label label = new Label (shell, SWT.CENTER);
      label.setText ("Hello_world");
      label.setBounds (shell.getClientArea ());
      shell.open ();
      while (!shell.isDisposed ()) {
         if (!display.readAndDispatch ()) display.sleep ();
      display.dispose ();


The Display represents the connection between SWT and the underlying platform's GUI system. Displays are primarily used to manage the platform event loop and control communication between the UI thread and other threads. (See Threading issues for clients for a complete discussion of UI threading issues.)

For most applications you can follow the pattern that is used above. You must create a display before creating any windows, and you must dispose of the display when your shell is closed. You don't need to think about the display much more unless you are designing a multi-threaded application.


A Shell is a "window" managed by the OS platform window manager. Top level shells are those that are created as a child of the display. These windows are the windows that users move, resize, minimize, and maximize while using the application. Secondary shells are those that are created as a child of another shell. These windows are typically used as dialog windows or other transient windows that only exist in the context of another window.

Parents and children

All widgets that are not top level shells must have a parent. Top level shells do not have a parent, but they are created in association with a particular Display. You can access this display using getDisplay(). All other widgets are created as descendants (direct or indirect) of top level shells.

Composite widgets are widgets that can have children.

When you see an application window, you can think of it as a widget tree, or hierarchy, whose root is the shell. Depending on the complexity of the application, there may be a single child of the shell, several children, or nested layers of composites with children.

Style bits

Some widget properties must be set at the time a widget is created and cannot be subsequently changed. For example, a list may be single or multi-selection, and may or may not have scroll bars.

These properties, called styles, are set in the constructor. All widget constructors take an int argument that specifies the bitwise OR of all desired styles. In some cases, a particular style is considered a hint, which means that it may not be available on all platforms, but will be gracefully ignored on platforms that do not support it.

The style constants are located in the SWT class as public static fields. A list of applicable constants for each widget class is contained in the API Reference for SWT.

Resource disposal

The platforms underneath SWT require explicit allocation and freeing of OS resources. In keeping with the SWT design philosophy of reflecting the platform application structure in the widget toolkit, SWT requires that you explicitly free any OS resources that you have allocated. In SWT, the Widget.dispose() method is used to free resources associated with a particular toolkit object.

The rule of thumb is that if you create the object, you must dispose of it. Here are some specific ground rules that further explain this philosophy:

There is one exception to these rules. Simple data objects, such as Rectangle and Point, do not use operating system resources. They do not have a dispose() method and you do not have to free them. If in doubt, check the javadoc for a particular class.

See Managing operating resources for further discussion of this topic.