The first part of this article (JDJ, Vol. 8, issue 4) introduced the Standard Widget Toolkit (SWT), and showed how graphical user interfaces can be created using some of the basic widgets found in SWT. In addition, layout classes were described that allow widgets to be arbitrarily positioned and sized within their parent.

In Part 2, we continue where the previous article left off, describing some of the more advanced controls and concepts, including multithreading in the user interface. We conclude with a brief discussion of SWT graphics.

Items
Many of the advanced controls in SWT make use of items. Items are widgets that represent a specific kind of child within a control. They are always used in conjunction with the parent and cannot exist without the parent. For example, a menu contains menu items and a menu item cannot exist outside of a menu. Table 1 shows some controls and their associated items.

A complete description of each of these controls is beyond the scope of this article. However, we'll briefly discuss some of the most commonly used ones - Menu, TabFolder, Tree, and Table.

Menus
SWT supports menu bars, and drop-down and pop-up menus using a single class called Menu. Style bits provided in the constructor create the appropriate kind of menu. These bits are SWT.BAR, SWT.DROP_DOWN, and SWT.POP_UP.

Each choice in a menu is MenuItem. A menu item can have a number of styles, including SWT.CHECK, SWT.CASCADE, SWT.PUSH, SWT.RADIO, and SWT.SEPARATOR to support a different appearance and behavior.

A menu bar is the root of a hierarchy of drop-down menus. Every shell can optionally display a single menu bar using the setMenuBar(Menu menuBar) method of Shell. It's possible to create many menu bars in a shell, but only one can be visible in a shell at a time. The following code creates the standard File and New menus for the shell shown in Figure 1.

Menu bar = new Menu(shell,SWT.BAR);
shell.setMenuBar(bar);
MenuItem fileItem = new MenuItem(bar,SWT.CASCADE);
fileItem.setText("File");
Menu fileMenu = new Menu(shell,SWT.DROP_DOWN);
fileItem.setMenu(fileMenu);
MenuItem newItem = new MenuItem(fileMenu,SWT.PUSH);
newItem.setText("New");

Drop-down menus represent submenus in a hierarchy of menus. They can never be the root of a menu hierarchy and cannot be displayed without being connected to a menu bar, pop-up menu, or another drop-down menu. Drop-down menus are connected to other menus using the setMenu(Menu menu) method of MenuItem.

In Figure 1 the black lines indicate the containment hierarchy from top to bottom. The shell is the parent of the drop-down menu and the menu bar. The gray lines indicate the setMenu() relationship between the cascade menu item and the New menu. Dotted red lines show the objects that are visible in the window.

A pop-up menu is the root of a hierarchy of drop-down menus. Pop-up menus are sometimes called context menus and are normally associated with a control. In SWT, every control can optionally have a single context menu using Control.setMenu(Menu menu). The same context menu can be used in many different controls.

Some platforms show a pop-up menu when the user presses the mouse, while others show the menu when the user releases the mouse. Depending on the platform, there are also specific key sequences or mouse and key combinations that are used to request a pop-up menu. For example, on Windows, the user presses Shift+F10. On the Macintosh, the user holds down the control key and presses the mouse. In SWT, pop-ups are displayed appropriately no matter how they were requested.

Figure 2 shows a List with a pop-up menu that contains two menu items, one of which is a cascade item containing a drop-down menu. This menu has a single item that can be checked and unchecked by the user.

Menu popUpMenu = new Menu(shell,SWT.POP_UP);
list.setMenu(popUpMenu);
MenuItem copyItem = new MenuItem(popUpMenu,SWT.PUSH);
copyItem.setText("Copy");
MenuItem optionsItem = new MenuItem(popUpMenu,SWT.CASCADE);
optionsItem.setText("Options");
Menu optionsMenu = new Menu(popUpMenu);
optionsItem.setMenu(optionsMenu);
MenuItem check = new MenuItem(optionsMenu,SWT.CHECK);
check.setText("Check");

TabFolder
A TabFolder represents a notebook with pages and tabs. Each tab in the tab folder is a TabItem. Tab items can display strings and images. Tab folders support automatic page selection as well as more sophisticated control over paging.

Controls are included in automatic page selection using TabItem.setControl(). When the user clicks on a tab, the previous control is hidden and the new control is resized to fill the client area of the tab folder. There is no special control that represents a tab folder page. Any control can fill the client area, as long as it's a child of the tab folder. In Figure 3, the tab folder is using automatic page selection and was created using the following code.

