include/wx/menu.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/menu.h
   3 // Purpose:     wxMenu and wxMenuBar classes
   4 // Author:      Vadim Zeitlin
   5 // Modified by:
   6 // Created:     26.10.99
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) wxWindows team
   9 // Licence:     wxWindows licence
  10 ///////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_MENU_H_BASE_
  13 #define _WX_MENU_H_BASE_
  14
  15 #if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
  16     #pragma interface "menubase.h"
  17 #endif
  18
  19 #include "wx/defs.h"
  20
  21 #if wxUSE_MENUS
  22
  23 // ----------------------------------------------------------------------------
  24 // headers
  25 // ----------------------------------------------------------------------------
  26
  27 #include "wx/list.h"        // for "template" list classes
  28 #include "wx/window.h"      // base class for wxMenuBar
  29
  30 // also include this one to ensure compatibility with old code which only
  31 // included wx/menu.h
  32 #include "wx/menuitem.h"
  33
  34 class WXDLLEXPORT wxMenu;
  35 class WXDLLEXPORT wxMenuBarBase;
  36 class WXDLLEXPORT wxMenuBar;
  37 class WXDLLEXPORT wxMenuItem;
  38
  39 // pseudo template list classes
  40 WX_DECLARE_EXPORTED_LIST(wxMenu, wxMenuList);
  41 WX_DECLARE_EXPORTED_LIST(wxMenuItem, wxMenuItemList);
  42
  43 // ----------------------------------------------------------------------------
  44 // wxMenu
  45 // ----------------------------------------------------------------------------
  46
  47 class WXDLLEXPORT wxMenuBase : public wxEvtHandler
  48 {
  49 public:
  50     // create a menu
  51     static wxMenu *New(const wxString& title = wxEmptyString, long style = 0);
  52
  53     // ctors
  54     wxMenuBase(const wxString& title, long style = 0) : m_title(title)
  55         { Init(style); }
  56     wxMenuBase(long style = 0)
  57         { Init(style); }
  58
  59     // dtor deletes all the menu items we own
  60     virtual ~wxMenuBase();
  61
  62     // menu construction
  63     // -----------------
  64
  65     // append any kind of item (normal/check/radio/separator)
  66     wxMenuItem* Append(int itemid,
  67                        const wxString& text,
  68                        const wxString& help = wxEmptyString,
  69                        wxItemKind kind = wxITEM_NORMAL)
  70     {
  71         return DoAppend(wxMenuItem::New((wxMenu *)this, itemid, text, help, kind));
  72     }
  73
  74     // append a separator to the menu
  75     wxMenuItem* AppendSeparator() { return Append(wxID_SEPARATOR, wxEmptyString); }
  76
  77     // append a check item
  78     wxMenuItem* AppendCheckItem(int itemid,
  79                                 const wxString& text,
  80                                 const wxString& help = wxEmptyString)
  81     {
  82         return Append(itemid, text, help, wxITEM_CHECK);
  83     }
  84
  85     // append a radio item
  86     wxMenuItem* AppendRadioItem(int itemid,
  87                                 const wxString& text,
  88                                 const wxString& help = wxEmptyString)
  89     {
  90         return Append(itemid, text, help, wxITEM_RADIO);
  91     }
  92
  93     // append a submenu
  94     wxMenuItem* Append(int itemid,
  95                        const wxString& text,
  96                        wxMenu *submenu,
  97                        const wxString& help = wxEmptyString)
  98     {
  99         return DoAppend(wxMenuItem::New((wxMenu *)this, itemid, text, help,
 100                                         wxITEM_NORMAL, submenu));
 101     }
 102
 103     // the most generic form of Append() - append anything
 104     wxMenuItem* Append(wxMenuItem *item) { return DoAppend(item); }
 105
 106     // insert a break in the menu (only works when appending the items, not
 107     // inserting them)
 108     virtual void Break() { }
 109
 110     // insert an item before given position
 111     wxMenuItem* Insert(size_t pos, wxMenuItem *item);
 112
 113     // insert an item before given position
 114     wxMenuItem* Insert(size_t pos,
 115                        int itemid,
 116                        const wxString& text,
 117                        const wxString& help = wxEmptyString,
 118                        wxItemKind kind = wxITEM_NORMAL)
 119     {
 120         return Insert(pos, wxMenuItem::New((wxMenu *)this, itemid, text, help, kind));
 121     }
 122
 123     // insert a separator
 124     wxMenuItem* InsertSeparator(size_t pos)
 125     {
 126         return Insert(pos, wxMenuItem::New((wxMenu *)this, wxID_SEPARATOR));
 127     }
 128
 129     // insert a check item
 130     wxMenuItem* InsertCheckItem(size_t pos,
 131                                 int itemid,
 132                                 const wxString& text,
 133                                 const wxString& help = wxEmptyString)
 134     {
 135         return Insert(pos, itemid, text, help, wxITEM_CHECK);
 136     }
 137
 138     // insert a radio item
 139      wxMenuItem* InsertRadioItem(size_t pos,
 140                                  int itemid,
 141                                  const wxString& text,
 142                                  const wxString& help = wxEmptyString)
 143     {
 144         return Insert(pos, itemid, text, help, wxITEM_RADIO);
 145     }
 146
 147     // insert a submenu
 148     wxMenuItem* Insert(size_t pos,
 149                        int itemid,
 150                        const wxString& text,
 151                        wxMenu *submenu,
 152                        const wxString& help = wxEmptyString)
 153     {
 154         return Insert(pos, wxMenuItem::New((wxMenu *)this, itemid, text, help,
 155                                            wxITEM_NORMAL, submenu));
 156     }
 157
 158     // prepend an item to the menu
 159     wxMenuItem* Prepend(wxMenuItem *item)
 160     {
 161         return Insert(0u, item);
 162     }
 163
 164     // prepend any item to the menu
 165     wxMenuItem* Prepend(int itemid,
 166                         const wxString& text,
 167                         const wxString& help = wxEmptyString,
 168                         wxItemKind kind = wxITEM_NORMAL)
 169     {
 170         return Insert(0u, itemid, text, help, kind);
 171     }
 172
 173     // prepend a separator
 174     wxMenuItem* PrependSeparator()
 175     {
 176         return InsertSeparator(0u);
 177     }
 178
 179     // prepend a check item
 180     wxMenuItem* PrependCheckItem(int itemid,
 181                                  const wxString& text,
 182                                  const wxString& help = wxEmptyString)
 183     {
 184         return InsertCheckItem(0u, itemid, text, help);
 185     }
 186
 187     // prepend a radio item
 188     wxMenuItem* PrependRadioItem(int itemid,
 189                                  const wxString& text,
 190                                  const wxString& help = wxEmptyString)
 191     {
 192         return InsertRadioItem(0u, itemid, text, help);
 193     }
 194
 195     // prepend a submenu
 196     wxMenuItem* Prepend(int itemid,
 197                         const wxString& text,
 198                         wxMenu *submenu,
 199                         const wxString& help = wxEmptyString)
 200     {
 201         return Insert(0u, itemid, text, submenu, help);
 202     }
 203
 204     // detach an item from the menu, but don't delete it so that it can be
 205     // added back later (but if it's not, the caller is responsible for
 206     // deleting it!)
 207     wxMenuItem *Remove(int itemid) { return Remove(FindChildItem(itemid)); }
 208     wxMenuItem *Remove(wxMenuItem *item);
 209
 210     // delete an item from the menu (submenus are not destroyed by this
 211     // function, see Destroy)
 212     bool Delete(int itemid) { return Delete(FindChildItem(itemid)); }
 213     bool Delete(wxMenuItem *item);
 214
 215     // delete the item from menu and destroy it (if it's a submenu)
 216     bool Destroy(int itemid) { return Destroy(FindChildItem(itemid)); }
 217     bool Destroy(wxMenuItem *item);
 218
 219     // menu items access
 220     // -----------------
 221
 222     // get the items
 223     size_t GetMenuItemCount() const { return m_items.GetCount(); }
 224
 225     const wxMenuItemList& GetMenuItems() const { return m_items; }
 226     wxMenuItemList& GetMenuItems() { return m_items; }
 227
 228     // search
 229     virtual int FindItem(const wxString& item) const;
 230     wxMenuItem* FindItem(int itemid, wxMenu **menu = NULL) const;
 231
 232     // find by position
 233     wxMenuItem* FindItemByPosition(size_t position) const;
 234
 235     // get/set items attributes
 236     void Enable(int itemid, bool enable);
 237     bool IsEnabled(int itemid) const;
 238
 239     void Check(int itemid, bool check);
 240     bool IsChecked(int itemid) const;
 241
 242     void SetLabel(int itemid, const wxString& label);
 243     wxString GetLabel(int itemid) const;
 244
 245     virtual void SetHelpString(int itemid, const wxString& helpString);
 246     virtual wxString GetHelpString(int itemid) const;
 247
 248     // misc accessors
 249     // --------------
 250
 251     // the title
 252     virtual void SetTitle(const wxString& title) { m_title = title; }
 253     const wxString GetTitle() const { return m_title; }
 254
 255     // event handler
 256     void SetEventHandler(wxEvtHandler *handler) { m_eventHandler = handler; }
 257     wxEvtHandler *GetEventHandler() const { return m_eventHandler; }
 258
 259     // invoking window
 260     void SetInvokingWindow(wxWindow *win) { m_invokingWindow = win; }
 261     wxWindow *GetInvokingWindow() const { return m_invokingWindow; }
 262
 263     // style
 264     long GetStyle() const { return m_style; }
 265
 266     // implementation helpers
 267     // ----------------------
 268
 269     // Updates the UI for a menu and all submenus recursively. source is the
 270     // object that has the update event handlers defined for it. If NULL, the
 271     // menu or associated window will be used.
 272     void UpdateUI(wxEvtHandler* source = (wxEvtHandler*)NULL);
 273
 274     // get the menu bar this menu is attached to (may be NULL, always NULL for
 275     // popup menus).  Traverse up the menu hierarchy to find it.
 276     wxMenuBar *GetMenuBar() const;
 277
 278     // called when the menu is attached/detached to/from a menu bar
 279     virtual void Attach(wxMenuBarBase *menubar);
 280     virtual void Detach();
 281
 282     // is the menu attached to a menu bar (or is it a popup one)?
 283     bool IsAttached() const { return GetMenuBar() != NULL; }
 284
 285     // set/get the parent of this menu
 286     void SetParent(wxMenu *parent) { m_menuParent = parent; }
 287     wxMenu *GetParent() const { return m_menuParent; }
 288
 289     // implementation only from now on
 290     // -------------------------------
 291
 292     // unlike FindItem(), this function doesn't recurse but only looks through
 293     // our direct children and also may return the index of the found child if
 294     // pos != NULL
 295     wxMenuItem *FindChildItem(int itemid, size_t *pos = NULL) const;
 296
 297     // called to generate a wxCommandEvent, return TRUE if it was processed,
 298     // FALSE otherwise
 299     //
 300     // the checked parameter may have boolean value or -1 for uncheckable items
 301     bool SendEvent(int itemid, int checked = -1);
 302
 303     // compatibility: these functions are deprecated, use the new ones instead
 304     // -----------------------------------------------------------------------
 305
 306     // use the versions taking wxItem_XXX now instead, they're more readable
 307     // and allow adding the radio items as well
 308     void Append(int itemid,
 309                 const wxString& text,
 310                 const wxString& help,
 311                 bool isCheckable)
 312     {
 313         Append(itemid, text, help, isCheckable ? wxITEM_CHECK : wxITEM_NORMAL);
 314     }
 315
 316     void Insert(size_t pos,
 317                 int itemid,
 318                 const wxString& text,
 319                 const wxString& help,
 320                 bool isCheckable)
 321     {
 322         Insert(pos, itemid, text, help, isCheckable ? wxITEM_CHECK : wxITEM_NORMAL);
 323     }
 324
 325     void Prepend(int itemid,
 326                  const wxString& text,
 327                  const wxString& help,
 328                  bool isCheckable)
 329     {
 330         Insert(0u, itemid, text, help, isCheckable);
 331     }
 332
 333     static void LockAccels(bool locked)
 334     {
 335         ms_locked = locked;
 336     }
 337
 338 protected:
 339     // virtuals to override in derived classes
 340     // ---------------------------------------
 341
 342     virtual wxMenuItem* DoAppend(wxMenuItem *item);
 343     virtual wxMenuItem* DoInsert(size_t pos, wxMenuItem *item);
 344
 345     virtual wxMenuItem *DoRemove(wxMenuItem *item);
 346     virtual bool DoDelete(wxMenuItem *item);
 347     virtual bool DoDestroy(wxMenuItem *item);
 348
 349     // helpers
 350     // -------
 351
 352     // common part of all ctors
 353     void Init(long style);
 354
 355     // associate the submenu with this menu
 356     void AddSubMenu(wxMenu *submenu);
 357
 358     wxMenuBar     *m_menuBar;           // menubar we belong to or NULL
 359     wxMenu        *m_menuParent;        // parent menu or NULL
 360
 361     wxString       m_title;             // the menu title or label
 362     wxMenuItemList m_items;             // the list of menu items
 363
 364     wxWindow      *m_invokingWindow;    // for popup menus
 365
 366     long           m_style;             // combination of wxMENU_XXX flags
 367
 368     wxEvtHandler  *m_eventHandler;      // a pluggable in event handler
 369
 370     static bool      ms_locked;
 371
 372     DECLARE_NO_COPY_CLASS(wxMenuBase)
 373 };
 374
 375 // ----------------------------------------------------------------------------
 376 // wxMenuBar
 377 // ----------------------------------------------------------------------------
 378
 379 class WXDLLEXPORT wxMenuBarBase : public wxWindow
 380 {
 381 public:
 382     // default ctor
 383     wxMenuBarBase();
 384
 385     // dtor will delete all menus we own
 386     virtual ~wxMenuBarBase();
 387
 388     // menu bar construction
 389     // ---------------------
 390
 391     // append a menu to the end of menubar, return TRUE if ok
 392     virtual bool Append(wxMenu *menu, const wxString& title);
 393
 394     // insert a menu before the given position into the menubar, return TRUE
 395     // if inserted ok
 396     virtual bool Insert(size_t pos, wxMenu *menu, const wxString& title);
 397
 398     // menu bar items access
 399     // ---------------------
 400
 401     // get the number of menus in the menu bar
 402     size_t GetMenuCount() const { return m_menus.GetCount(); }
 403
 404     // get the menu at given position
 405     wxMenu *GetMenu(size_t pos) const;
 406
 407     // replace the menu at given position with another one, returns the
 408     // previous menu (which should be deleted by the caller)
 409     virtual wxMenu *Replace(size_t pos, wxMenu *menu, const wxString& title);
 410
 411     // delete the menu at given position from the menu bar, return the pointer
 412     // to the menu (which should be  deleted by the caller)
 413     virtual wxMenu *Remove(size_t pos);
 414
 415     // enable or disable a submenu
 416     virtual void EnableTop(size_t pos, bool enable) = 0;
 417
 418     // is the menu enabled?
 419     virtual bool IsEnabledTop(size_t WXUNUSED(pos)) const { return TRUE; }
 420
 421     // get or change the label of the menu at given position
 422     virtual void SetLabelTop(size_t pos, const wxString& label) = 0;
 423     virtual wxString GetLabelTop(size_t pos) const = 0;
 424
 425     // item search
 426     // -----------
 427
 428     // by menu and item names, returns wxNOT_FOUND if not found or id of the
 429     // found item
 430     virtual int FindMenuItem(const wxString& menu, const wxString& item) const;
 431
 432     // find item by id (in any menu), returns NULL if not found
 433     //
 434     // if menu is !NULL, it will be filled with wxMenu this item belongs to
 435     virtual wxMenuItem* FindItem(int itemid, wxMenu **menu = NULL) const;
 436
 437     // find menu by its caption, return wxNOT_FOUND on failure
 438     int FindMenu(const wxString& title) const;
 439
 440     // item access
 441     // -----------
 442
 443     // all these functions just use FindItem() and then call an appropriate
 444     // method on it
 445     //
 446     // NB: under MSW, these methods can only be used after the menubar had
 447     //     been attached to the frame
 448
 449     void Enable(int itemid, bool enable);
 450     void Check(int itemid, bool check);
 451     bool IsChecked(int itemid) const;
 452     bool IsEnabled(int itemid) const;
 453
 454     void SetLabel(int itemid, const wxString &label);
 455     wxString GetLabel(int itemid) const;
 456
 457     void SetHelpString(int itemid, const wxString& helpString);
 458     wxString GetHelpString(int itemid) const;
 459
 460     // implementation helpers
 461
 462     // get the frame we are attached to (may return NULL)
 463     wxFrame *GetFrame() const { return m_menuBarFrame; }
 464
 465     // returns TRUE if we're attached to a frame
 466     bool IsAttached() const { return GetFrame() != NULL; }
 467
 468     // associate the menubar with the frame
 469     virtual void Attach(wxFrame *frame);
 470
 471     // called before deleting the menubar normally
 472     virtual void Detach();
 473
 474     // need to override these ones to avoid virtual function hiding
 475     virtual bool Enable(bool enable = TRUE) { return wxWindow::Enable(enable); }
 476     virtual void SetLabel(const wxString& s) { wxWindow::SetLabel(s); }
 477     virtual wxString GetLabel() const { return wxWindow::GetLabel(); }
 478
 479     // don't want menu bars to accept the focus by tabbing to them
 480     virtual bool AcceptsFocusFromKeyboard() const { return FALSE; }
 481
 482 protected:
 483     // the list of all our menus
 484     wxMenuList m_menus;
 485
 486     // the frame we are attached to (may be NULL)
 487     wxFrame *m_menuBarFrame;
 488
 489     DECLARE_NO_COPY_CLASS(wxMenuBarBase)
 490 };
 491
 492 // ----------------------------------------------------------------------------
 493 // include the real class declaration
 494 // ----------------------------------------------------------------------------
 495
 496 #ifdef wxUSE_BASE_CLASSES_ONLY
 497     #define wxMenuItem wxMenuItemBase
 498 #else // !wxUSE_BASE_CLASSES_ONLY
 499 #if defined(__WXUNIVERSAL__)
 500     #include "wx/univ/menu.h"
 501 #elif defined(__WXMSW__)
 502     #include "wx/msw/menu.h"
 503 #elif defined(__WXMOTIF__)
 504     #include "wx/motif/menu.h"
 505 #elif defined(__WXGTK__)
 506     #include "wx/gtk/menu.h"
 507 #elif defined(__WXMAC__)
 508     #include "wx/mac/menu.h"
 509 #elif defined(__WXCOCOA__)
 510     #include "wx/cocoa/menu.h"
 511 #elif defined(__WXPM__)
 512     #include "wx/os2/menu.h"
 513 #endif
 514 #endif // wxUSE_BASE_CLASSES_ONLY/!wxUSE_BASE_CLASSES_ONLY
 515
 516 #endif // wxUSE_MENUS
 517
 518 #endif
 519     // _WX_MENU_H_BASE_