oracle.ide.controller

Class MenuManager

java.lang.Object

oracle.ide.controller.MenuManager

Direct Known Subclasses:

ContextMenu, Menubar

public abstract class MenuManager
extends java.lang.Object

Manages the IDE's menus. The MenuManager can be used to retrieve, create, insert, and remove menus and menu items. Extension writers should use this API when working with menus in order to have a complete integration with the IDE's menu management.

This class should not be subclassed by extension writers.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	MenuManager.CustomMenu

Method Summary

Methods

Modifier and Type	Method and Description
void	add(java.awt.Component child) Appends a component into the MenuManager's GUI.
void	add(java.awt.Component child, float sectionId) Adds a component into the MenuManager's GUI.
void	add(java.awt.Component child, javax.swing.JMenu parent) Appends a component into the given parent.
void	add(java.awt.Component child, javax.swing.JMenu parent, float sectionId) Appends a component into the given parent.
void	addMenuFilter(MenuFilter menuFilter) Adds a menu filter to the menu manager.
protected void	addMenuManagerAsListener(java.awt.Component component)
void	applyGlobalFilter(MenuFilter filter) Applies a filter globally.
protected void	applyGlobalFilterImpl(MenuFilter filter) Implements the applyGlobalFilter(MenuFilter) method.
void	clearGlobalFilter() Clears the currently applied global filter, resetting menus to their default state.
protected void	clearGlobalFilterImpl() Implements the clearGlobalFilter() method.
boolean	contains(java.awt.Component component)
javax.swing.JMenu	createMenu(java.lang.String caption, float weight) Creates a new menu suitable for insertion into JDeveloper's top level menu bar.
javax.swing.JMenu	createMenu(java.lang.String caption, float weight, float addinSectionId) Creates a new menu suitable for insertion into JDeveloper's top level menu bar.
javax.swing.JMenu	createMenu(java.lang.String caption, java.lang.Integer mnemonic) Creates a new menu suitable for insertion into JDeveloper's top level menu bar.
javax.swing.JMenu	createMenu(java.lang.String caption, java.lang.Integer mnemonic, float weight) Creates a new menu suitable for insertion into JDeveloper's top level menu bar.
javax.swing.JMenu	createMenu(java.lang.String caption, java.lang.Integer mnemonic, float weight, float addinSectionId) Creates a new menu suitable for insertion into JDeveloper's top level menu bar.
javax.swing.JMenuItem	createMenuItem(ToggleAction action) Creates a new menu item for the supplied ToggleAction.
javax.swing.JMenuItem	createMenuItem(ToggleAction action, float menuWeight) Creates a new menu item for the supplied ToggleAction with the supplied menu weight.
javax.swing.JMenu	createSubMenu(java.lang.String caption, java.lang.Integer mnemonic) Creates a new menu suitable for insertion into JDeveloper's menu bar or into another menu.
javax.swing.JMenu	createSubMenu(java.lang.String caption, java.lang.Integer mnemonic, float weight) Creates a new menu suitable for insertion into JDeveloper's menu bar or into another menu.
javax.swing.JMenu	createSubMenu(java.lang.String caption, java.lang.Integer mnemonic, float weight, float sectionId) Creates a new menu suitable for insertion into JDeveloper's menu bar or into another menu.
java.awt.Component	getChildById(java.awt.Container parent, int commandId) Returns the child with the specified command id.
protected java.awt.event.ContainerListener	getContainerListener() Gets the MenuManager's container listener.
abstract java.awt.Container	getGUI(boolean create) Gets the MenuManager's GUI.
java.lang.String	getId(java.awt.Component menuComponent) Returns the id of the specified menu component.
int	getIndexOfChild(java.awt.Container parent, java.awt.Component child) Returns the index of the specified component.
int	getIndexOfCommandId(java.awt.Container parent, int commandId) Returns the index of the specified command.
static javax.swing.JMenu	getJMenu(java.lang.String id) Gets the main menu with the specified ID.
int	getKeyboardMnemonic(java.lang.String menuLabel, java.lang.Integer mnemonic) Returns an int that corresponds to a VK_xxx key code defined in KeyEvent and maps to a single key on the keyboard.
static java.lang.String	getMenuId(javax.swing.JMenu menu) Returns the identifier for a menu previously set by setMenuId(JMenu,String) or registered using the putJMenu(String,JMenu) method.
protected boolean	isMenuComponentAccepted(java.awt.Component component) Returns true if all registered MenuFilters accept the specified menu component.
protected static boolean	isMenuComponentAccepted(java.awt.Component component, java.util.Collection<MenuFilter> filters)
java.lang.Float	lookupMenuSection(java.lang.String menuId, java.lang.String sectionId) Retrieves the section value for a specific menu section in a given menu.
static void	putJMenu(java.lang.String id, javax.swing.JMenu menu) Puts the main menu with the specified ID.
protected void	registerFilterContainerListener(javax.swing.JMenu menu)
void	remove(java.awt.Component child) Removes a child from the MenuManager's GUI.
void	remove(java.awt.Component child, javax.swing.JMenu parent) Removes a child from the given parent.
void	removeAll(javax.swing.JMenu parent)
void	removeMenuFilter(MenuFilter menuFilter) Removes a menu filter from the menu manager.
protected void	removeMenuManagerAsListener(java.awt.Component component)
void	removeMenuManagerMenuListener(javax.swing.JMenu menu) INTERNAL method.
void	resolveMnemonicsForMenuItemsInSection(javax.swing.JMenu menu, float sectionID) Ensures that the mnemonics for the menu items in the specified section are resolved before the menu is shown.
static void	setMenuId(javax.swing.JMenu menu, java.lang.String id) Sets the identifier for a menu.
protected void	setWeight(java.awt.Component component, float weight, java.lang.String weightId) Checks to see if section Id is the default section, if so, only replace the client property if child is unset.
void	sortContainer(java.awt.Container container)
void	sortSectionByName(javax.swing.JComponent menu, float sectionID) Sorts the commands in the specified section alphabetically by the menu item name, rather than sorting by weight.
void	storeMenuSection(java.lang.String menuId, java.lang.String sectionId, java.lang.Float section) Stores a section value for a menu section in a specific menu.
protected void	unregisterFilterContainerListener(javax.swing.JMenu menu)