TabFolder folder = new TabFolder(shell,SWT.NONE);
TabItem tab1 = new TabItem(folder,SWT.NONE);
tab1.setText("Page One");
List list = new List(folder,SWT.BORDER);
tab1.setControl(list);
TabItem tab2 = new TabItem(folder,SWT.NONE);
tab2.setText("Page Two");
Composite comp = new Composite(folder,SWT.NONE);
tab2.setControl(comp);

The implementation of TabFolder is flexible. It allows complete control of the client area of the folder and doesn't dictate when and how pages are created. To avoid automatic page selection and to implement your own page selection strategy, don't call setControl(Control). This allows you to hide and show pages yourself by listening for selection events on the tab folder. TabFolder supports the SWT.Selection event and listeners can be added using addListener() or addSelectionListener(). You can even create pages lazily, destroy or hide them, or keep some of the same controls around from a previous page when the page changes. Of course, this requires more effort on the part of the programmer.

Tree
A Tree represents a hierarchy of tree items. Each node in the tree is represented by the class TreeItem. Tree items can display strings and images, and can be collapsed and expanded by the user or by the programmer using TreeItem.setExpanded(boolean expand).

TreeItems are created using the constructors TreeItem(Tree tree, int style) and TreeItem(TreeItem tree, int style). These constructors allow a new item to be a child of another item or a child of the tree. In addition, the constructors TreeItem(TreeItem tree, int style, int index) and TreeItem(Tree tree, int style, int index) allow an item to be inserted at an arbitrary position with respect to a sibling in the tree.

Tree tree = new Tree(shell, SWT.BORDER);
TreeItem firstItem = new TreeItem(tree,SWT.NONE);
firstItem.setText("First Item");
TreeItem secondItem = new TreeItem(tree,SWT.NONE);
secondItem.setText("Second Item");
TreeItem childOfFirstItem = new TreeItem(firstItem,SWT.NONE);
childOfFirstItem.setText("Child of First Item");

Figure 4 shows a tree with three items where two are children of the tree and one is a child of another item.

A tree can allow more than one item to be selected when created with the style bit SWT.MULTI. Selected items are returned by getSelection(), which returns an array of the currently selected items. To know when the selection has changed, trees support the SWT.Selection event.

In addition to text, a tree item can have an image associated with it using setImage(Image image). Individual colors for each item can be changed with setForeground(Color color) and setBackground(Color color).

The Tree style bit SWT.CHECK can be used to allow each item to have a check-box appearance, as shown in Figure 5. When a TreeItem has been checked or unchecked, a selection listener is called with the detail field of the event set to SWT.CHECK. This allows the programmer to determine whether the item or the check box was selected.

Table
Tables are used to display a list of strings and images, optionally in columns. Each row in the table is represented by a TableItem. When no columns are added by the programmer, the table behaves like a List widget, showing a single list of items with no headers or grid lines.

To add a column, TableColumn(Table parent, int style) is used to create the new column. After a column is created, in order for it to be visible to the user, it must be resized. The TableColumn methods setSize(int width) and pack() are used to resize a column. The pack() method makes the column large enough to display the column header or widest string and image in the column. It's typically called after all the items have been added to the table.

For column headings and grid lines to be shown, the Table methods setHeaderVisible(boolean) and setLinesVisible(boolean) are used. Headers and grid lines are not shown by default.

Table table = new Table(shell, SWT.BORDER);
table.setHeaderVisible(true);
table.setLinesVisible(true);
TableColumn columnOne = new TableColumn(table,SWT.NONE);
columnOne.setText("First Name");
TableColumn columnTwo = new TableColumn(table,SWT.NONE);
columnTwo.setText("Last Name");

Figure 6 shows the table. (Note: On Windows the last column does not extend to fill up the available space.) Each row in the table is a TableItem created using TableItem(Table parent, int style). To set the contents of particular cell, use the methods setText(int index,Sting text) or setText(String[] strings).

TableItem firstTableItem = new TableItem(table,SWT.NONE);
firstTableItem.setText(new String[] {"Chris","Chringle"});
TableItem secondTableItem = new TableItem(table,SWT.NONE);
secondTableItem.setText(0,"Tooth");
secondTableItem.setText(1,"Fairy");

