1

org.eclipse.jface.action-api

Provides support for shared UI resources such as

» menus,

» tool bars, and

» status lines.

org.eclipse.jface.action

2

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),

3

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).

4

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!!

5

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.

6

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.

7

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.

8

ContributionItem implements IContributionItem constructors:

» ContributionItem([String id]) ; IContributionManager getParent()

» Returns null if it has no contribution manager. String toString()

9

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); } }

10

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

11

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() ;

12

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.

13

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();

14

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.

15

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. 

16

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.

17

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.

18

IMenuManager IIontr ut onI n rib i a age ,

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.

19

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.

20

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.

21

 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.

22

 Menu getMenu()» Returns the SWT menu control for this menu

manager.  String getMenuText()

» Returns the text shown in the menu.