Eclipse Forms Programming Guide

Initial creation: 21 February 2004
Added table wrap sample: 22 February 2004

Introduction

This document has been written to help you use the new Eclipse 3.0 feature called 'Eclipse Forms'. The content will eventually move to Eclipse help. In the mean time, you can start experimenting using examples shown below and code in Eclipse 3.0 integration builds.

Eclipse Forms is a plug-in that exposes a set of customs widgets and other supporting classes that were before used as internal to PDE and Update components. They provide for creating polished, 'Web-like' UIs by modestly extending SWT and/or manipulating style bits, colors, fonts and other properties in order to get the desired behavior. This technology was used throughout PDE multi-page editors and will now be available as public API in Eclipse 3.0.

The document represents the state of API at the time of writing. It is possible that some aspects of the API will slightly change until final release. We anticipate only mechanical name changes rather than more fundamental changes.

Problem definition

When Eclipse platform was designed, there were two distinct context in which SWT widgets could appear:

• In traditional dialogs (message boxes, dialogs, wizards, preference pages, property pages)
• In content areas (views and editors)

Controls in dialogs typically used default colors and fonts as provided by the operating system and were layed out using GridLayout in 9 out of 10 cases. The goal was to look like a dialog and fill the dialog space in both directions.

Controls in views and editors were 'stretchy' i.e. they filled the entire content area. Stretchy controls can scroll their content (trees, tables, text areas, lists etc.). The colors and fonts used here were those provided by the system for use in content area (these colors can be obtained from the Display using SWT.LIST_BACKGROUND or SWT.LIST_FOREGROUND keys).

What was missing was the third option where widgets you would normally see in the dialog context are created in views or editors (where you would expect 'stretchy' controls). Several problems needed to be solved:

1. SWT controls like buttons, labels, composites etc. look strange in the content areas as-is (with the default dialog background)
2. Composites with GridLayout in the content area are problematic because they are not scrolled. Therefore, it is easy to get the controls to clip or start riding one another.
3. Controls in the content area are normally wrapped to fill the provided width. Wrapping is very hard to accomplish with the existing SWT layouts.
4. When problems 1-3 are fixed, the result looks very much like forms in HTML browsers, and a natural leap is to add hyperlinks and mix them with other controls.

Eclipse Forms were designed to solve these problems. They provide:

1. A concept of a 'form' that is suitable for inclusion into the content area (editor or view)
2. A toolkit that manages colors, hyperlink groups and other aspects of the form, as well as serve as a factory for a number of SWT controls (these controls are created and configured to fit into the form context)

   9 7 3 1 2 3 4 5 6 7 8 9 10 4 8 :