Methods inherited from class java.lang.Object

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

Method Detail

addMenuFilter

public void addMenuFilter(MenuFilter menuFilter)

Adds a menu filter to the menu manager. Menu components which do not pass the filter will not be displayed in the menu structure.

Note that a menu filter added via Ide.getMenubar().addMenuFilter() will be applied to all context menus as well.

Parameters:

menuFilter - a menu filter. Must not be null.

Since:

11.0

removeMenuFilter

public void removeMenuFilter(MenuFilter menuFilter)

Removes a menu filter from the menu manager.

Parameters:

menuFilter - a filter previously added using addMenuFilter(MenuFilter). Note that a menu filter removed via Ide.getMenubar().addMenuFilter() will be removed from all context menus as well.

Since:

11.0

applyGlobalFilter

public final void applyGlobalFilter(MenuFilter filter)

Applies a filter globally. The filter will apply to the main menu and any context menus. The existing menu bar will immediately be rebuilt to include only menu components which pass the filter.

Only one filter can be in effect at any given time. If you attempt to apply a global filter while a filter is already in effect, the previous filter will be canceled.

This method primarily exists to support the ability for layouts to control menus. See the oracle.ide.layout.Layouts#registerMenuFilter(oracle.ide.layout.Layout,MenuFilter) method for details.

Parameters:

filter - a filter to apply globally. Must not be null.

Throws:

java.lang.IllegalStateException - if a filter is already in effect.

java.lang.NullPointerException - if filter is null.

Since:

11.0

See Also:

clearGlobalFilter()

applyGlobalFilterImpl

protected void applyGlobalFilterImpl(MenuFilter filter)

Implements the applyGlobalFilter(MenuFilter) method.

This implementation does nothing.

Parameters:

filter - the filter to apply.

clearGlobalFilter

public final void clearGlobalFilter()

Clears the currently applied global filter, resetting menus to their default state.

You may call this method safely even if no filter is currently applied.

Since:

11.0

clearGlobalFilterImpl

protected void clearGlobalFilterImpl()

Implements the clearGlobalFilter() method.

This implementation does nothing.

lookupMenuSection

public java.lang.Float lookupMenuSection(java.lang.String menuId,
                                java.lang.String sectionId)

Retrieves the section value for a specific menu section in a given menu. Use this method to lookup a section for a menu or menu item that is defined in an extension manifest.

Parameters:

menuId - the id that identifies the menu

