Eclipse Plug-in Developer Guide (Galileo) - MenuManager (Eclipse Platform API Specification)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse Platform
Release 3.5

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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

Field Summary

protected boolean visible
          Indicates this item is visible in its manager; true by default.

Constructor Summary

MenuManager ()
          Creates a menu manager.

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

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

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 ( 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 createMenuBar(Decorations) instead.

void dispose ()
          Disposes of this menu manager and frees all allocated SWT resources.

protected void doItemFill ( IContributionItem ci, int index)
          Call an IContributionItem's fill method with the implementation's widget.

void fill ( Composite parent)
          Fills the given composite control with controls representing this contribution item.

void fill ( CoolBar parent, int index)
          Fills the given cool bar 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.

ImageDescriptor getImageDescriptor ()
          Returns the image for this menu as an image descriptor.

Menu getMenu ()
          Returns the SWT menu control for this menu manager.

protected Item getMenuItem (int index)
          Get an item from the implementation's widget.

protected int getMenuItemCount ()
          Get the menu item count for the implementation's widget.

protected Item[] getMenuItems ()
          Get all the items from the implementation's widget.

String getMenuText ()
          Returns the text shown in the menu, potentially with a shortcut appended.

IContributionManagerOverrides getOverrides ()
          The ContributionManager implementation of this method declared on IContributionManager returns the current overrides.

IContributionManager getParent ()
          Returns the parent contribution manager of this manger.

boolean getRemoveAllWhenShown ()
          Returns whether all items should be removed when the menu is about to show, 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)
          Deprecated. this method is no longer a part of the IContributionItem API.

boolean isVisible ()
          Returns whether this contribution item is visibile within its manager.

void markDirty ()
          The MenuManager implementation of this ContributionManager method also propagates the dirty flag up the parent chain.

protected boolean menuExist ()
          Returns whether the menu control is created and not disposed.

void removeMenuListener ( IMenuListener listener)
          Removes the given menu listener from this menu.

void saveWidgetState ()
          Saves any state information of the control(s) owned by this contribution item.

void setActionDefinitionId ( String definitionId)
          Sets the action definition id of this action.

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 about to show, 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, allowItem, appendToGroup, appendToGroup, dumpStatistics, find, getItems, getSize, hasDynamicItems, indexOf, indexOf, insert, insertAfter, insertAfter, insertBefore, insertBefore, internalSetItems, isDirty, isEmpty, itemAdded, itemRemoved, prependToGroup, prependToGroup, remove, remove, removeAll, replaceItem, 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, prependToGroup, prependToGroup, remove, remove, removeAll

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

isDirty

Field Detail

visible

protected boolean visible

Indicates this item is visible in its manager; true by default.

Since:: 3.3

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

MenuManager

public MenuManager(
String text,
                   
ImageDescriptor image,
                   
String id)

Creates a menu manager with the given text, image, 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; image - the image for the menu, or null if none; id - the menu id, or null if it is to have no id
Since:: 3.4

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(
Decorations parent)

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

Parameters:: parent - the parent decorations
Returns:: the menu control
Since:: 2.1

createMenuBar

public 
Menu createMenuBar(
Shell parent)

Deprecated. use createMenuBar(Decorations) instead.

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. This implementation simply calls the createMenuBar(Decorations) method

Parameters:: parent - the parent decorations
Returns:: the menu control

dispose

public void dispose()

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

Specified by:: dispose in interface IContributionItem

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(
CoolBar parent,
                 int index)

Description copied from interface: IContributionItem

Fills the given cool bar with controls representing this contribution item. Used by CoolBarManager.

Specified by:: fill in interface IContributionItem

Parameters:: parent - the parent cool bar; index - the index where the controls are inserted, or -1 to insert at the end

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

getMenuText

public 
String getMenuText()

Returns the text shown in the menu, potentially with a shortcut appended.

Returns:: the menu text

getImageDescriptor

public 
ImageDescriptor getImageDescriptor()

Returns the image for this menu as an image descriptor.

Returns:: the image, or null if this menu has no image
Since:: 3.4

getOverrides

public 
IContributionManagerOverrides getOverrides()

Description copied from class: ContributionManager

The ContributionManager implementation of this method declared on IContributionManager returns the current overrides. If there is no overrides it lazily creates one which overrides no item state.

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 about to show, 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 IContributionItem
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(String, IContributionItem), IContributionManager.prependToGroup(String, IContributionItem)

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)

Deprecated. this method is no longer a part of the IContributionItem API.

Check if the contribution is item is a subsitute for ourselves

Parameters:: item - the contribution item
Returns:: true if give item is a substitution for ourselves

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

markDirty

public void markDirty()

The MenuManager implementation of this ContributionManager method also propagates the dirty flag up the parent chain.

Specified by:: markDirty in interface IContributionManager
Overrides:: markDirty in class ContributionManager

Since:: 3.1

menuExist

protected boolean menuExist()

Returns whether the menu control is created and not disposed.

Returns:: true if the control is created and not disposed, false otherwise
Since:: 3.4 protected, was added in 3.1 as private method

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

saveWidgetState

public void saveWidgetState()

Description copied from interface: IContributionItem

Saves any state information of the control(s) owned by this contribution item. The contribution manager calls this method before disposing of the controls.

Specified by:: saveWidgetState in interface IContributionItem

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

setRemoveAllWhenShown

public void setRemoveAllWhenShown(boolean removeAll)

Description copied from interface: IMenuManager

Sets whether all items should be removed when the menu is about to show, 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

setActionDefinitionId

public void setActionDefinitionId(
String definitionId)

Sets the action definition id of this action. This simply allows the menu item text to include a short cut if available. It can be used to notify a user of a key combination that will open a quick menu.

Parameters:: definitionId - the command definition id
Since:: 3.4

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)

getMenuItems

protected 
Item[] getMenuItems()

Get all the items from the implementation's widget.

Returns:: the menu items
Since:: 3.4

getMenuItem

protected 
Item getMenuItem(int index)

Get an item from the implementation's widget.

Parameters:: index - of the item
Returns:: the menu item
Since:: 3.4

getMenuItemCount

protected int getMenuItemCount()

Get the menu item count for the implementation's widget.

Returns:: the number of items
Since:: 3.4

doItemFill

protected void doItemFill(
IContributionItem ci,
                          int index)

Call an IContributionItem's fill method with the implementation's widget. The default is to use the Menu widget.
fill(Menu menu, int index)

Parameters:: ci - An IContributionItem whose fill() method should be called.; index - The position the fill() method should start inserting at.
Since:: 3.4

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

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

Parameters:: property - the id of the changed property

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

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse Platform
Release 3.5

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

org.eclipse.jface.action Class MenuManager

visible

MenuManager

MenuManager

MenuManager

MenuManager

addMenuListener

createContextMenu

createMenuBar

createMenuBar

dispose

fill

fill

fill

fill

findMenuUsingPath

findUsingPath

getId

getMenu

getMenuText

getImageDescriptor

getOverrides

getParent

getRemoveAllWhenShown

isDynamic

isEnabled

isGroupMarker

isSeparator

isSubstituteFor

isVisible

markDirty

menuExist

removeMenuListener

saveWidgetState

setOverrides

setParent

setRemoveAllWhenShown

setVisible

setActionDefinitionId

update

update

getMenuItems

getMenuItem

getMenuItemCount

doItemFill

update

update

updateAll

org.eclipse.jface.action
Class MenuManager