org.eclipse.jface.action
Class MenuManager

java.lang.Object
  |
  +--org.eclipse.jface.action.ContributionManager
        |
        +--org.eclipse.jface.action.MenuManager

All Implemented Interfaces:

IContributionItem, IContributionManager, IMenuManager

public class MenuManager

extends ContributionManager

implements IMenuManager

A menu manager is a contribution manager which 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.

Constructor Summary

MenuManager()
Creates a menu manager.

MenuManager(String text)
Creates a menu manager with the given text.

MenuManager(String text, String id)
Creates a menu manager with the given text and id.

Method Summary

void	addMenuListener(IMenuListener listener) Adds a menu listener to this menu.
Menu	createContextMenu(Control parent) Creates and returns an SWT context menu control for this menu, and installs all registered contributions.
Menu	createMenuBar(Shell parent) Creates and returns an SWT menu bar control for this menu, for use in the given shell, and installs all registered contributions.
void	dispose() Disposes of this menu manager and frees all allocated SWT resources.
void	fill(Composite parent) Fills the given composite control with controls representing this contribution item.
void	fill(Menu parent, int index) Fills the given menu with controls representing this contribution item.
void	fill(ToolBar parent, int index) Fills the given tool bar with controls representing this contribution item.
IMenuManager	findMenuUsingPath(String path) Finds the manager for the menu at the given path.
IContributionItem	findUsingPath(String path) Finds the contribution item at the given path.
String	getId() Returns the menu id.
Menu	getMenu() Returns the SWT menu control for this menu manager.
IContributionManagerOverrides	getOverrides() Returns the overrides for the items of this manager.
IContributionManager	getParent() Returns the parent contribution manager of this manger.
boolean	getRemoveAllWhenShown() Returns whether all items should be removed when the menu is first shown, but before notifying menu listeners.
boolean	isDynamic() Returns whether this contribution item is dynamic.
boolean	isEnabled() Returns whether this menu should be enabled or not.
boolean	isGroupMarker() Returns whether this contribution item is a group marker.
boolean	isSeparator() Returns whether this contribution item is a separator.
boolean	isSubstituteFor(IContributionItem item)
boolean	isVisible() Returns whether this contribution item is visibile within its manager.
void	removeMenuListener(IMenuListener listener) Removes the given menu listener from this menu.
void	setOverrides(IContributionManagerOverrides newOverrides) Sets the overrides for this contribution manager
void	setParent(IContributionManager manager) Sets the parent manager of this item
void	setRemoveAllWhenShown(boolean removeAll) Sets whether all items should be removed when the menu is first shown, but before notifying menu listeners.
void	setVisible(boolean visible) Sets whether this contribution item is visibile within its manager.
void	update() Updates any SWT controls cached by this contribution item with any changes which have been made to this contribution item since the last update.
void	update(boolean force) The MenuManager implementation of this IContributionManager updates this menu, but not any of its submenus.
protected void	update(boolean force, boolean recursive) Incrementally builds the menu from the contribution items.
void	update(String property) Updates any SWT controls cached by this contribution item with changes for the the given property.
void	updateAll(boolean force) Incrementally builds the menu from the contribution items, and does so recursively for all submenus.

Methods inherited from class org.eclipse.jface.action.ContributionManager

add, add, appendToGroup, appendToGroup, dumpStatistics, find, getItems, hasDynamicItems, insertAfter, insertAfter, insertBefore, insertBefore, isDirty, isEmpty, markDirty, prependToGroup, prependToGroup, remove, remove, removeAll, setDirty

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.eclipse.jface.action.IContributionManager

add, add, appendToGroup, appendToGroup, find, getItems, insertAfter, insertAfter, insertBefore, insertBefore, isDirty, isEmpty, markDirty, prependToGroup, prependToGroup, remove, remove, removeAll

Constructor Detail

MenuManager

public MenuManager()

Creates a menu manager. The text and id are null. Typically used for creating a context menu, where it doesn't need to be referred to by id.

MenuManager

public MenuManager(String text)

Creates a menu manager with the given text. The id of the menu is null. Typically used for creating a sub-menu, where it doesn't need to be referred to by id.

Parameters:

text - the text for the menu, or null if none

MenuManager

public MenuManager(String text,
                   String id)

Creates a menu manager with the given text and id. Typically used for creating a sub-menu, where it needs to be referred to by id.

Parameters:

text - the text for the menu, or null if none

id - the menu id, or null if it is to have no id

Method Detail

addMenuListener

public void addMenuListener(IMenuListener listener)

Description copied from interface: IMenuManager

Adds a menu listener to this menu. Has no effect if an identical listener is already registered.

Specified by:

addMenuListener in interface IMenuManager

Parameters:

listener - a menu listener

createContextMenu

public Menu createContextMenu(Control parent)

Creates and returns an SWT context menu control for this menu, and installs all registered contributions. Does not create a new control if one already exists.

Note that the menu is not expected to be dynamic.

Parameters:

parent - the parent control

Returns:

the menu control

createMenuBar

public Menu createMenuBar(Shell parent)

Creates and returns an SWT menu bar control for this menu, for use in the given shell, and installs all registered contributions. Does not create a new control if one already exists.

Parameters:

parent - the parent shell

Returns:

the menu control

dispose

public void dispose()

Disposes of this menu manager and frees all allocated SWT resources. Note that this method does not clean up references between this menu manager and its associated contribution items. Use removeAll for that purpose.

fill

public void fill(Composite parent)

Description copied from interface: IContributionItem

Fills the given composite control with controls representing this contribution item. Used by StatusLineManager.

Specified by:

fill in interface IContributionItem

Parameters:

parent - the parent control

fill

public void fill(Menu parent,
                 int index)

Description copied from interface: IContributionItem

Fills the given menu with controls representing this contribution item. Used by MenuManager.

Specified by:

fill in interface IContributionItem

Parameters:

parent - the parent menu

index - the index where the controls are inserted, or -1 to insert at the end

fill

public void fill(ToolBar parent,
                 int index)

Description copied from interface: IContributionItem

Fills the given tool bar with controls representing this contribution item. Used by ToolBarManager.

Specified by:

fill in interface IContributionItem

Parameters:

parent - the parent tool bar

index - the index where the controls are inserted, or -1 to insert at the end

findMenuUsingPath

public IMenuManager findMenuUsingPath(String path)

Description copied from interface: IMenuManager

Finds the manager for the menu at the given path. A path consists of contribution item ids separated by the separator character. The path separator character is '/'.

Convenience for findUsingPath(path) which extracts an IMenuManager if possible.

Specified by:

findMenuUsingPath in interface IMenuManager

Parameters:

path - the path string

Returns:

the menu contribution item, or null if there is no such contribution item or if the item does not have an associated menu manager

findUsingPath

public IContributionItem findUsingPath(String path)

Description copied from interface: IMenuManager

Finds the contribution item at the given path. A path consists of contribution item ids separated by the separator character. The path separator character is '/'.

Specified by:

findUsingPath in interface IMenuManager

Parameters:

path - the path string

Returns:

the contribution item, or null if there is no such contribution item

getId

public String getId()

Returns the menu id. The menu id is used when creating a contribution item for adding this menu as a sub menu of another.

Specified by:

getId in interface IContributionItem

Returns:

the menu id

getMenu

public Menu getMenu()

Returns the SWT menu control for this menu manager.

Returns:

the menu control

getOverrides

public IContributionManagerOverrides getOverrides()

Description copied from interface: IContributionManager

Returns the overrides for the items of this manager.

Specified by:

getOverrides in interface IContributionManager

Overrides:

getOverrides in class ContributionManager

Returns:

the overrides for the items of this manager

getParent

public IContributionManager getParent()

Returns the parent contribution manager of this manger.

Returns:

the parent contribution manager

Since:

2.0

getRemoveAllWhenShown

public boolean getRemoveAllWhenShown()

Description copied from interface: IMenuManager

Returns whether all items should be removed when the menu is first shown, but before notifying menu listeners. The default is false.

Specified by:

getRemoveAllWhenShown in interface IMenuManager

Returns:

true if all items should be removed when shown, false if not

isDynamic

public boolean isDynamic()

Description copied from interface: IContributionItem

