#include <MenuBar.h>
Public Member Functions | |
| virtual QMenu * | addMenu (const std::string &location, QAction *pBefore=NULL)=0 |
| virtual QAction * | insertMenu (QMenu *pMenu, QMenu *pParentMenu=NULL, QAction *pBefore=NULL)=0 |
| virtual QAction * | addCommand (const std::string &location, QAction *pBefore=NULL)=0 |
| virtual QAction * | addCommand (const std::string &location, const std::string &shortcutContext, QAction *pBefore=NULL)=0 |
| virtual bool | insertCommand (QAction *pCommand, QMenu *pMenu, const std::string &shortcutContext, QAction *pBefore=NULL)=0 |
| virtual QAction * | getMenuItem (const std::string &location) const =0 |
| virtual QAction * | getMenuItem (QMenu *pMenu) const =0 |
| virtual QMenu * | getMenu (QAction *pAction) const =0 |
| virtual bool | isMenu (QAction *pAction) const =0 |
| virtual bool | isCommand (QAction *pAction) const =0 |
| virtual bool | removeMenu (QMenu *pMenu)=0 |
| virtual bool | removeMenuItem (QAction *pAction)=0 |
Protected Member Functions | |
| virtual | ~MenuBar () |
This class provides access to the menu structure from which users can execute a variety of actions. Plug-ins can use the menu bar to actively add and organize actions. The application contains a menu bar located at the top of the main application window that can be obtained by calling DesktopServices::getMainMenuBar(). In addition to the main menu bar, each toolbar contains a menu bar that is the first widget on the toolbar that can be obtained by calling ToolBar::getMenuBar().
Plug-ins should use the MenuBar class when Qt slot methods within the plug-in should be called when the command is invoked. For this to work properly, these plug-ins should stay resident after execution.
There are several approaches to adding and organizing menus and commands on the menu bar. One approach is that a menu can be added with addMenu(), and then custom actions can be added directly to the menu. Each action that is added directly to a menu will not have a keyboard shortcut initialized from the user-defined configuration settings If the user should be able to edit and save the keyboard shortcut, insertCommand() should be called or DesktopServices::initializeAction() should be called prior to adding the action to the menu.
A second approach to adding and organizing menus and commands on the menu bar is that an existing menu can be added with the insertMenu() method.
A third approach is that a command can be directly added to the menu bar with the addCommand() method. There are two versions of the method, one that allows the user to edit and save a keyboard shortcut, and one that does not allow the user to edit and save a keyboard shortcut. Both methods take a string location, which will create any menus and submenus as necessary. This means that the menu and/or submenus do not need to be created before adding the command to the menu bar.
The MenuBar class should not be used by plug-ins that desire the Executable::execute() method to be called when a command is invoked. Use the PlugInShell::setMenuLocation() and PlugInShell::addMenuLocation() methods instead, or override Executable::getMenuLocations().
Definition at line 58 of file MenuBar.h.
| virtual MenuBar::~MenuBar | ( | ) | [protected, virtual] |
| virtual QMenu* MenuBar::addMenu | ( | const std::string & | location, | |
| QAction * | pBefore = NULL | |||
| ) | [pure virtual] |
Creates a menu on the menu bar or a submenu on an existing menu.
| location | The full location and name of the menu relative to this menu bar. The string should contain slashes between menu and submenu names. The last name in the string should be the name of the menu to add. Examples of valid menu location strings are as follows:
| |
| pBefore | The menu or command that should immediately follow the added menu. The menu is added at the end of the menu bar or submenu if NULL is passed in or if the given action does not exist on the parent menu or menu bar. |
| virtual QAction* MenuBar::insertMenu | ( | QMenu * | pMenu, | |
| QMenu * | pParentMenu = NULL, |
|||
| QAction * | pBefore = NULL | |||
| ) | [pure virtual] |
Adds an existing menu to the menu bar or a submenu.
| pMenu | A pointer to the existing Qt menu to add. | |
| pParentMenu | A pointer to the menu that should be the parent menu of pMenu. If NULL is passed in, the menu will be added directly to the menu bar. | |
| pBefore | The menu or command that should immediately follow the added menu. The menu is added at the end of the menu bar or submenu if NULL is passed in or if the given action does not exist on the parent menu or menu bar. |
| virtual QAction* MenuBar::addCommand | ( | const std::string & | location, | |
| QAction * | pBefore = NULL | |||
| ) | [pure virtual] |
Creates a command on a menu in the menu bar.
This method creates a command on a menu in the menu bar and creates menus and submenus as necessary. The command is added directly to a menu and the user will not be able to edit and save a keyboard shortcut in the user-defined configuration settings. To allow the user to edit the keyboard shortcut, call the overloaded addCommand(const std::string&, const std::string&, QAction*) method instead.
| location | The full location and name of the command relative to this menu bar. The string should contain slashes between menu and submenu names and the command name. The last name in the string should be the name of the command to add. Examples of valid command location strings are as follows:
| |
| pBefore | The menu or command that should immediately follow the added command. The command is added at the end of the menu bar or submenu if NULL is passed in or if the given action does not exist on the parent menu. |
| virtual QAction* MenuBar::addCommand | ( | const std::string & | location, | |
| const std::string & | shortcutContext, | |||
| QAction * | pBefore = NULL | |||
| ) | [pure virtual] |
Creates a command on a menu in the menu bar.
This method creates a command on a menu in the menu bar and creates menus and submenus as necessary. The command is added directly to a menu and a given shortcut context allows the user to edit and save the keyboard shortcut in the user-defined configuration settings. If the should not be able to edit the shortcut, call the overloaded addCommand(const std::string&, QAction*) method instead or first create the menu and add the command directly to the menu.
| location | The full location and name of the command relative to this menu bar. The string should contain slashes between menu and submenu names and the command name. The last name in the string should be the name of the command to add. Examples of valid command location strings are as follows:
| |
| shortcutContext | The context name for the keyboard shortcut of the action. When the user edits keyboard shortcuts, the shortcuts are grouped according to their context string. Contexts can be nested by using a slash (/) between context levels. If the top-level context name is the same as a plug-in name, the shortcut is grouped under a single Plug-Ins context. | |
| pBefore | The menu or command that should immediately follow the added command. The command is added at the end of the menu bar or submenu if NULL is passed in or if the given action does not exist on the parent menu. |
| virtual bool MenuBar::insertCommand | ( | QAction * | pCommand, | |
| QMenu * | pMenu, | |||
| const std::string & | shortcutContext, | |||
| QAction * | pBefore = NULL | |||
| ) | [pure virtual] |
Adds an existing command to a given menu on the menu bar.
This method adds an existing command to a menu in the menu bar and allows the user to edit and save a keyboard shortcut based on a given context. If the should not be able to edit the shortcut, call the QMenu::insertAction() method instead.
| pCommand | The command to add. | |
| pMenu | A pointer to the menu to which pCommand should be added. This method does nothing if NULL is passed in. | |
| shortcutContext | The context name for the keyboard shortcut of the action. When the user edits keyboard shortcuts, the shortcuts are grouped according to their context string. Contexts can be nested by using a slash (/) between context levels. If the top-level context name is the same as a plug-in name, the shortcut is grouped under a single Plug-Ins context. Passing in an empty string indicates that the user should not be able to edit the keyboard shortcut of the command, which is the same as calling QMenu::insertAction(). | |
| pBefore | The menu or command that should immediately follow the added command. The command is added at the end of the menu bar or submenu if NULL is passed in or if the given action does not exist on the given menu. |
| virtual QAction* MenuBar::getMenuItem | ( | const std::string & | location | ) | const [pure virtual] |
Retrieves the menu or command at a given location.
| location | The full location and name of the command relative to this menu bar. The string should contain slashes between menu and submenu names and the command name. The last name in the string should be the name of the command to add. Examples of valid command location strings are as follows:
|
| virtual QAction* MenuBar::getMenuItem | ( | QMenu * | pMenu | ) | const [pure virtual] |
Retrieves the Qt action associated with a given menu.
This method differs from QMenu::menuAction() in that a valid value is returned only if the menu exists on the menu bar or one of its menus.
| pMenu | The menu for which to get its associated Qt action. |
| virtual QMenu* MenuBar::getMenu | ( | QAction * | pAction | ) | const [pure virtual] |
Retrieves the menu associated with a given Qt action.
| pAction | The Qt action for which to get its associated menu. |
| virtual bool MenuBar::isMenu | ( | QAction * | pAction | ) | const [pure virtual] |
Queries whether a given Qt action is associated with a menu.
| pAction | The Qt action to query if is represents a menu. |
| virtual bool MenuBar::isCommand | ( | QAction * | pAction | ) | const [pure virtual] |
Queries whether a given Qt action is associated with a command.
| pAction | The Qt action to query if is represents a command. |
| virtual bool MenuBar::removeMenu | ( | QMenu * | pMenu | ) | [pure virtual] |
Removes a menu from the menu bar or one of its menus.
If the menu is successfully removed, it is also deleted.
| pMenu | The menu to remove. |
| virtual bool MenuBar::removeMenuItem | ( | QAction * | pAction | ) | [pure virtual] |
Removes a menu or command from the menu bar or one of its menus.
If a menu is successfully removed, it is also deleted.
| pAction | The Qt action representing the menu or command to remove. |