Add Statusbar plugin to project

To the project target add a new Software Site with address https://dl.bintray.com/cybersearch2/generic/Statusbar/V1.1.0.

Add plugins to MANIFEST.MF

 au.com.cybersearch2.statusbar;bundle-version="1.1.0",
 au.com.cybersearch2.control_factory;bundle-version="1.1.0"
                 

Update postContextCreate

Create StatusBar objects in the E4 Lifecycle postContextCreate method in the following order:

• One ControlFactory.
• One StatusBar.
• One or more StatusItem(s).

One ControlFactory instance and one StatusBar instance needs to be installed in the Eclipse context before the E4 Model is created. This is because the StatusBarToolControl, incorporated in the E4 Model as a fragment, receives both instances by dependency injection.

The StatusBar needs to have at least one StatusItem for the status line to be visible. StatusItems may be aggregated into a single class, as in the Example Application, or managed independently of each other.

Use EventBroker Service

The recommended practice in Eclipse E4 to signal status updates is to use the EventBroker service. Event handlers run in the GUI Thread, which is a requirement for invoking StatusItem methods to update the status line. Otherwise, org.eclipse.e4.ui.di.UISynchronize asyncExec() should be used to run the update in the GUI Thread.

Constructor

StatusItem constructor has two parameters, a au.com.cybersearch2.controls.CustomLabelSpec object to configure it and an integer "id" parameter to position the item in the status line. The most important configuration attributes are text and image, either of which may be null. When both text and image are null, then the item will not appear on the status line.

The id range starts from zero, and goes up to, but does not include the StatusBar capacity. The default capacity is 5, but it may be set to another value by calling setCapacity() on StatusBar. However, there is a limit set to 20 for safety. The order in which items are added to StatusBar is not important and contiguous id values is not a requirement, so item ids can be kept in reserve until if and when needed.

Update Methods

The following self-evident StatusItem methods are used to update the status line

• void setText(String text)
• void setImage(Image image)
• void setLabel(String text, Image image)
• void update(CustomLabelSpec updateSpec)

For efficiency, it is best to select an update method that matches what is to be changed eg. setText() to just change text etc. The update() method allows background color and font to be changed. There is also void setWidth(int width) which sets width in number of text characters. A value of 0 indicates use default width hint.

Tooltip

A tooltip can be added to any item for one of two purposes:

1. Display text which the label has elided due to insufficient space
2. Display detailed information relating to the current status

To add a tooltip requires using the StatusItem LabelListener callback to access the underlying custom label. This callback fires for every visible item every time the status line is redrawn.

Code

import org.eclipse.swt.widgets.ToolTip;
import au.com.cybersearch2.controls.ControlTip;
import au.com.cybersearch2.controls.ControlFactory;
import au.com.cybersearch2.statusbar.LabelListener;
...             
  LabelListener labelListener = new LabelListener(){
    public void onLabelCreate(CLabel label)
    {
      ToolTip toolTip = 
        controlFactory.toolTipInstance(label.getParent());
      label.addFocusListener(new ControlTip(toolTip));
    }};
              

This code snippet shows a LabelListener which adds a tooltip to the newly created CLabel object. Note that the ControlTip wrapper handles change of tooltip focus. Use method setLabelListener() to add labelListener to the StatusItem.

Use method setsetTooltip() to set the tooltip text. Otherwise, the tooltip will echo the label text.

Context Menu

A context menu can be attached to a status line item which pops up with appropriate mouse click over the item - typically right button for right-handed users. To add a menu requires using the StatusItem LabelListener callback to access the underlying custom label. This callback fires for every visible item every time the status line is redrawn.

Code

The following code snippet is adapted from the Example Application

  StatusItem middle = 
    new StatusItem(MIDDLE_CONFIGURATION, 1);
  middle.setLabelListener(new LabelListener(){
    public void onLabelCreate(CLabel label)
    {
      Menu menu = new Menu(label);
      middle.setMenu(menu);
      label.setMenu(menu);
    }});
    ...
    MenuItem menuItem = 
      new MenuItem(middle.getMenu(), SWT.PUSH);
             

The anonymous LabelListener here creates a Menu object passing the newly created CLabel object to the constructor. StatusItem contains a Menu field for convenience.