As well as showing text, a table item cell can display an image. Like the tree control, the style bit SWT.CHECK is used to add check boxes to the control (see Figure 7).

In Figures 5 and 7, you'll notice that the examples contain images and text. Where did these images come from and how were they created?

Graphics: A Brief Introduction
SWT includes the package org.eclipse.swt.graphics that provides general-purpose graphics capability. Table 2 shows the basic set of SWT graphics objects.

Both widgets and graphics share the same coordinate system, with (0, 0) in the top left corner. Most of the time, it's possible to use graphics objects and have the widgets do all the drawing for you. Graphics objects often appear as arguments in the widget API. For example, you can set an image into a button, causing the button to draw the image.

Fonts, Images, and Colors
A Font is created with a font-face name, a point size, and style bits. The style bits are a bitmask of SWT.NORMAL, SWT.BOLD, and SWT.ITALIC.

Font font1 = new Font(display,"Courier",18,SWT.BOLD);
Font font2 = new Font(display,"Arial",10,SWT.ITALIC | SWT.BOLD);

Images can be created from an absolute path or loaded from an input stream.

Image image1 = new Image(display,"c:/temp/eclipse32.gif");
InputStream stream =
getClass().getResourceAsStream
("icons/image.gif");
Image image2 = new Image(display,stream);

Colors are created from red, green, and blue components. These are integer values from 0 to 255. Commonly used colors can be retrieved directly from the display using the method getSystemColor(int id).

Color cyan = new Color(display,0,255,255);
Color red = display.getSystemColor(SWT.COLOR_RED);

The same font, image, or color can be shared by many different controls, reducing the number of operating system resources that are allocated. The results are shown in Figure 8.

Most graphics objects, like fonts and images, use operating system resources in the same manner as controls, and must be disposed when they are no longer required (see www.eclipse.org/articles/swt-design-2/swt-design-2.html).

GC: The Only Way to Draw
GC, which is short for graphics context, is one of the most important graphics classes in SWT. All drawing and measuring operations are defined in this class. For those readers who are familiar with Windows GDI, a GC is equivalent to an HDC. On X Windows, a GC is a thin layer on top of an X Windows GC.

GCs are created on different kinds of objects, usually an image or a control, allowing drawing and measuring operations to occur in these objects.

Drawing Lines and Shapes
GC has a number of API methods that allow the drawing of images, shapes, and text. As well as drawing a simple line between two points, there are a number of methods that draw pre-defined shapes. Arbitrary polygons can be drawn by defining the points that make up the polygon. Lines and shapes are drawn in the foreground color of the GC. Different line widths and styles can be specified. Figure 9 shows the results of running the following code.

gc.drawRectangle(10,10,30,40);
gc.setLineStyle(SWT.LINE_DOT);
gc.drawOval(50,10,30,40);
gc.setLineWidth(3);
gc.setLineStyle(SWT.LINE_SOLID);
gc.drawPolygon(new int[]
{90,10,90,50,120,30});
gc.drawArc(130,10,30,40,90,270);

The first shape that is drawn is a rectangle whose top left corner is (10,10) with width 30, height 40. The next shape is an oval. Ovals are drawn by specifying the bounding rectangle for the oval. In the example code, this is a rectangle with a top left corner at (50, 10) with width 30, height 40. Next, a triangle is drawn as a polygon whose corners are (90, 10), (90, 50) and (120, 30). Arcs are drawn by specifying the bounding rectangle along with the start and end angle. A start angle of 0 points due east. In the previous code, the start angle 90 means the arc begins from the top of the bounding rectangle. The end angle is the number of degrees the arc is drawn in a counterclockwise direction, 270 degrees in the code.

For each method that draws a shape there is a corresponding method that fills the shape. Shapes are filled using the background color of the GC. The following code fills a number of shapes in green as shown in Figure 10.

gc.setBackground
(display.getSystemColor
(SWT.COLOR_GREEN));
gc.fillRectangle(10,10,30,40);
gc.fillOval(50,10,30,40);
gc.fillPolygon(new int[] {90,10,90,50,120,30});
gc.fillArc(130,10,30,40,90,270);

