Eclipse Corner Article

Creating Your Own Widgets using SWT

Summary
When writing applications, you typically use the standard widgets provided by SWT. On occasion, you will need to create your own custom widgets. For example, you might want to add a new type of widget not provided by the standard widgets, or extend the functionality of an existing widget. This article explains the different SWT extension strategies and shows you how to use them.

By Steve Northover & Carolyn MacLeod, OTI
March 22, 2001

Creating Your Own Widgets

Overview

When writing applications, you typically use the standard widgets provided by SWT. On occasion, you will need to create your own custom widgets. There are several reasons that you might want to do this:

· To add a new type of widget not provided by the standard widgets

· To extend the functionality of an existing widget

Custom widgets are created by subclassing in the existing widget class hierarchy.

Portability Issues

It is very important to think about portability before writing a custom widget. SWT can be extended in the following ways:

· Write a new widget that is 100% Java™ portable

· Extend an existing widget in a 100% Java portable manner

· Write a new widget that wraps an existing native widget – not portable

· Extend an existing widget by calling natives – not portable

In addition, a combination of these can be used on different platforms:

· Write a new widget that wraps an existing native widget on one platform, but is 100% Java portable on other platforms

· Extend an existing widget by calling natives on one platform, but call 100% Java portable code on other platforms

This of course involves implementing the widget twice – using native calls on the one platform and portable code on the others – while maintaining the same API for both.

Each SWT platform is shipped with both a shared library (for example, a DLL on Windows®) and a jar (for the Java class files). The shared library contains all of the native function required for SWT, but it was not meant to be a complete set of the functions available on the platform. Thus to expose native function or native widgets that were not exposed by SWT, you need to write your own shared library. If you are using a combination of native code on one platform and portable code on another, make sure you call your shared library on the platform with the native widget, and your jar on the platform with the portable widget.

One final note: SWT’s interface to its shared libraries is internal SWT code. It was not meant to provide a framework for applications to access all possible native function on all platforms – that would be a daunting task. One of the purposes of this document is to show how you can integrate C code with SWT, not model the operating system. As such, the approach taken to writing natives in this document is different from the approach taken by SWT.

Writing Portable Widgets

The SWT library provides two widget classes that are typically used as the basis for a custom 100% Java portable widget:

· Canvas - to create basic widgets

· Composite - to create compound widgets

Basic Widgets

Basic widgets do not contain any other widgets, and are not built from any other widgets. Basic widgets draw themselves. An example of a basic widget is Button. Another example is Text. To create a custom basic widget, subclass Canvas.

Compound Widgets

Compound widgets contain other widgets, and/or are composed of other widgets. An example of a compound widget is Combo. It contains a Text, a Button and a List. Another example is Group. It can contain any number of children. To create a custom compound widget, subclass Composite.

The astute reader may have noticed that Canvas is actually a subclass of Composite. This is an artifact of the underlying implementation. We treat Canvas as something you draw on and Composite as something that has children. Therefore the rule for deciding which class to subclass is this: If your widget has or will have children, subclass Composite. If your widget does not have and never will have children, subclass Canvas.

Note also that we do not distinguish between a compound widget that is intended to contain and lay out children, and one that is merely composed of other widgets. Both will be a subclass of Composite, and as such we are describing implementation, rather than type, inheritance. When writing 100% Java portable widgets, we can think of Composite as the portable entry point into the SWT class hierarchy for all compound widgets, and Canvas as the portable entry point into the SWT class hierarchy for all basic widgets, regardless of widget type.

Basic Widget Example

Imagine we are building an application where we need a widget that displays an image with a line of text to the right, something like this:

Since we plan to draw both the image and the text, we subclass Canvas.

import org.eclipse.swt.*;

import org.eclipse.swt.graphics.*;

import org.eclipse.swt.widgets.*;

import org.eclipse.swt.events.*;

public class PictureLabel extends Canvas {

Image image;

String text;

}

Our widget needs to be created. To do this, we must write at least one constructor. Because widgets in SWT cannot be created without a parent, the constructor must take at least one argument that is the parent. The convention in SWT is to have a constructor with two arguments, parent and style. Style bits are used to control the look of widgets. Neither the parent nor the style bits can be changed after the widget is created. Your widget can use style bits too.

PictureLabel(Composite parent, int style) {

super(parent, style);

}

