UI Forms enhancements in release 3.3

Dejan Glozic and Kimberley Peter, 01/22/2007


The document is meant to enumerate various enhancements that will be available in Eclipse Platform release 3.3 from milestone 5. The readers are assumed to be familiar with Forms in general and have some working experience with them. If that is not the case, a good place to start would be Eclipse article: Eclipse Forms: Rich UI for Rich Client Applications as well as online documentation.

Most of the features listed in this document will be available in the integration builds leading to M5 and can be used with the caveat that there is a small change that APIs can change before they are frozen in the M5 stable build. We make these changes only if absolutely necessary and not without the prior warning on the mailing list.

Changes related to forms heading

The majority of changes in 3.3 are related to the way forms heading is handled. Much more can be done now in the heading and the changes that were first introduced in 3.2 are clarified and evolved further.

Title rendering

As before, the heading area is initially rendered using the overall background color of the form. Clients still have an option to decorate this area using two mutually exclusive approaches: by providing a background image or by providing an array of colors to render a gradient. However, either approach is problematic when it comes to making the design hold on all the platforms and windowing systems Eclipse can run on. For this reason, we have elected to provide one combination of colors for title background rendering that will work well everywhere. The color used to render the title are stored in the FormColors class under the following keys (defined in IFormColors interface):

These colors are computed by starting from system colors as provided by SWT, then blending them with the background at various degrees depending on the windowing system/skin employed. They are guaranteed to work well everywhere Eclipse runs, including accessibility use cases such as 'high contrast black' and similar. Nevertheless, in order to turn this rendering on, you need to call FormToolkit.decorateFormHeading(Form).

The decision to use the provided rendering should mostly depend on what is in the header of your form. If all you do is set the title, you should probably leave the form without it. If, on the other hand, you use heading tool bar, heading client, or use new message handling, it may be beneficial to decorate the title area in a stronger way using the provided method.

Layout changes

As first introduced in 3.2, forms can now have either one or two-row header. As before, it is the head client that causes the form to switch to the two rows. However, while in 3.2 head client was position on the same raw as the title, in 3.3 head client is pushed to the second row. Tool bar now stays in the same raw as the title all the time. This change is a side-effect of the changes in message handling. There is nothing you need to do to react to the change, but it will affect your forms if you chose to take advantage of the 3.2 API. Since the head client has the entire second row for itself, this will be a good thing in most cases.

Although we just claimed that tool bar stays on the same row, there is actually an exception. A new API Form.setToolBarVerticalAlignment(int) allows for setting the alignment to SWT.BOTTOM and therefore placing the tool bar on the second row. By default, this setting is SWT.TOP. If you know that the head client will not occupy the entire width of the space it has for itself, you can push the tool bar down to be closer to the form body.

Message handling

In 3.2, we introduced methods to show typed messages in form heading. The messages of types defined in org.eclipse.jface.dialogs.IMessageProvider were shown in an animated tray that would overlap the portion of the header when visible. We have decided that in many situations the message may be obstructing the useful widgets. If the problem is caused by the controls in the head client, the message tray would obstruct the very controls that are the cause of the message's appearance.

In 3.3, the message is now shown next to the title text. In the normal layout, it will use the area between the title and the tool bar (if used) or the right edge of the header. As before title text will wrap if there is not enough space to display it on one row. In contrast, message text will shrink and replace portion of the text with ellipses (...). The full text will be available as a tool tip (similar to other places in the workbench).

In addition to showing the text of the message, the image appropriate for the message type (error, warning, information) will be shown before the title. If there is an image already, it will replace the image until the message is reset. The text of the message will also indicate the message type. We have chosen fixed system colors (SWT.COLOR_RED for errors and SWT.COLOR_DARK_YELLOW for warnings) because they work equally well on all windowing systems and color combinations we tested.

By default, messages are rendered as static text. If a hyperlink handler is added to Form using the new API Form.addMessageHyperlinkListener(IHyperlinkListener), the message text will be rendered using a hyperlink and the handler will be notified about its standard hyperlink events.

Also see the section on message manager below.

Image priority

The area to the left of the title (in LTR locales) is reserved for the form image. This area is only used if the image needs to be displayed. In 3.3, this area is shared by three potential image groups, in increasing priority:

  1. No image
  2. Title image set using Form.setImage(Image) API
  3. Message image (error, warning, information) when message is set
  4. Busy animation when Form.setBusy(true) is called

The appearance of image of any priority when the image of lower priority is not already present will cause the form to reflow. In extreme cases, the reduced space to render the title may cause the title to wrap, pushing the form body down. Keep this in mind if layout stability is important to you.

Drop-down menu

In addition to the tool bar manager, a new menu manager has been added to forms in 3.3. It is accessible through the new API Form.getMenuManager(). When this manager is not empty, a drop-down arrow will appear next to the title bar and clicking on it will open the managed menu. The same menu will also available as a pop-up menu anywhere on the title and the title image.