Drawing Text and Images
Text is drawn using the method GC.drawText(String text, int x, int y, int flags). The x and y arguments specify the location of the drawing operation. The flags are a bitmask of the constants SWT.DRAW_TRANSPARENT, SWT.DRAW_MNEMONIC, SWT.DRAW_TAB, and SWT.DRAW_DELIMITER. The last three bit flags determine whether "&", "\t", and "\n" should be processed as mnemonic, tab, or new line directives or drawn in the text instead. Text is measured using GC.textExtent(String text, int flags). This method returns a point that is the bounding box of the string. The following code draws an image on GC and then some text; the result is shown in Figure 11.

gc.drawImage(image,0,0);
gc.setForeground(display.getSystemColor(SWT.COLOR_MAGEN
TA));
gc.drawText("The\tStandard",10,10);
gc.drawText("Widget/n&Toolkit",10,30,true);
gc.drawText("and &Eclipse",10,70,SWT.DRAW_MNEMONIC);

Text is normally drawn with the background filled using the background color of the GC. For transparent text use the convenience method GC.drawText(String text, int x, int y, boolean transparent) or the SWT.DRAW_TRANSPARENT bit flag.

Images are drawn in their original size or cropped and stretched. The following code draws the Eclipse image three times as shown in Figure 12. The image is drawn once at (10,10) at the original size, then drawn again at (10,50), this time drawing only the bottom left quarter. Finally the image is stretched to twice its size vertically, four times its size horizontally, and drawn at (50,10).

gc.drawImage(image,10,10);
gc.drawImage
(image,0,16,16,16,10,50,32,32);
gc.drawImage
(image,0,0,32,32,50,10,128,64);

Drawing in an Image
As well as loading images from files and input streams, it's also possible to create an image and draw into it or draw on an image that was loaded. The following code uses a GC to draw a white line from (0, 0), the top left corner to (30, 30), the bottom right corner in an image. The resulting image is set into a label. Figure 13 shows that label in a shell.

Image image = new
Image(display,"C:/eclipse32.gif");
GC gc = new GC(image);
gc.setForeground
(display.getSystemColor
(SWT.COLOR_WHITE));
gc.drawLine(0,0,30,30);
gc.dispose();
Label label = new Label(shell,SWT.NONE);
label.setImage(image);

Drawing in a Control
We've seen how to use a GC to draw into an image and how images can be drawn by a GC or a control. It's also possible to draw directly into a control. The following code fragment draws a line from (0, 0) to (30, 30) in a Canvas (a class that is specifically designed for drawing operations):

GC gc = new GC(canvas);
gc.drawLine(0,0,30,30);
gc.dispose();

In a multiwindowed windowed environment where the desktop is shared by many different processes, each with multiple overlapped windows, what happens to the line when the user clicks on another window and then clicks back on the canvas? Since most operating systems don't retain graphics operations or save the window contents automatically, the canvas is redrawn without the line. How can we ensure that the line will always be drawn when the canvas is drawn? The answer is to use a paint listener.

Paint Listeners
The code fragment, shown in Figure 14, draws a line from (0, 0) to (30, 30) on a canvas in an SWT.Paint listener, ensuring that the line will always be drawn every time the canvas is drawn:

Canvas canvas = new Canvas(shell,SWT.BORDER);
canvas.setBounds(10,10,160,80);
Listener listener = new Listener() {
public void handleEvent(Event
event) {
event.gc.drawLine(0,0,30,30);
}
};
canvas.addListener(SWT.Paint,listener);

Notice that we did not create a GC but used one from the paint event. On most operating systems, when a control is drawn, the window system provides a native graphics context that is clipped so that only the area that was exposed will be painted. SWT takes advantage of this feature and provides a GC that maps directly to the native graphics context. The coordinate system of the GC is the client area of the control, so in Figure 14 the line begins at (0,0) within the Canvas and continues to (30,30).

To determine how much of the canvas needs to be painted, the paint event contains the damaged area. This is the x, y, width, and height of the area that needs to be drawn. In most situations, paint listeners just draw the entire client area of the control, ignoring the damage. However, it's possible to use the damaged area to draw less. In the example, if the damaged area did not intersect the line from (0, 0) to (30, 30), then the paint listener could choose not to draw the line.

When do paint events occur? As previously discussed, they can occur when the user resizes or exposes a window on the desktop. It is also possible for the programmer to cause a paint event to occur using the method Control.redraw(). Why would we want to do this? For one thing, drawing outside of a paint event means that the drawing operations will get lost when the window is resized or exposed. This means that a control always needs to be able to draw its contents in a paint event, so why draw outside of paint? In addition, drawing in paint can reduce flicker. Most operating systems collapse individual paints and merge the damaged area into a single paint event, reducing the number of redraws.

