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#ifndef _POPUPMENU_H_
 24#define _POPUPMENU_H_
 25
 26#include "console/simBase.h"
 27#include "core/util/tVector.h"
 28#include "util/messaging/dispatcher.h"
 29#include "gui/core/guiCanvas.h"
 30
 31class PopupMenu;
 32class GuiMenuBar;
 33class GuiPopupMenuTextListCtrl;
 34class GuiPopupMenuBackgroundCtrl;
 35
 36struct MenuItem   // an individual item in a pull-down menu
 37{
 38   String mText;    // the text of the menu item
 39   U32 mID;        // a script-assigned identifier
 40   char *mAccelerator; // the keyboard accelerator shortcut for the menu item
 41   U32 mAcceleratorIndex; // index of this accelerator
 42   bool mEnabled;        // true if the menu item is selectable
 43   bool mVisible;        // true if the menu item is visible
 44   S32 mBitmapIndex;     // index of the bitmap in the bitmap array
 45   S32 mCheckGroup;      // the group index of the item visa vi check marks - 
 46                        // only one item in the group can be checked.
 47
 48   bool mIsSubmenu;           //  This menu item has a submenu that will be displayed
 49
 50   bool mIsChecked;
 51
 52   bool mIsSpacer;
 53
 54   bool mIsMenubarEntry;
 55
 56   PopupMenu* mSubMenuParentMenu; //  For a submenu, this is the parent menu
 57   PopupMenu* mSubMenu;
 58   String mCMD;
 59};
 60
 61// PopupMenu represents a menu.
 62// You can add menu items to the menu, but there is no torque object associated
 63// with these menu items, they exist only in a  platform specific manner.
 64class PopupMenu : public SimObject, public virtual Dispatcher::IMessageListener
 65{
 66   typedef SimObject Parent;
 67   friend class GuiMenuBar;
 68   friend class GuiPopupMenuTextListCtrl;
 69   friend class GuiPopupMenuBackgroundCtrl;
 70
 71protected:
 72   Vector<MenuItem> mMenuItems;
 73
 74   GuiMenuBar* mMenuBarCtrl;
 75
 76   StringTableEntry mBarTitle;
 77
 78   RectI mBounds;
 79   bool mVisible;
 80
 81   S32 mBitmapIndex;    // Index of the bitmap in the bitmap array (-1 = no bitmap)
 82   bool mDrawBitmapOnly;   // Draw only the bitmap and not the text
 83   bool mDrawBorder;    // Should a border be drawn around this menu (usually if we only have a bitmap, we don't want a border)
 84
 85   bool mIsSubmenu;
 86
 87   bool mRadioSelection; ///If true, we treat all the items in the same check group as a radio item, so we uncheck everything else in the group if an item is checked
 88                         ///If false, then we don't clear other selections
 89
 90   //This is the gui control that renders our popup
 91   GuiPopupMenuTextListCtrl *mTextList;
 92
 93public:
 94   PopupMenu();
 95   virtual ~PopupMenu();
 96   
 97   DECLARE_CONOBJECT(PopupMenu);
 98
 99   static void initPersistFields();
100
101   virtual bool onAdd();
102   virtual void onRemove();
103
104   static PopupMenuEvent smPopupMenuEvent;
105   static bool smSelectionEventHandled; /// Set to true if any menu or submenu handles a selection event
106   
107   /// pass NULL for @p title to insert a separator
108   /// returns the menu item's ID, or -1 on failure.
109   /// implementd on a per-platform basis.
110   /// TODO: factor out common code
111   S32 insertItem(S32 pos, const char *title, const char* accelerator, const char* cmd, S32 bitmapIndex = -1);
112
113   /// Sets the name title and accelerator for 
114   /// an existing item.
115   bool setItem(S32 pos, const char *title, const char* accelerator, const char* cmd);
116
117   /// pass NULL for @p title to insert a separator
118   /// returns the menu item's ID, or -1 on failure.
119   /// adds the submenu to the mSubmenus vector.
120   /// implemented on a per-platform basis.
121   /// TODO: factor out common code
122   S32 insertSubMenu(S32 pos, const char *title, PopupMenu *submenu);
123   
124   /// remove the menu item at @p itemPos
125   /// if the item has a submenu, it is removed from the mSubmenus list.
126   /// implemented on a per-platform basis.
127   /// TODO: factor out common code
128   void removeItem(S32 itemPos);
129
130   /// implemented on a per-platform basis.
131   void enableItem(S32 pos, bool enable);
132   /// implemented on a per-platform basis.
133   void checkItem(S32 pos, bool checked);
134
135   /// All items at positions firstPos through lastPos are unchecked, and the
136   /// item at checkPos is checked.
137   /// implemented on a per-platform basis.
138   void checkRadioItem(S32 firstPos, S32 lastPos, S32 checkPos);
139   bool isItemChecked(S32 pos);
140
141   /// Returns the number of items in the menu.
142   U32 getItemCount();
143
144   ///Clears all items
145   void clearItems();
146
147   ///Gets the text of a given item
148   String getItemText(S32 pos);
149
150   //-----------------------------------------------------------------------------
151   /// Displays this menu as a popup menu and blocks until the user has selected
152   /// an item.
153   /// @param canvas the owner to show this popup associated with
154   /// @param x window local x coordinate at which to display the popup menu
155   /// @param y window local y coordinate at which to display the popup menu
156   /// implemented on a per-platform basis.
157   void showPopup(GuiCanvas *owner, S32 x = -1, S32 y = -1);
158
159   void hidePopup();
160   void hidePopupSubmenus();
161
162   /// Returns true iff this menu contains an item that matches @p iD.
163   /// implemented on a per-platform basis.
164   /// TODO: factor out common code
165   bool canHandleID(U32 iD);
166
167   /// A menu item in this menu has been selected by id.
168   /// Submenus are given a chance to respond to the command first.
169   /// If no submenu can handle the command id, this menu handles it.
170   /// The script callback this::onSelectItem( position, text) is called.
171   /// If @p text is null, then the text arg passed to script is the text of
172   /// the selected menu item.
173   /// implemented on a per-platform basis.
174   /// TODO: factor out common code
175   bool handleSelect(U32 command, const char *text = NULL);
176
177   void onMenuSelect();
178
179   /// Helper function to allow menu selections from signal events.
180   /// Wraps canHandleID() and handleSelect() in one function
181   /// without changing their internal functionality, so
182   /// it should work regardless of platform.
183   void handleSelectEvent(U32 popID, U32 command);
184
185   virtual bool onMessageReceived(StringTableEntry queue, const char* event, const char* data );
186   virtual bool onMessageObjectReceived(StringTableEntry queue, Message *msg );
187
188   bool isVisible() { return mVisible; }
189   void setVisible(bool isVis) { mVisible = isVis; }
190
191   GuiMenuBar* getMenuBarCtrl();
192};
193
194#endif // _POPUPMENU_H_
195