popupMenu.h
Engine/source/platform/menus/popupMenu.h
Classes:
class
Detailed Description
1 2//----------------------------------------------------------------------------- 3// Copyright (c) 2012 GarageGames, LLC 4// 5// Permission is hereby granted, free of charge, to any person obtaining a copy 6// of this software and associated documentation files (the "Software"), to 7// deal in the Software without restriction, including without limitation the 8// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 9// sell copies of the Software, and to permit persons to whom the Software is 10// furnished to do so, subject to the following conditions: 11// 12// The above copyright notice and this permission notice shall be included in 13// all copies or substantial portions of the Software. 14// 15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 20// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 21// IN THE SOFTWARE. 22//----------------------------------------------------------------------------- 23#include "console/simBase.h" 24#include "core/util/tVector.h" 25#include "util/messaging/dispatcher.h" 26#include "gui/core/guiCanvas.h" 27 28#ifndef _POPUPMENU_H_ 29#define _POPUPMENU_H_ 30 31// Forward ref used by the platform code 32struct PlatformPopupMenuData; 33class MenuBar; 34 35// PopupMenu represents a menu. 36// You can add menu items to the menu, but there is no torque object associated 37// with these menu items, they exist only in a platform specific manner. 38class PopupMenu : public SimObject, public virtual Dispatcher::IMessageListener 39{ 40 typedef SimObject Parent; 41 42 friend class MenuBar; 43 44private: 45 /// Used by MenuBar to attach the menu to the menu bar. Do not use anywhere else. 46 void attachToMenuBar(GuiCanvas *owner, S32 pos); 47 48protected: 49 PlatformPopupMenuData *mData; 50 51 SimSet *mSubmenus; 52 SimObjectPtr<GuiCanvas> mCanvas; 53 54 StringTableEntry mBarTitle; 55 56 U32 mPopupGUID; 57 58 bool mIsPopup; 59 60public: 61 PopupMenu(); 62 virtual ~PopupMenu(); 63 void createPlatformPopupMenuData(); 64 void deletePlatformPopupMenuData(); 65 66 DECLARE_CONOBJECT(PopupMenu); 67 68 static void initPersistFields(); 69 70 virtual bool onAdd(); 71 virtual void onRemove(); 72 73 static PopupMenuEvent smPopupMenuEvent; 74 static bool smSelectionEventHandled; /// Set to true if any menu or submenu handles a selection event 75 76 /// Creates the platform specific menu object, a peer to this object. 77 /// The platform menu *must* exist before calling any method that manipulates 78 /// menu items or displays the menu. 79 /// implementd on a per-platform basis. 80 void createPlatformMenu(); 81 82 void setBarTitle(const char * val) { mBarTitle = StringTable->insert(val, true); } 83 StringTableEntry getBarTitle() const { return mBarTitle; } 84 85 /// pass NULL for @p title to insert a separator 86 /// returns the menu item's ID, or -1 on failure. 87 /// implementd on a per-platform basis. 88 /// TODO: factor out common code 89 S32 insertItem(S32 pos, const char *title, const char* accelerator, const char* cmd); 90 91 /// Sets the name title and accelerator for 92 /// an existing item. 93 bool setItem(S32 pos, const char *title, const char* accelerator, const char* cmd); 94 95 /// pass NULL for @p title to insert a separator 96 /// returns the menu item's ID, or -1 on failure. 97 /// adds the submenu to the mSubmenus vector. 98 /// implemented on a per-platform basis. 99 /// TODO: factor out common code 100 S32 insertSubMenu(S32 pos, const char *title, PopupMenu *submenu); 101 102 /// remove the menu item at @p itemPos 103 /// if the item has a submenu, it is removed from the mSubmenus list. 104 /// implemented on a per-platform basis. 105 /// TODO: factor out common code 106 void removeItem(S32 itemPos); 107 108 /// implemented on a per-platform basis. 109 void enableItem(S32 pos, bool enable); 110 /// implemented on a per-platform basis. 111 void checkItem(S32 pos, bool checked); 112 113 /// All items at positions firstPos through lastPos are unchecked, and the 114 /// item at checkPos is checked. 115 /// implemented on a per-platform basis. 116 void checkRadioItem(S32 firstPos, S32 lastPos, S32 checkPos); 117 bool isItemChecked(S32 pos); 118 119 /// Returns the number of items in the menu. 120 U32 getItemCount(); 121 122 /// Returns the popup GUID 123 U32 getPopupGUID() { return mPopupGUID; } 124 125 //----------------------------------------------------------------------------- 126 // New code should not use these methods directly, use the menu bar instead. 127 // 128 // They remain for compatibility with old code and will be changing/going away 129 // once the existing code is moved over to the menu bar. 130 //----------------------------------------------------------------------------- 131 132 /// Places this menu in the menu bar of the application's main window. 133 /// @param owner The GuiCanvas that owns the PlatformWindow that this call is associated with 134 /// @param pos The relative position at which to place the menu. 135 /// @param title The name of the menu 136 void attachToMenuBar(GuiCanvas *owner, S32 pos, const char *title); 137 138 /// Removes this menu from the menu bar. 139 void removeFromMenuBar(); 140 141 //----------------------------------------------------------------------------- 142 143 /// Called when the menu has been attached to the menu bar 144 void onAttachToMenuBar(GuiCanvas *canvas, S32 pos, const char *title); 145 146 /// Called when the menu has been removed from the menu bar 147 void onRemoveFromMenuBar(GuiCanvas *canvas); 148 149 /// Returns the position index of this menu on the bar. 150 S32 getPosOnMenuBar(); 151 152 /// Returns true if this menu is attached to the menu bar 153 bool isAttachedToMenuBar() { return mCanvas != NULL; } 154 155 /// Displays this menu as a popup menu and blocks until the user has selected 156 /// an item. 157 /// @param canvas the owner to show this popup associated with 158 /// @param x window local x coordinate at which to display the popup menu 159 /// @param y window local y coordinate at which to display the popup menu 160 /// implemented on a per-platform basis. 161 void showPopup(GuiCanvas *owner, S32 x = -1, S32 y = -1); 162 163 /// Returns true iff this menu contains an item that matches @p iD. 164 /// implemented on a per-platform basis. 165 /// TODO: factor out common code 166 bool canHandleID(U32 iD); 167 168 /// A menu item in this menu has been selected by id. 169 /// Submenus are given a chance to respond to the command first. 170 /// If no submenu can handle the command id, this menu handles it. 171 /// The script callback this::onSelectItem( position, text) is called. 172 /// If @p text is null, then the text arg passed to script is the text of 173 /// the selected menu item. 174 /// implemented on a per-platform basis. 175 /// TODO: factor out common code 176 bool handleSelect(U32 command, const char *text = NULL); 177 178 void onMenuSelect(); 179 180 /// Helper function to allow menu selections from signal events. 181 /// Wraps canHandleID() and handleSelect() in one function 182 /// without changing their internal functionality, so 183 /// it should work regardless of platform. 184 void handleSelectEvent(U32 popID, U32 command); 185 186 virtual bool onMessageReceived(StringTableEntry queue, const char* event, const char* data ); 187 virtual bool onMessageObjectReceived(StringTableEntry queue, Message *msg ); 188}; 189 190#endif // _POPUPMENU_H_ 191