sectionId - the id used to identify the section

Returns:

the Float mapped to the section or SECTION_UNDEFINED if the menu or section ID was not found

storeMenuSection

public void storeMenuSection(java.lang.String menuId,
                    java.lang.String sectionId,
                    java.lang.Float section)

Stores a section value for a menu section in a specific menu. Use this method to store section values for a menu that is defined in an extension manifest.

Note: Although this method is public, it is not intended to be called except by the JSR198 implementation classes.

Parameters:

menuId - the id that identifies the menu; should be non-null

sectionId - the id used to identify the section; should be non-null

setMenuId

public static final void setMenuId(javax.swing.JMenu menu,
             java.lang.String id)

Sets the identifier for a menu. This allows the menu to be referenced in a menu customization hook.

Parameters:

menu - a menu instance. Must not be null.

id - an identifier for the menu. If null, any existing identifier for the menu is cleared.

Since:

11.0

getMenuId

public static final java.lang.String getMenuId(javax.swing.JMenu menu)

Returns the identifier for a menu previously set by setMenuId(JMenu,String) or registered using the putJMenu(String,JMenu) method.

Parameters:

menu - a menu, must not be null.

Returns:

the identifier for the menu, or null if it has no identifier.

Since:

11.0

isMenuComponentAccepted

protected final boolean isMenuComponentAccepted(java.awt.Component component)

Returns true if all registered MenuFilters accept the specified menu component.

Parameters:

component - a component.

Returns:

true if all registered MenuFilters accept the component, or if component is null.

Since:

11.0

isMenuComponentAccepted

protected static final boolean isMenuComponentAccepted(java.awt.Component component,
                              java.util.Collection<MenuFilter> filters)

getJMenu

public static final javax.swing.JMenu getJMenu(java.lang.String id)

Gets the main menu with the specified ID.

putJMenu

public static final void putJMenu(java.lang.String id,
            javax.swing.JMenu menu)

Puts the main menu with the specified ID.

createMenu

public javax.swing.JMenu createMenu(java.lang.String caption,
                           java.lang.Integer mnemonic)

Creates a new menu suitable for insertion into JDeveloper's top level menu bar.

Parameters:

caption - localized string to be displayed in the bar or supermenu; value should be non-null. A mnemonic may be embedded into the string in the style of "&File".

mnemonic - the mnemonic to associate with the resulting JMenu.

Returns:

a new menu.

See Also:

JMenu

createMenu

public javax.swing.JMenu createMenu(java.lang.String caption,
                           float weight,
                           float addinSectionId)

Creates a new menu suitable for insertion into JDeveloper's top level menu bar.

Parameters:

caption - localized string to be displayed in the bar or supermenu; value should be non-null. A mnemonic may be embedded into the string in the style of "&File".

weight - a float used to indicate the menu's position in the menu bar. Menus are sorted in ascending order from the left to right.

addinSectionId - menu items which are not explicitly added to a menu section are added to this section.

Returns:

a new menu.

See Also:

JMenu

createMenu

public javax.swing.JMenu createMenu(java.lang.String caption,
                           java.lang.Integer mnemonic,
                           float weight)

Creates a new menu suitable for insertion into JDeveloper's top level menu bar.

Parameters:

caption - localized string to be displayed in the bar or supermenu; value should be non-null. A mnemonic may be embedded into the string in the style of "&File".

mnemonic - mnemonic to associate with the resulting JMenu.

weight - a float used to indicate the menu's position in the menu bar. Menus are sorted in ascending order from the left to right.

Returns:

a new menu.

See Also:

JMenu

createMenu

public javax.swing.JMenu createMenu(java.lang.String caption,
                           float weight)

Creates a new menu suitable for insertion into JDeveloper's top level menu bar.

Parameters:

caption - localized string to be displayed in the bar or supermenu; value should be non-null. A mnemonic may be embedded into the string in the style of "&File".

weight - a float used to indicate the menu's position in the menu bar. Menus are sorted in ascending order from the left to right.

Returns:

a new menu.

See Also:

JMenu

createMenu

public javax.swing.JMenu createMenu(java.lang.String caption,
                           java.lang.Integer mnemonic,
                           float weight,
                           float addinSectionId)

Creates a new menu suitable for insertion into JDeveloper's top level menu bar.

Parameters:

caption - localized string to be displayed in the bar or supermenu; value should be non-null. A mnemonic may be embedded into the string in the style of "&File".