Drag and drop support

There are use cases when form title represents an object that other workbench parts can interact with. In 3.3, we added the ability to support dragging of the title into these targets, as well as having the title serve as a drop target for the compatible objects. New APIs Form.addDragSupport and Form.addDropSupport are added to handle this scenario.

When drag and drop support is activated by using the new APIs, title area is rendered differently. A border is painted around the title in two colors: moderately dark when the mouse is in the vicinity of the title, and dark when it is directly over it. We added this visual feedback to indicate the user that the title can be manipulated directly. The colors for this indication are part of OS/skin dependent color computation and shows well on all the platforms we tested it on.

Changes related to sections

New colors

A new color computation algorithm is used for all colors allocated by FormColors class. In addition, rendering of sections when TITLE_BAR style is used has been slightly revised. Section headers are now using the same color as the form title, which is also applied to the toggle button.

Section title bar rendering when text client is present

When some sections on a page have text client (a control that can be placed in the section title bar on the right), two problems arise:

  1. Sections that use TITLE_BAR style have the envelope and the gradient painted to include the text client, causing the title bar to be taller
  2. Taller title bar pushes description and/or the section client down

Starting from release 3.3 M5, this problem has been addressed in two steps:

  1. Gradient and envelope for the sections using the TITLE_BAR style are now painted without taking text client into account. This results in a uniform decoration height that is only controlled by the chosen font for the title text.
  2. The description and/or the section body are still pushed down to accommodate the text client. However, it is possible to use public variables ExpandableComposite.clientVerticalSpacing and ExpandableComposite.descriptionVerticalSpacing to compensate for the difference so that the rest of the content in side-by-side sections lines up.

Since the difference between text and text client heights is dynamic, it is not possible to pick a 'magic number' to correct the vertical alignment issues in a portable way. For that reason, a new method has been added to ExpandableComposite - getTextClientHeightDifference(). This method will compute the currently valid difference that can be applied as described above. Note that making modifications to the text client or changing the text font invalidates this value and the method must be called again.

The following sample code shows the application of this method for the picture below:

		Section s1 = createTableSection(form, toolkit, "First Table Section", true);
		Section s2 = createTableSection(form, toolkit, "Second Table Section", false);
		s2.descriptionVerticalSpacing += s1.getTextClientHeightDifference();

As a result, the description of the section s2 has been pushed down to compensate for the tool bar set as a text client of the section s1:


Shared-header form editor

In most implementations of the multi-page form editor, each page contained a separate form with its own title and other heading controls. There is a use case for an editor that has multiple pages with one fixed header. In order to support this use case, a new class has been added in 3.3 called SharedHeaderFormEditor. This class extends FormEditor and configures is such that the tabbed folder containing pages is placed inside a managed form's body, leaving the heading unaffected by page changes.

The common header is configured by extending the class and implementing the protected method createHeaderContents(IManagedForm headerForm). The header form is included in the life cycle management of the editor (refresh, commit etc.). For this reason, it is recommended to wrap the head client in an IFormPart and register it with the header form in case head client is used. This will ensure that the controls in the head client that can make the editor dirty are included in the life cycle management.

Since the header form takes responsibility of the common header, form pages that are normally added to this editor must not have the heading themselves. This is easily accomplished by not setting the title on individual pages' forms or otherwise calling any other method related to the heading.

Message Manager

A new manager is now accessible via the IManagedForm interface that makes message management in forms much easier. The manager is available as an interface (IMessageManager) and has the following roles:

  1. Manages multiple messages - shows a summary message with the highest type, as well as details as a tool tip
  2. Provides for adding and removing messages associated with controls on the form

The message manager uses JFace support for control decoration to render the appropriate image near controls that have messages associated with them. What makes message manager convenient is that clients only manipulate messages and message types, while the manager handles control decoration at the SWT/JFace level.

Clients who want to take advantage of this new facility should refrain from setting messages directly using Form APIs and use the manager instead. There are methods to add and remove general purpose messages, as well as those associated with controls. The manager will keep track of all of them and provide a suitable summary message in the header. Clients who use form-based multi-page editors already have managed form instances in the pages. All you need to do is ask for the manager instance and use it.

If message label is configured to be a hyperlink, href property of the hyperlink event is set to be an array of IMessage objects that form the summary message. This array is used internally to compose the tool tip text. Clients can also use this information to do interesting things. For example, a lightweight window can be shown with individual messages as hyperlinks, allowing users to go to each one (this feature makes much more sense for shared-header editor described earlier, where the error may have occurred on a currently inactive page). Another possible use of this data can be to offer the user to automatically fix the errors if possible.

API deprecation and cleanup

The most significant change in 3.3 is that we moved all the color constants into IFormColors interface. The existing constants in FormColors are now deprecated since they are just pointing at the matching constants in IFormColors.

All new APIs are marked using '@since 3.3' in javadoc. Go to the source code in the Eclipse builds for details.