EclipseCon Day 1: Tutorial: Eclipse Forms

Dejan Glozic (pictured below) and Curtus d'Entremont begin the tutorial with an introduction to the history of how Eclipse Forms came to be. Originally it was part of the PDE (Plug-in Development Environment), but so many people were interested in it and started to use the internal classes that the PDE/UA (User Assistance) team decided to polish it up and make it an API.
 

FormToolkit

The simplest form just creates a FormToolkit object, and then calls the createScrolledForm() method. The form can be placed anywhere, for example in an editor or in a view. FormToolkit takes care of color and hyperlink management, border painting, focus, and so forth.

Although it has factory methods it really only adapts existing widgets and tweaks them a little so that they look like they're part of a document. In fact it's possible to create widgets outside and use the toolkit to adapt them afterwards. This is harder than it seems because the user expects things like arrow keys, tabs, scroll up and down, etc. to work like a web page.

A flat border style is important so that the controls don't "stick out" of the document. Flashy 3d controls are fine in a dialog but look weird in a document. New operating systems like Windows XP and Mac OS X have native flat widgets, but this has to be emulated in Motif and Windows Classic.

Forms are made up by a head and a body. The head has the title and optional tool bar, and (new in 3.2) animated progress indication and message tray. It supports multicolor gradients or image backgrounds, and title wrapping.

Content is added to the form's body (which acts as the parent composite). You're still doing SWT programming, but the factory methods make it a little easier. If you have a custom control that you need border painting, you can use the setData() method to provide attributes which the Form toolkit will recognize.

Layouts

TableWrapLayout is a new SWT layout that was written to flow controls using the W3C recommended algorithm for HTML tables. It's a two pass algorithm, first computing the width and then computing the height. It flows top down. When there's extra space available, it's granted to columns according to wrap factor. It's ideal for mixing text, links, images, and so forth on the same form.

Another layout that was added with Eclipse Forms is called ColumnLayout. Use it when you have a lot of sections on a page and want to lay them out in vertical columns in such a way to cover the area in the best way. Also, if you make the area narrow, the number of columns will drop, and if you make it wider, it will add more columns. You can set the minimum and maximum number of columns.

Dejan and Curtus lead the class through a series of three examples to demonstrate major Eclipse Forms concepts such as layouts and sections.

Sections

One of the key classes in the Forms UI is ExpandableComposite. It has three key elements: a title, toggle control, and client (the body of the composite). Sections extend expandable composite to add title bar rendering, title bar client, and a separator. The section title bar can be normal sized or slimmer sized for busy pages.

FormText

FormText renders plain wrapped text with inline flowing images. Text is rendered with HTML-like tags. You can render from a String or an InputStream. FormText is a custom widget that extends Canvas and renders into it. Text that looks like links is converted into a real link. Supported HTML tags include: p (paragraph), li (list), span, img, control (to insert an SWT control) and a (hyperlink).

This is not a browser. Images, fonts, colors, controls - none of these are created as a result of markup. The client is responsible for creating them and registering them, then in markup you can reference these resources by name.

FormText is useful when the UI you want to render is not very long, or when you want to mix text, hyperlinks, and images with SWT controls, and when you want to run everywhere SWT runs. Use the embedded Browser widget instead when your UI is complex, you need animation, sound, etc. and when you're only shipping on platforms that support the Browser widget.

Advanced topics

These are things they've learned in real applications. For example color in a toolkit manager is something you really have to pay attention to. Create one toolkit and color manager for all the forms that have the same life cycle (e.g., pages in a multi-page editor). Dispose the color manager on plug-in shutdown so OS resources will be recovered.

A "managed form" adds the notion of managed states to a form to fulfill a need for lifecycle management that goes beyond the widget itself. This relationship is similar to the one between JFace Viewers and controls. Managed forms have form parts, which can be dirty (has newer data than the model) or stale (has older data than the model). Flags are cleared by committing or refreshing the form.

The Master/Details block is a pattern used all over Eclipse. It consists of a master part (something you can select) and a details part (a page book showing a different page depending on the selection in the master). Both parts are hosted in a sash that can be oriented horizontally or vertically.

Multi-page form editors

Multi-page form editors provide value-add over raw source code editors, for example when editing proprietary XML files (one page for the friendly editor, one page for the raw editor). The classic example is the PDE manifest editor. Pages and editors can be dynamically added or removed.

Multi-page editors are pretty hard to do. To make things easier, use one selection for the entire editor. Create one pop-up menu that is shared with all the pages. Save the current page and restore it when starting back up. Hook to commonly used actions such as clipboard actions, delete, and undo/redo. Delegate actions and selections are delegated to the active pages and form parts inside the editor.

In the future of the Forms API, they will try to get out of the custom widget business, initiated an effort with the SWT team to move all the custom widgets into SWT (for example Sections). Of course they have their own take on things, so it will look a little different. Also, StyledText has gained many of the features of FormText so eventually it may replace it (though it doesn't have a front-end with simple markup).

So most of the widgets will be absorbed into SWT with the rest into JFace, maybe by Eclipse 3.3.