00001 /* 00002 * The information in this file is 00003 * Copyright(c) 2007 Ball Aerospace & Technologies Corporation 00004 * and is subject to the terms and conditions of the 00005 * GNU Lesser General Public License Version 2.1 00006 * The license text is available from 00007 * http://www.gnu.org/licenses/lgpl.html 00008 */ 00009 00010 #ifndef MENUBAR_H 00011 #define MENUBAR_H 00012 00013 #include <string> 00014 00015 class QAction; 00016 class QMenu; 00017 00018 /** 00019 * Container for menus with user executable commands. 00020 * 00021 * This class provides access to the menu structure from which users can 00022 * execute a variety of actions. Plug-ins can use the menu bar to actively 00023 * add and organize actions. The application contains a menu bar located at 00024 * the top of the main application window that can be obtained by calling 00025 * DesktopServices::getMainMenuBar(). In addition to the main menu bar, each 00026 * toolbar contains a menu bar that is the first widget on the toolbar that 00027 * can be obtained by calling ToolBar::getMenuBar(). 00028 * 00029 * Plug-ins should use the MenuBar class when Qt slot methods within the 00030 * plug-in should be called when the command is invoked. For this to work 00031 * properly, these plug-ins should stay resident after execution. 00032 * 00033 * There are several approaches to adding and organizing menus and commands on 00034 * the menu bar. One approach is that a menu can be added with addMenu(), and 00035 * then custom actions can be added directly to the menu. Each action that is 00036 * added directly to a menu will not have a keyboard shortcut initialized from 00037 * the user-defined configuration settings If the user should be able to edit 00038 * and save the keyboard shortcut, insertCommand() should be called or 00039 * DesktopServices::initializeAction() should be called prior to adding the 00040 * action to the menu. 00041 * 00042 * A second approach to adding and organizing menus and commands on the menu 00043 * bar is that an existing menu can be added with the insertMenu() method. 00044 * 00045 * A third approach is that a command can be directly added to the menu bar 00046 * with the addCommand() method. There are two versions of the method, one 00047 * that allows the user to edit and save a keyboard shortcut, and one that 00048 * does not allow the user to edit and save a keyboard shortcut. Both 00049 * methods take a string location, which will create any menus and submenus as 00050 * necessary. This means that the menu and/or submenus do not need to be 00051 * created before adding the command to the menu bar. 00052 * 00053 * The MenuBar class should not be used by plug-ins that desire the 00054 * Executable::execute() method to be called when a command is invoked. Use 00055 * the PlugInShell::setMenuLocation() and PlugInShell::addMenuLocation() 00056 * methods instead, or override Executable::getMenuLocations(). 00057 */ 00058 class MenuBar 00059 { 00060 public: 00061 /** 00062 * Creates a menu on the menu bar or a submenu on an existing menu. 00063 * 00064 * @param location 00065 * The full location and name of the menu relative to this menu 00066 * bar. The string should contain slashes between menu and 00067 * submenu names. The last name in the string should be the name 00068 * of the menu to add. Examples of valid menu location strings 00069 * are as follows: 00070 * - &File/&Import 00071 * - Geo 00072 * @param pBefore 00073 * The menu or command that should immediately follow the added 00074 * menu. The menu is added at the end of the menu bar or submenu 00075 * if \b NULL is passed in or if the given action does not exist 00076 * on the parent menu or menu bar. 00077 * 00078 * @return A pointer to the new Qt menu. \b NULL is returned if the menu 00079 * already exists. 00080 * 00081 * @see insertMenu() 00082 */ 00083 virtual QMenu* addMenu(const std::string& location, QAction* pBefore = NULL) = 0; 00084 00085 /** 00086 * Adds an existing menu to the menu bar or a submenu. 00087 * 00088 * @param pMenu 00089 * A pointer to the existing Qt menu to add. 00090 * @param pParentMenu 00091 * A pointer to the menu that should be the parent menu of 00092 * \em pMenu. If NULL is passed in, the menu will be added 00093 * directly to the menu bar. 00094 * @param pBefore 00095 * The menu or command that should immediately follow the added 00096 * menu. The menu is added at the end of the menu bar or submenu 00097 * if \b NULL is passed in or if the given action does not exist 00098 * on the parent menu or menu bar. 00099 * 00100 * @return A pointer to the Qt action created by the menu bar or submenu 00101 * to which the menu was added. A valid value is returned if the 00102 * given menu already exists on the menu bar or the given parent 00103 * menu. 00104 */ 00105 virtual QAction* insertMenu(QMenu* pMenu, QMenu* pParentMenu = NULL, QAction* pBefore = NULL) = 0; 00106 00107 /** 00108 * Creates a command on a menu in the menu bar. 00109 * 00110 * This method creates a command on a menu in the menu bar and creates 00111 * menus and submenus as necessary. The command is added directly to a 00112 * menu and the user will not be able to edit and save a keyboard shortcut 00113 * in the user-defined configuration settings. To allow the user to edit 00114 * the keyboard shortcut, call the overloaded 00115 * addCommand(const std::string&, const std::string&, QAction*) method 00116 * instead. 00117 * 00118 * @param location 00119 * The full location and name of the command relative to this menu 00120 * bar. The string should contain slashes between menu and 00121 * submenu names and the command name. The last name in the 00122 * string should be the name of the command to add. Examples of 00123 * valid command location strings are as follows: 00124 * - &File/&Import/Layer 00125 * - Geo/Georeference 00126 * @param pBefore 00127 * The menu or command that should immediately follow the added 00128 * command. The command is added at the end of the menu bar or 00129 * submenu if \b NULL is passed in or if the given action does not 00130 * exist on the parent menu. 00131 * 00132 * @return A pointer to the Qt action created by the menu to which the 00133 * command was added. A valid value is returned if the given 00134 * command already exists. 00135 * 00136 * @see insertCommand() 00137 */ 00138 virtual QAction* addCommand(const std::string& location, QAction* pBefore = NULL) = 0; 00139 00140 /** 00141 * Creates a command on a menu in the menu bar. 00142 * 00143 * This method creates a command on a menu in the menu bar and creates 00144 * menus and submenus as necessary. The command is added directly to a 00145 * menu and a given shortcut context allows the user to edit and save the 00146 * keyboard shortcut in the user-defined configuration settings. If the 00147 * should not be able to edit the shortcut, call the overloaded 00148 * addCommand(const std::string&, QAction*) method instead or first create 00149 * the menu and add the command directly to the menu. 00150 * 00151 * @param location 00152 * The full location and name of the command relative to this menu 00153 * bar. The string should contain slashes between menu and 00154 * submenu names and the command name. The last name in the 00155 * string should be the name of the command to add. Examples of 00156 * valid command location strings are as follows: 00157 * - &File/&Import/Layer 00158 * - Geo/Georeference 00159 * @param shortcutContext 00160 * The context name for the keyboard shortcut of the action. When 00161 * the user edits keyboard shortcuts, the shortcuts are grouped 00162 * according to their context string. Contexts can be nested by 00163 * using a slash (/) between context levels. If the top-level 00164 * context name is the same as a plug-in name, the shortcut is 00165 * grouped under a single Plug-Ins context. 00166 * @param pBefore 00167 * The menu or command that should immediately follow the added 00168 * command. The command is added at the end of the menu bar or 00169 * submenu if \b NULL is passed in or if the given action does not 00170 * exist on the parent menu. 00171 * 00172 * @return A pointer to the Qt action created by the menu to which the 00173 * command was added. A valid value is returned if the given 00174 * command already exists. 00175 * 00176 * @see insertCommand() 00177 */ 00178 virtual QAction* addCommand(const std::string& location, const std::string& shortcutContext, 00179 QAction* pBefore = NULL) = 0; 00180 00181 /** 00182 * Adds an existing command to a given menu on the menu bar. 00183 * 00184 * This method adds an existing command to a menu in the menu bar and 00185 * allows the user to edit and save a keyboard shortcut based on a given 00186 * context. If the should not be able to edit the shortcut, call the 00187 * QMenu::insertAction() method instead. 00188 * 00189 * @param pCommand 00190 * The command to add. 00191 * @param pMenu 00192 * A pointer to the menu to which \em pCommand should be added. 00193 * This method does nothing if \b NULL is passed in. 00194 * @param shortcutContext 00195 * The context name for the keyboard shortcut of the action. When 00196 * the user edits keyboard shortcuts, the shortcuts are grouped 00197 * according to their context string. Contexts can be nested by 00198 * using a slash (/) between context levels. If the top-level 00199 * context name is the same as a plug-in name, the shortcut is 00200 * grouped under a single Plug-Ins context. Passing in an empty 00201 * string indicates that the user should not be able to edit the 00202 * keyboard shortcut of the command, which is the same as calling 00203 * QMenu::insertAction(). 00204 * @param pBefore 00205 * The menu or command that should immediately follow the added 00206 * command. The command is added at the end of the menu bar or 00207 * submenu if \b NULL is passed in or if the given action does not 00208 * exist on the given menu. 00209 * 00210 * @return Returns \b true if the command was successfully added; 00211 * otherwise returns \b false. 00212 * 00213 * @see addCommand() 00214 */ 00215 virtual bool insertCommand(QAction* pCommand, QMenu* pMenu, const std::string& shortcutContext, 00216 QAction* pBefore = NULL) = 0; 00217 00218 /** 00219 * Retrieves the menu or command at a given location. 00220 * 00221 * @param location 00222 * The full location and name of the command relative to this menu 00223 * bar. The string should contain slashes between menu and 00224 * submenu names and the command name. The last name in the 00225 * string should be the name of the command to add. Examples of 00226 * valid command location strings are as follows: 00227 * - &File/&Import/Layer 00228 * - Geo/Georeference 00229 * 00230 * @return A pointer to the Qt action represented by the given menu or 00231 * command. \b NULL is returned if the menu or command in the 00232 * given location does not exist. 00233 */ 00234 virtual QAction* getMenuItem(const std::string& location) const = 0; 00235 00236 /** 00237 * Retrieves the Qt action associated with a given menu. 00238 * 00239 * This method differs from QMenu::menuAction() in that a valid value is 00240 * returned only if the menu exists on the menu bar or one of its menus. 00241 * 00242 * @param pMenu 00243 * The menu for which to get its associated Qt action. 00244 * 00245 * @return A pointer to the Qt action represented by the given menu. 00246 * \b NULL is returned if the given menu does not exist on the 00247 * menu bar or one of its menus. 00248 */ 00249 virtual QAction* getMenuItem(QMenu* pMenu) const = 0; 00250 00251 /** 00252 * Retrieves the menu associated with a given Qt action. 00253 * 00254 * @param pAction 00255 * The Qt action for which to get its associated menu. 00256 * 00257 * @return A pointer to the Qt menu represented by the given action. 00258 * \b NULL is returned if the given menu action does not exist on 00259 * the menu bar or one of its menus or if the given action does 00260 * not represent a menu. 00261 * 00262 * @see isMenu() 00263 */ 00264 virtual QMenu* getMenu(QAction* pAction) const = 0; 00265 00266 /** 00267 * Queries whether a given Qt action is associated with a menu. 00268 * 00269 * @param pAction 00270 * The Qt action to query if is represents a menu. 00271 * 00272 * @return This method returns \b true if the given action is represented 00273 * by a menu or submenu contained on the menu bar; otherwise 00274 * returns \b false. 00275 * 00276 * @see getMenu(), isCommand() 00277 */ 00278 virtual bool isMenu(QAction* pAction) const = 0; 00279 00280 /** 00281 * Queries whether a given Qt action is associated with a command. 00282 * 00283 * @param pAction 00284 * The Qt action to query if is represents a command. 00285 * 00286 * @return This method returns \b true if the given action is represented 00287 * by a command contained on the menu bar or one of its menus; 00288 * otherwise returns \b false. 00289 * 00290 * @see isMenu() 00291 */ 00292 virtual bool isCommand(QAction* pAction) const = 0; 00293 00294 /** 00295 * Removes a menu from the menu bar or one of its menus. 00296 * 00297 * If the menu is successfully removed, it is also deleted. 00298 * 00299 * @param pMenu 00300 * The menu to remove. 00301 * 00302 * @return This method returns \b true if the menu is successfully removed 00303 * and deleted; otherwise returns \b false. 00304 */ 00305 virtual bool removeMenu(QMenu* pMenu) = 0; 00306 00307 /** 00308 * Removes a menu or command from the menu bar or one of its menus. 00309 * 00310 * If a menu is successfully removed, it is also deleted. 00311 * 00312 * @param pAction 00313 * The Qt action representing the menu or command to remove. 00314 * 00315 * @return This method returns \b true if the menu or command is 00316 * successfully removed; otherwise returns \b false. 00317 */ 00318 virtual bool removeMenuItem(QAction* pAction) = 0; 00319 00320 protected: 00321 /** 00322 * This should not be deleted directly. 00323 */ 00324 virtual ~MenuBar() {} 00325 }; 00326 00327 #endif