org.eclipse.ui.menus

Disclaimer: The org.eclipse.ui.menus extension point in eclipse 3.2 is only partially implemented. It currently does not support menu or toolbar definitions or extensions (the existing contributon extensions should be used for these). It is, however, the only mechanism through which 'trim' widgets can be contributed into the workbench. This section will demonstrate how to use it for this purpose.

A 'trim' widget is a control that gets sited into a location (called a 'Trim Area') on the outer boundary of the Workbench Window. The most common example is the generic 'status line' which almost all GUI's place along the bottom of the window. The extension point org.eclipse.ui.menus allows plug-ins to add views to the workbench. Plug-ins that contribute trim must register the trim in their plugin.xml file and provide  configuration information about the trim, such as its implementation class, the trim group (trim bar) that it resides in and layout information sucha s whether the trim wishes to use available 'extra' space during its layout within the trim area.

The interface for contributed trim is defined in IWorkbenchWidget, but plug-ins can (are in fact encouraged) to choose to extend the AbstractWorkbenchTrimWidget class rather than implement the interface from scratch.

For the readmetool example we've contributed a fairly naive trim widget that simply displays a string and an indication of which side the trim is currently docked on.

Let's take a look at the extension point definition used to contribute this piece of trim:

The first section of the extension (the 'group' definition) simply defines the id of the group and defines a 'location' for the group as being at the start of the 'status' group (i.e. at the beginning of the bottom trim area). The second section (the 'widget' definition) specifies the implementation 'class' of the widget and defines the 'location' of the widget as being placed within the previously defined group.

Note that in both cases the bar's 'type' is defined as trim (which is the only type currently supported).

Once you have the actual readmetool example installed, take a look at the implementation of the ReadmeTrimWidget's fill method. This is different from the other fill methods used when adding widgets into toolbars or menus in that, because trim can be dragged from one area to another, it also passes the 'side' that the trim is being placed into, allowing the implementor to tailor the widget's display based on its location by changing orientation etc. The current implementation simply changes the displayed text to reflect the current location. Also note how the 'dispose'/'fill' life-cycle is handled; there will be repeated calls to dispose and fill generated by workbench changes (i.e. changing perspectives or dragging the trim to a new side).

One thing that is not reflected in this sample's code is the reliance of the trim layout manager on the trim's proper implementation of the widget control's computeSize method. The widget must be capable of calculating and returning its 'preferred' size since this is used throughout the layout management implementation to determine, for example, how much space is needed for a particular trim area. See the SWT documentation for notes on how to correctly implement 'computeSize correctly.