mnemonic - mnemonic to associate with the resulting JMenu.

weight - a float used to indicate the menu's position in the menu bar. Menus are sorted in ascending order from the left to right.

addinSectionId - menu items which are not explicitly added to a menu section are added to this section.

Returns:

a new menu.

See Also:

JMenu

getKeyboardMnemonic

public int getKeyboardMnemonic(java.lang.String menuLabel,
                      java.lang.Integer mnemonic)

Returns an int that corresponds to a VK_xxx key code defined in KeyEvent and maps to a single key on the keyboard. If the menu label text has a mnemonic, that takes precedence over the suppied Integer. If neither menu label, nor mnemonic contains a valid mnemonic, KeyEvent.VK_UNDEFINED is returned.

Parameters:

menuLabel - the menu label; must not be null

mnemonic - the menu mnemonic

Returns:

a key code that corresponds to a single key on the keyboard or KeyEvent.VK_UNDEFINED if a none could be determined

See Also:

AbstractButton.setMnemonic(int)

createSubMenu

public javax.swing.JMenu createSubMenu(java.lang.String caption,
                              java.lang.Integer mnemonic)

Creates a new menu suitable for insertion into JDeveloper's menu bar or into another menu. This will add the required padding to compensate for lack of an Icon for this menu item (which is a sub menu).

Parameters:

caption - localized string to be displayed in the bar or supermenu; value should be non-null. A mnemonic may be embedded into the string in the style of "&File".

mnemonic - the mnemonic to associate with the resulting JMenu.

Returns:

a new menu.

See Also:

JMenu

createSubMenu

public javax.swing.JMenu createSubMenu(java.lang.String caption,
                              java.lang.Integer mnemonic,
                              float weight)

Creates a new menu suitable for insertion into JDeveloper's menu bar or into another menu. This will add the required padding to compensate for lack of an Icon for this menu item (which is a sub menu).

Parameters:

caption - localized string to be displayed in the bar or supermenu; value should be non-null. A mnemonic may be embedded into the string in the style of "&File".

mnemonic - mnemonic to associate with the resulting JMenu.

weight - a float used to indicate the menu's position in the menu bar. Menus are sorted in ascending order from the left to right.

Returns:

a new menu.

See Also:

JMenu

createSubMenu

public javax.swing.JMenu createSubMenu(java.lang.String caption,
                              java.lang.Integer mnemonic,
                              float weight,
                              float sectionId)

Creates a new menu suitable for insertion into JDeveloper's menu bar or into another menu. This will add the required padding to compensate for lack of an Icon for this menu item (which is a sub menu).

Parameters:

caption - localized string to be displayed in the bar or supermenu; value should be non-null. A mnemonic may be embedded into the string in the style of "&File".

mnemonic - mnemonic to associate with the resulting JMenu.

weight - a float used to indicate the menu's position in the menu bar. Menus are sorted in ascending order from the left to right.

sectionId - menu items which are not explicitly added to a menu section are added to this section.

Returns:

a new menu.

See Also:

JMenu

registerFilterContainerListener

protected void registerFilterContainerListener(javax.swing.JMenu menu)

unregisterFilterContainerListener

protected final void unregisterFilterContainerListener(javax.swing.JMenu menu)

createMenuItem

public javax.swing.JMenuItem createMenuItem(ToggleAction action)

Creates a new menu item for the supplied ToggleAction. By default, the menu weight is WEIGHT_UNDEFINED unless the action has a defined menu weight, in which case that value is used.

See Also:

ToggleAction, ToggleAction.setMenuWeight(float)

createMenuItem

public javax.swing.JMenuItem createMenuItem(ToggleAction action,
                                   float menuWeight)

Creates a new menu item for the supplied ToggleAction with the supplied menu weight. If the ToggleAction has a defined menu weight, the supplied weight overwrites it, except in the case where the supplied menu weight is MenuConstants.WEIGHT_UNDEFINED then the menu weight stored in the ToggleAction, if any, is set in the menu item.

Parameters:

action - The action for this menu item

menuWeight - The menu weight to use to sort this item when it is added to a menu

See Also:

createMenuItem(ToggleAction), ToggleAction, ToggleAction.setMenuWeight(float)

add

public void add(java.awt.Component child)

Appends a component into the MenuManager's GUI.

Parameters:

