org.eclipse.jface.action-api
org.eclipse.jface.action

Provides support for shared UI
resources such as
» menus,
» tool bars, and
» status lines.
1
Package Specification



Contribution managers
» coordinate contributions to shared UI resources such
as menus, menu bars, tool bars, and status lines.
» maintains the contributions as a dynamic list of
contribution items (IContributionItems).
Separators (Separator) can be included in contribution
lists to break up the list's visual representation.
» contribution lists can be organized into named groups
via special group markers (GroupMarker) to facilitate
programatic insertion at specific positions within the
list.
Three specific contribution managers are provided:
» a hierarchical menu manager (MenuManager).
» a tool bar manager (ToolBarManager), and
» a status line manager (StatusLineManager),
2
Actions


Actions (IAction)
» are commands which can be triggered from
the UI, like the ones found in menus, toolbars,
and buttons.
Menus and tools bars are typically populated with
contribution items that delegate to actions
(ActionContributionItem).
3
IContributionItem






represents a contribution to a shared UI resource such as
a menu or tool bar.
managed by a contribution manager.
For instance,
» in a tool bar a contribution item is a tool bar button or a
separator.
» In a menu bar a contribution item is a menu, and
» in a menu a contribution item is a menu item or
separator.
can realize itself in different SWT widgets, using the
different fill methods.
can be used in different types of managers such as a
MenuBarManager, a ToolBarManager, or a
StatusLineManager.
internal api to the framework!!
4
IContributionManager




A contribution manager organizes contributions to
such UI components as menus, toolbars and
status lines.
A contribution manager keeps track of a list of
contribution items.
Each contribution item may has an optional
identifier, which can be used to retrieve items
from a manager, and for positioning items relative
to each other.
The list of contribution items can be subdivided
into named groups using special contribution
items that serve as group markers.
5
IContributionItem



fill(Composite parent)
» Fills the given composite control with controls
representing this contribution item.
fill(CoolBar | Menu | ToolBar parent, int index)
» Fills the given parent cool bar (menu, tool bar) with
controls representing this contribution item. index = -1
=> append.
boolean isDirty(), isDynamic(), isEnabled(boolean),
is/setVisible([boolean]) , isGroupMarker() ,
isSeparator()
» Returns whether this contribution item is dirty (,
dynamiv, visible in its manager,… ).
» A dynamic contribution item contributes items
conditionally, dependent on some internal state.
6





getId() :String
» return the id of this item
dispose()
» Disposes of this contribution item. Called by the parent
manager when the manager is being disposed. Clients
should not call this method directly.
saveWidgetState()
» Saves any state information of the control(s) owned by
this contribution item.
setParent(IContributionManager parent)
» Sets the parent manager of this item void
update([Strign id] )
» Updates any SWT controls cached by this contribution
item with any changes (for the given id property) which
have been made to this contribution item since the last
update.
7
ContributionItem




implements IContributionItem
constructors:
» ContributionItem([String id]) ;
IContributionManager getParent()
» Returns null if it has no contribution manager.
String toString()
8
possible implementations