The parent of any widget must be a Composite. The style is an integer, where some bits are already used by the system. For example, SWT.BORDER will cause a Canvas to have a border.

Next we need to initialize our widget. The convention in SWT is to do all initialization in the constructor. Certainly, any initialization that requires the parent or the style bits must be done here. We have decided that our PictureLabel widget will default to a white background, so we need to add a Color field, allocate a Color, and initialize the background.

public class PictureLabel extends Canvas {

Image image;

String text;

Color white;

PictureLabel(Composite parent, int style) {

super(parent, style);

white = new Color(null, 255, 255, 255);

setBackground(white);

Colors are graphics resources that must be disposed. How can we dispose of the white color that we allocated? We add a dispose listener. Every widget provides notification when it is destroyed. We add the dispose listener in the constructor.

addDisposeListener(new DisposeListener() {

public void widgetDisposed(DisposeEvent e) {

white.dispose();

}

});

}

Note: Do not just override dispose() to release the color. This only works in the case where dispose is actually sent to the widget. When the shell is disposed this does not happen, so overriding dispose will leak the color. To ensure that your widget is informed of an event no matter how it was generated, add an event listener instead of overriding methods that generate events.

Our widget is created and initialized, and it can be destroyed without leaking graphics resources. Now it needs some functionality. We need to draw the image and the text, and this will require another listener: the paint listener. Implementing a widget often requires adding many listeners. We could implement the listener interfaces as part of our new widget class, but that would make the interface methods public in our class. Instead, the SWT convention is to use anonymous inner classes to forward the functionality to non-public methods of the same name. For consistency, we will rewrite the dispose listener to follow this convention, moving the color dispose code into the widgetDisposed method. We write the paint listener the same way.

addDisposeListener(new DisposeListener() {

public void widgetDisposed(DisposeEvent e) {

PictureLabel.this.widgetDisposed(e);

}

});

addPaintListener(new PaintListener() {

public void paintControl(PaintEvent e) {

PictureLabel.this.paintControl(e);

}

});

By choosing the same names, we have the option of easily implementing the interfaces if we decide to do so later. Here is the paintControl method to draw the widget.

void paintControl(PaintEvent e) {

GC gc = e.gc;

int x = 1;

if (image != null) {

gc.drawImage(image, x, 1);

x = image.getBounds().width + 5;

}

if (text != null) {

gc.drawString(text, x, 1);

}

Now we can draw the image and the text, but we need to let the user set them. So we write set and get methods for each of them.

public Image getImage() {

return image;

}

public void setImage(Image image) {

this.image = image;

redraw();

}

public String getText() {

return text;

}

public void setText(String text) {

this.text = text;

redraw();

}

The get methods are trivial. They simply answer the fields. The set methods set the fields and then redraw the widget to show the change. The easiest way to do this is to damage the widget by calling redraw(), which queues a paint event for the widget. This approach has the advantage that setting both the image and the text will cause only one paint event because multiple paints are collapsed in the event queue.

We are not done yet. Our widget does not know its preferred size. This information is needed in order to lay out the widget. In our case, the best size is simply the size of the text plus the size of the image, plus a little bit of space in between. Also, we will add a 1 pixel margin all the way around.

To return the preferred size of the widget, we must implement the computeSize method. The computeSize method can be quite complicated. Its job is to calculate the preferred size of the widget based on the current contents. The simplest implementation ignores the arguments and just computes the size.

public Point computeSize(int wHint, int hHint, boolean changed) {

int width = 0, height = 0;

if (image != null) {

Rectangle bounds = image.getBounds();

width = bounds.width + 5;

height = bounds.height;

}

if (text != null) {

GC gc = new GC(this);

Point extent = gc.stringExtent(text);

gc.dispose();

width += extent.x;

height = Math.max(height, extent.y);

}

return new Point(width + 2, height + 2);

}

What are wHint, hHint, and changed? The hint arguments allow you to ask a widget questions such as “Given a particular width, how high does the widget need to be to show all of the contents”? For example, a word-wrapping Label widget might be asked this. To indicate that the client does not care about a particular hint, the special value SWT.DEFAULT is used. The following example asks a label for its preferred size given a width of 100 pixels:

Point extent = label.computeSize(100, SWT.DEFAULT, false);

For our PictureLabel widget, we could be fancy and stack the image over the text when the width is too small, and/or wrap the text in order to meet a width request, but for simplicity we have decided not to do so. Still, we need to honour the hints. So, our widget will clip. The easiest way to do this is to perform the calculation and then filter the results.

public Point computeSize(int wHint, int hHint, boolean changed) {

int width = 0, height = 0;

if (image != null) {

Rectangle bounds = image.getBounds();

width = bounds.width + 5;

height = bounds.height;

}

if (text != null) {

GC gc = new GC(this);

Point extent = gc.stringExtent(text);

gc.dispose();

width += extent.x;

height = Math.max(height, extent.y);

}

if (wHint != SWT.DEFAULT) width = wHint;

if (hHint != SWT.DEFAULT) height = hHint;

return new Point(width + 2, height + 2);

}

Notice that we do not return the hint sizes exactly as specified. We have added the 1-pixel border. Why do we do this? All widgets have a client area and trim. The hint parameters specify the desired size of the client area. We must set the size of the widget so that the size of the client area is the same as the hint, so the size we return from computeSize must include the trim.

What about the changed flag? This is used in conjunction with SWT layout managers and is ignored for basic widgets. This will be discussed when we talk about compound widgets.

Compound Widget Example

Now we will recode the PictureLabel widget as a compound widget. Note that this section assumes that you have read the basic widget example section. This time the widget will be implemented using two Label children: one to display the image, and one to display the text. Since we are using other widgets to implement our widget, we subclass Composite.

public class PictureLabel extends Composite {

Label image, text;

Color white;

PictureLabel(Composite parent, int style) {

super(parent, style);

white = new Color(null, 255, 255, 255);

image = new Label(this, 0);

text = new Label(this, 0);

setBackground(white);

image.setBackground(white);

text.setBackground(white);

addDisposeListener(new DisposeListener() {

public void widgetDisposed(DisposeEvent e) {

PictureLabel.this.widgetDisposed(e);

}

});

As well as initializing the graphics resources in the constructor, we need to create the child widgets and set their background color. A common mistake is to create the child widgets as children of the parent. This would make them peers of our widget. Instead, make sure to create them as children of this. The dispose listener frees the color, as before.

Now that we have handled creation and destruction, we need to lay out the children. There are two possibilities:

· position the children when the widget is resized

· use a layout manager

We will implement both here for comparison.

Positioning Children on Resize

First, we will position the children when the widget is resized. We need to add a resize listener.

addControlListener(new ControlAdapter() {

public void controlResized(ControlEvent e) {

PictureLabel.this.controlResized(e);

}

});

}

void controlResized(ControlEvent e) {

Point iExtent = image.computeSize(SWT.DEFAULT, SWT.DEFAULT, false);

Point tExtent = text.computeSize(SWT.DEFAULT, SWT.DEFAULT, false);

image.setBounds(1, 1, iExtent.x, iExtent.y);

text.setBounds(iExtent.x + 5, 1, tExtent.x, tExtent.y);

}

When the widget is resized, we compute the size of each of our children, and then use their extents and our 5-pixel spacing and 1-pixel margin to position the children using setBounds.

Now we will write the set and get methods. Because we are not drawing the image and text, damaging the widget will not cause the correct behavior. The children must be resized to show their new contents. To do this, we will take the code from the resize listener and move it into a helper method called resize.

void controlResized(ControlEvent e) {

resize();

}

void resize() {

Point iExtent = image.computeSize(SWT.DEFAULT, SWT.DEFAULT, false);

Point tExtent = text.computeSize(SWT.DEFAULT, SWT.DEFAULT, false);

image.setBounds(1, 1, iExtent.x, iExtent.y);

text.setBounds(iExtent.x + 5, 1, tExtent.x, tExtent.y);

}

Here are the set and get methods.

public Image getImage() {

return image.getImage();

}

public void setImage(Image image) {

this.image.setImage(image);

resize();

}

public String getText() {

return text.getText();

}

public void setText(String text) {

this.text.setText(text);

resize();

}

Now we have to implement the computeSize method. This is a simple matter of asking the children for their preferred sizes.

public Point computeSize(int wHint, int hHint, boolean changed) {

Point iExtent = image.computeSize(SWT.DEFAULT, SWT.DEFAULT, false