child - the child to add.

add

public void add(java.awt.Component child,
       float sectionId)

Adds a component into the MenuManager's GUI.

Parameters:

child - the child to add.

sectionId - the menu section to which to add the child. Menu sections are automatically split by JSeparators.

add

public void add(java.awt.Component child,
       javax.swing.JMenu parent)

Appends a component into the given parent.

Parameters:

child - the child to be inserted.

parent - the parent in which to insert the child.

add

public void add(java.awt.Component child,
       javax.swing.JMenu parent,
       float sectionId)

Appends a component into the given parent.

Parameters:

child - the child to add.

parent - the parent in which to insert the child.

sectionId - a float which indicates the menu section to which the child will be added. Menu sections are automatically split by JSeparators. Menu section constants are defined in the MenuConstants interface.

See Also:

MenuConstants

contains

public boolean contains(java.awt.Component component)

remove

public void remove(java.awt.Component child)

Removes a child from the MenuManager's GUI.

Parameters:

child - the child to be removed.

remove

public void remove(java.awt.Component child,
          javax.swing.JMenu parent)

Removes a child from the given parent. Behaves exactly as though parent.remove(child) were called directly.

Parameters:

child - the child to remove.

parent - the parent from which to remove the child.

removeAll

public void removeAll(javax.swing.JMenu parent)

getGUI

public abstract java.awt.Container getGUI(boolean create)

Gets the MenuManager's GUI. Typically the return value would be either a JMenuBar or a JPopupMenu, though any Container is valid.

Parameters:

create - force a creation of the GUI if it does not yet exist.

Returns:

the GUI of the MenuManager implementation.

getContainerListener

protected java.awt.event.ContainerListener getContainerListener()

Gets the MenuManager's container listener. Only intended to be used by subclasses.

Returns:

The MenuManager's container listener.

getIndexOfChild

public int getIndexOfChild(java.awt.Container parent,
                  java.awt.Component child)

Returns the index of the specified component.

Parameters:

parent - the Container to search for the child component

child - the Component to find

Returns:

an int giving the component's position, where 0 = first

getIndexOfCommandId

public int getIndexOfCommandId(java.awt.Container parent,
                      int commandId)

Returns the index of the specified command.

Parameters:

parent - the Container in which to search for the child command

commandId - the commandId to find

Returns:

an int giving the command's position, where 0 = first

getChildById

public java.awt.Component getChildById(java.awt.Container parent,
                              int commandId)

Returns the child with the specified command id.

Parameters:

parent - the Container in which to search for the child command

commandId - the command id to find

Returns:

the child Component with the specified command id, or null if no child with that id exists in the parent container.

sortSectionByName

public void sortSectionByName(javax.swing.JComponent menu,
                     float sectionID)

Sorts the commands in the specified section alphabetically by the menu item name, rather than sorting by weight.

Parameters:

menu - The menu component

sectionID - The section that contains the commands commands to sort alphabetically. If none of the commands the menu are in the specified section, the commands will be sorted in the default order.

resolveMnemonicsForMenuItemsInSection

public void resolveMnemonicsForMenuItemsInSection(javax.swing.JMenu menu,
                                         float sectionID)

Ensures that the mnemonics for the menu items in the specified section are resolved before the menu is shown.

Parameters:

menu - The menu container

sectionID - The section that contains the menu items whose mnemonics to resolve.

removeMenuManagerMenuListener

public void removeMenuManagerMenuListener(javax.swing.JMenu menu)

INTERNAL method. Do not use.

setWeight

protected void setWeight(java.awt.Component component,
             float weight,
             java.lang.String weightId)

Checks to see if section Id is the default section, if so, only replace the client property if child is unset.

sortContainer

public void sortContainer(java.awt.Container container)

addMenuManagerAsListener

protected final void addMenuManagerAsListener(java.awt.Component component)

removeMenuManagerAsListener

protected final void removeMenuManagerAsListener(java.awt.Component component)

getId

public final java.lang.String getId(java.awt.Component menuComponent)

Returns the id of the specified menu component. If the menu component is a regular menu item backed by an IdeAction, this returns the action id. If the menu component is a JMenu, this returns the id the JMenu is registered with using the getMenuId(JMenu) method.

Parameters:

menuComponent - a component to get the id of. Must not be null.

Returns:

the id of the specified component, or the empty string if it could not be determined.

Since:

11.0