Returns whether this contribution item is dynamic. A dynamic contribution item contributes items conditionally, dependent on some internal state.

Specified by:

isDynamic in interface IContributionItem

Returns:

true if this item is dynamic, and false for normal items

isEnabled

public boolean isEnabled()

Returns whether this menu should be enabled or not. Used to enable the menu item containing this menu when it is realized as a sub-menu.

The default implementation of this framework method returns true. Subclasses may reimplement.

Specified by:

isEnabled in interface IMenuManager

Returns:

true if enabled, and false if disabled

isGroupMarker

public boolean isGroupMarker()

Description copied from interface: IContributionItem

Returns whether this contribution item is a group marker. This information is used when adding items to a group.

Specified by:

isGroupMarker in interface IContributionItem

Returns:

true if this item is a group marker, and false for normal items

See Also:

GroupMarker, IContributionManager.appendToGroup(java.lang.String, org.eclipse.jface.action.IAction), IContributionManager.prependToGroup(java.lang.String, org.eclipse.jface.action.IAction)

isSeparator

public boolean isSeparator()

Description copied from interface: IContributionItem

Returns whether this contribution item is a separator. This information is used to enable hiding of unnecessary separators.

Specified by:

isSeparator in interface IContributionItem

Returns:

true if this item is a separator, and false for normal items

See Also:

Separator

isSubstituteFor

public boolean isSubstituteFor(IContributionItem item)

isVisible

public boolean isVisible()

Description copied from interface: IContributionItem

Returns whether this contribution item is visibile within its manager.

Specified by:

isVisible in interface IContributionItem

Returns:

true if this item is visible, and false otherwise

removeMenuListener

public void removeMenuListener(IMenuListener listener)

Description copied from interface: IMenuManager

Removes the given menu listener from this menu. Has no effect if an identical listener is not registered.

Specified by:

removeMenuListener in interface IMenuManager

Parameters:

listener - the menu listener

setRemoveAllWhenShown

public void setRemoveAllWhenShown(boolean removeAll)

Description copied from interface: IMenuManager

Sets whether all items should be removed when the menu is first shown, but before notifying menu listeners.

Specified by:

setRemoveAllWhenShown in interface IMenuManager

Parameters:

removeAll - true if all items should be removed when shown, false if not

setVisible

public void setVisible(boolean visible)

Description copied from interface: IContributionItem

Sets whether this contribution item is visibile within its manager.

Specified by:

setVisible in interface IContributionItem

Parameters:

visible - true if this item should be visible, and false otherwise

setOverrides

public void setOverrides(IContributionManagerOverrides newOverrides)

Sets the overrides for this contribution manager

Overrides:

setOverrides in class ContributionManager

Parameters:

newOverrides - the overrides for the items of this manager

Since:

2.0

setParent

public void setParent(IContributionManager manager)

Description copied from interface: IContributionItem

Sets the parent manager of this item

Specified by:

setParent in interface IContributionItem

Parameters:

manager - the parent contribution manager

update

public void update()

Description copied from interface: IContributionItem

Updates any SWT controls cached by this contribution item with any changes which have been made to this contribution item since the last update. Called by contribution manager update methods.

Specified by:

update in interface IContributionItem

update

public void update(boolean force)

The MenuManager implementation of this IContributionManager updates this menu, but not any of its submenus.

Specified by:

update in interface IContributionManager

Parameters:

force - true means update even if not dirty, and false for normal incremental updating

See Also:

updateAll(boolean)

update

public void update(String property)

Description copied from interface: IContributionItem

Updates any SWT controls cached by this contribution item with changes for the the given property.

Specified by:

update in interface IContributionItem

update

protected void update(boolean force,
                      boolean recursive)

Incrementally builds the menu from the contribution items. This method leaves out double separators and separators in the first or last position.

Parameters:

force - true means update even if not dirty, and false for normal incremental updating

recursive - true means recursively update all submenus, and false means just this menu

updateAll

public void updateAll(boolean force)

Description copied from interface: IMenuManager

Incrementally builds the menu from the contribution items, and does so recursively for all submenus.

Specified by:

updateAll in interface IMenuManager

Parameters:

force - true means update even if not dirty, and false for normal incremental updating