Custom widgets

Custom Widgets

You may want to extend SWT by implementing your own custom widget. SWT itself provides a package, org.eclipse.swt.custom, which contains custom controls that are not in the core set of SWT controls but are needed to implement the platform workbench.

Control	Purpose
CBanner	CBanner is used in the workbench to layout the toolbar area and perspective switching toolbar.
CCombo	Similar to Combo, but is vertically resizable allowing it to fit inside table cells.
CLabel	Similar to Label, but supports shortening of text with an ellipsis. Also supports a gradient effect for the background color as seen in the active workbench view. Does not support wrapping.
CTabFolder	Similar to TabFolder, but supports additional configuration of the visual appearance of tabs (top or bottom) and borders.
CTabItem	Selectable user interface object corresponding to a tab for a page in a CTabFolder.
SashForm	Composite control that lays out its children in a row or column arrangement and uses a Sash to separate them so that the user can resize them.
ScrolledComposite	Composite control that scrolls its contents and optionally stretches its contents to fill the available space.
StyledText	Editable control that allows the user to type text. Ranges of text inside the control can have distinct colors and font styles.
ViewForm	ViewForm is used in the workbench to position and size a view's label/toolbar/menu local bar.

Implementing a Custom Widget

Once you've determined that you need a custom widget and have decided which platforms must be supported, you can consider several implementation techniques for your widget. These techniques can be mixed and matched depending on what is available in the underlying OS platform.

Native Implementation

If your application requires a native widget that is not provided by SWT, you will need to implement it natively. This may be a platform widget, a third party widget, or any other widget in a platform shared library. A complete example of a native custom widget implementation can be found in Creating Your Own Widgets using SWT.

Combining Existing Widgets

Widgets can be combined to form widgets that are more sophisticated. For example, a Combo can be implemented using a text entry widget along with a button and a drop-down list. To implement a combined widget, you create a subclass of Composite and manage the children internally.

A simple example can be found in CCombo.

Custom Drawn Implementation

In some cases, you don't have any native code or existing widgets that help you in the implementation of your new widget. This means you must draw the widget yourself in the handler for the Paint event. Although this technique can become quite complicated, it has the advantage of producing a completely portable implementation.

Custom drawn controls are implemented by subclassing the Canvas or Composite. Subclass Canvas if your widget will not contain any child controls.

The internal implementation of a custom drawn widget usually involves these major tasks:

Create any graphics objects needed in your constructor and store them in an instance variable. Register a listener for the dispose event on your canvas or composite so that you can free these objects when the widget is destroyed.
Add a paintListener to your canvas or composite and paint the widget according to your design. For complex widgets, a lot of work goes into optimizing this process by calculating and repainting only what's absolutely necessary.
Ensure that any API calls that affect the appearance of your widget trigger a repaint of the widget. In general, you should use redraw to damage your widget when you know you must repaint, rather than call your internal painting code directly. This gives the platform a chance to collapse the paint you want to generate with any other pending paints and helps streamline your code by funneling all painting through one place.
If your widget defines events in its API, determine what low level Canvas or Composite events will trigger your widget's events. For example, if you have a clicked event, you will want to register a mouse event on your canvas and perform calculations (such as hit testing) to determine whether the mouse event in your canvas should trigger your widget event.

Many of the widgets implemented in the org.eclipse.swt.custom use this approach. A simple example can be found in CLabel.

Further information on custom widgets can be found in Creating your own widgets using SWT.