To damage a specific area and cause it to be redrawn, use Control.redraw(int x, int y, int width, int height, boolean all). The integer arguments specify the damage rectangle while the boolean argument determines whether the rectangle should also be damaged in the children of the control.

Occasionally, it makes sense to flush all outstanding paint events for a control, causing it to draw right away. This is sometimes necessary when a program takes some time getting back to the event loop and needs to give feedback to the user right away. For example, imagine a control that displays a line of text (like a Label) and only draws this text inside the paint event. When the text is changed, the control issues a redraw() to cause a paint and eventually draw the new text when the next paint occurs from the event loop. If the text is changed to many different strings, redraw() will be called for each string but only one merged paint will occur. This means that the control will only draw the last string. Normally this is not a problem but if the control is being used as a counter in a tight loop to give feedback to the user, the user will only see the last value of the counter when the tight loop has finished and the program goes back to the event loop.

To flush all outstanding paint events, the Control.update() method is used. Generally, it's a bad idea to flush outstanding paints because this defeats the paint event and the damaged area merging mechanism of the operating system.

Multithreaded Programming
In SWT, by definition the thread that creates the Display is a UI thread. This thread is responsible for reading and dispatching events from the operating system event queue, and invoking listeners in response to these events. Listener code is executed in the UI thread. This makes an SWT application generally quite responsive, behaving like most other operating system programs. However, any long operation, when executed by a listener, will run in the UI thread and prevent it from reading and dispatching events, thus temporarily hanging the application.

If a listener has a large amount of work to perform, instead of performing that work in the UI thread, it can fork a separate thread so the UI thread can continue dispatching events. If the other thread needs to execute code that accesses an SWT object, such as changing the string in a label, there's a concurrency issue. Some kind of synchronization mechanism is necessary to prevent the operating system or SWT from crashing, hanging, or behaving unpredictably.

SWT implements a single-threaded UI model often called apartment threading. In this model, only the UI thread can invoke UI operations. SWT strictly enforces this rule. If you try to access an SWT object from outside the UI thread, you get the exception "org.eclipse.swt.SWTException: Invalid thread access". Different operating systems have different rules governing threads, UI components, and synchronization. Some use a single-threaded UI model like SWT. Others allow only one thread at a time in the window system library, controlling access through a global lock. This type of multithreaded UI model is often called free threading. To be simple, efficient, and portable, SWT is apartment threaded.

To allow background threads to perform operations on objects belonging to the UI thread, the methods syncExec(Runnable runnable) and asyncExec(Runnable runnable) of Display are used. These are the only methods in SWT that can be called from any thread. They allow a runnable to be executed by the UI thread, either synchronously, causing the background thread to wait for the runnable to finish, or asynchronously, allowing the background thread to continue execution without waiting for the result. A runnable that is executed using syncExec() most closely matches the equivalent direct call to the UI operation because a Java method call always waits for the result before proceeding, just like syncExec().

The following code sets the text of a label from a background thread and waits for the operation to complete:

display.syncExec(
new Runnable() {
public void run(){
label.setText(text);
}
}
);

Conclusion
One of the design goals of SWT was to create a rich set of user interface controls so that developers could build applications with a high level of integration on the desktop. SWT includes an advanced set of user interface controls such as Tree, Table, TabFolder, and Menu. These controls display images as well as strings. The package org.eclipse.swt.graphics provides a general purpose graphics capability, including support for images, fonts, and colors.

In SWT, events are dispatched from the thread that is running the event loop. Widgets can only be accessed programmatically from that thread. To allow background threads to update the user interface, the Display class provides both a synchronous and asynchronous mechanism.

Acknowledgment
We would like to thank Veronika Irvine of IBM Canada for her help in preparing these articles.

SIDEBAR

Errata
In Part 1 of the article (Vol. 8, issue 4) there was an error in the section "Obtaining the SWT". The Java command should be:

java -classpath "helloworld.jar";C:\ECLIPSE\
eclipse\plugins\org.eclipse.swt.win32_2.0.1\
ws\win32\swt.jar
-Djava.library.path=C:\ECLIPSE\eclipse\plugins\
org.eclipse.swt.win32_2.0.1\os\win32\x86
HelloWorld