Separator  IContributionItem { …
public void fill(Menu menu, int index) {
if (index >= 0) {
new MenuItem(menu, SWT.SEPARATOR, index);
} else {
new MenuItem(menu, SWT.SEPARATOR);
}
}
public void fill(ToolBar toolbar, int index) {
if (index >= 0) {
new ToolItem(toolbar, SWT.SEPARATOR, index);
} else {
new ToolItem(toolbar, SWT.SEPARATOR);
}
}
9
IContritutionManager




provides general protocol for adding, removing,
and retrieving contribution items.
provides convenience methods to contribute
actions.
should be implemented by all objects that wish to
manage contributions.
known Implementions in this package,
» MenuManager,
» ToolBarManager
» StatusLineManager
10
IContributionManager

item management
» add items :
» add(IContributionItem | Action )
» append/prependToGroup(String groupName,
IAction | IContributionItem )
– append or prepend the given item [for the action ] to
the end [start] of the named group.
» insertAfter/Before( String itemName, IAction |
IContributionItem ).
» remove items :
» IContributinoItem remove(String id |
IContributinoItem )
» removeAll() ;
11

item query
» IContributionItem find(String id)
– Finds the contribution item with the given id.
» IContributionItem[] getItems()
– Returns all known contribution items.


» boolean isEmpty()
void markDirty() , isDirty(), update(boolean force)
» Marks this contribution manager as dirty.
» Returns whether the list of contributions is dirty.
» Updates this manager's underlying widget(s) with any changes
made to it or its items.
» Normally changes to a contribution manager merely mark it as
dirty, without updating the underlying widgets. This brings the
underlying widgets up to date with any changes.
IContributionManagerOverrides getOverrides()
» The ContributionManager implementation of this method declared
on IContributionManager returns the current overrides.
12
abstract ContributionManager




implements IContributionManager
This class
» maintains a list of contribution items and a dirty flag.
» coalesces adjacent separators, hides beginning and
ending separators.
» deals with dynamically changing sets of contributions.
» When the set of contributions does change
dynamically, the changes are propagated to the control
via the update method, which subclasses must
implement.
Note: A ContributionItem cannot be shared between
different ContributionManagers.
Construcotor: protected ContributionManager();
13








protected boolean allowItem(IContributionItem)
» allows subclasses to prevent certain items in the contributions list.
protected boolean hasDynamicItems()
» Returns whether this contribution manager contains dynamic
items.
[protected] indexOf(ICOntributinoItem | String id)
insert(int index, IContributionItem item)
» Insert the item at the given index.
protected void internalSetItems(IContributionItem[] items)
» An internal method for setting the order of the contribution items.
boolean replaceItem(String id, IContributionItem newIem)
» Replaces the item of the given id with another contribution item.
setOverrides(IContributionManagerOverrides newOverrides)
» Sets the overrides for this contribution manager
protected itemAdded(IContributionItem item)
, itemRemoved(IContributionItem item)
» The given item was added/removed to/from the list of
contributions. mark the manager as dirty and updates the number
of dynamic items, and the memento.
14
Interface IContributionManagerOverrides






used by IContributionItem to determine if the values for
certain properties have been overriden by their manager.
» This interface is internal to the framework.
Method summary
Integer getAccelerator(IContributionItem item),
String getAcceleratorText(IContributionItem item),
String getText(IContributionItem item)
» not intended to be called outside of the workbench.
» deprecated in 3.1.
Boolean getEnabled(IContributionItem item)
» Boolean.TRUE if the given contribution item should be
enabled,
» Boolean.FALSE if the item should be disabled, and
» null if the item may determine its own enablement.
15
IAction






An action represents the non-UI side of a command which
can be triggered by the end user.
Actions are typically associated with buttons, menu items,
and items in tool bars.
The controls for a command are built by some container,
which furnished the context where these controls appear
and configures them with data from properties declared
by the action.
When the end user triggers the command via its control,
the action's run method is invoked to do the real work.
Actions support a predefined set of properties (and
possibly others as well).
Clients of an action may register property change
listeners so that they get notified whenever the value of a
property changes.
16


Clients should subclass the abstract base class
Action to define concrete actions rather than
implementing IAction from scratch.
This interface exists only to define the API for
actions. It is not intended to be implemented by
clients.
17
IMenuManager





IContributionManager, IContributionItem
provides protocol for managing contributions to a
menu bar and its sub menus.
An IMenuManager is also an IContributionItem,
allowing sub-menus to be nested in parent
menus.
internal to the framework; not to be implemented
outside the framework.
concrete menu manager implementation
» MenuManager.
18
IMenuManager




MenuEvent source
» add/removeMenuListener(MenuListner).
IMenuManager findMenuUsingPath(String path)
IContributionItem findUsingPath(String path)
» Finds the contribution item at the given path.
» Finds the manager for the menu at the given path.
» path format: item_id (“/” item_id)* .
boolean get/setRemoveAllWhenShown(boolean)
» Returns whether all items should be removed when
the menu is about to show, but before notifying menu
listeners. The default is false.
19
MenuManager




extends ContributionManager (IMenuManager )
A menu manager realizes itself and its items in a
menu control; either as
» a menu bar,
» a sub-menu, or
» a context menu.
This class may be instantiated; it may also be
subclassed.
Constructors:
» MenuManager([String text [, String id]])
– Creates a menu manager with the given text and id.
20



Menu createContextMenu(Control parent)
» Creates and returns an SWT context menu
control for this menu, and installs all registered
contributions.
Menu createMenuBar(Decorations parent)
» Creates and returns an SWT menu bar control
for this menu, for use in the given Decorations,
and installs all registered contributions.
Menu createMenuBar(Shell parent)
» Deprecated. use (2) instead.
21


Menu getMenu()
» Returns the SWT menu control for this menu
manager.
String getMenuText()
» Returns the text shown in the menu.
22