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     void Append(int itemid,
  67                 const wxString& text,
  68                 const wxString& help = wxEmptyString,
  69                 wxItemKind kind = wxITEM_NORMAL)
  70     {
  71         DoAppend(wxMenuItem::New((wxMenu *)this, itemid, text, help, kind));
  72     }
  73
  74     // append a separator to the menu
  75     void AppendSeparator() { Append(wxID_SEPARATOR, wxEmptyString); }
  76
  77     // append a check item
  78     void AppendCheckItem(int itemid,
  79                          const wxString& text,
  80                          const wxString& help = wxEmptyString)
  81     {
  82         Append(itemid, text, help, wxITEM_CHECK);
  83     }
  84
  85     // append a radio item
  86     void AppendRadioItem(int itemid,
  87                          const wxString& text,
  88                          const wxString& help = wxEmptyString)
  89     {
  90         Append(itemid, text, help, wxITEM_RADIO);
  91     }
  92
  93     // append a submenu
  94     void Append(int itemid,
  95                 const wxString& text,
  96                 wxMenu *submenu,
  97                 const wxString& help = wxEmptyString)
  98     {
  99         DoAppend(wxMenuItem::New((wxMenu *)this, itemid, text, help,
 100                                  wxITEM_NORMAL, submenu));
 101     }
 102
 103     // the most generic form of Append() - append anything
 104     void Append(wxMenuItem *item) { 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     bool Insert(size_t pos, wxMenuItem *item);
 112
 113     // insert an item before given position
 114     void Insert(size_t pos,
 115                 int itemid,
 116                 const wxString& text,
 117                 const wxString& help = wxEmptyString,
 118                 wxItemKind kind = wxITEM_NORMAL)
 119     {
 120         Insert(pos, wxMenuItem::New((wxMenu *)this, itemid, text, help, kind));
 121     }
 122
 123     // insert a separator
 124     void InsertSeparator(size_t pos)
 125     {
 126         Insert(pos, wxMenuItem::New((wxMenu *)this));
 127     }
 128
 129     // insert a check item
 130     void InsertCheckItem(size_t pos,
 131                          int itemid,
 132                          const wxString& text,
 133                          const wxString& help = wxEmptyString)
 134     {
 135         Insert(pos, itemid, text, help, wxITEM_CHECK);
 136     }
 137
 138     // insert a radio item
 139     void InsertRadioItem(size_t pos,
 140                          int itemid,
 141                          const wxString& text,
 142                          const wxString& help = wxEmptyString)
 143     {
 144         Insert(pos, itemid, text, help, wxITEM_RADIO);
 145     }
 146
 147     // insert a submenu
 148     void Insert(size_t pos,
 149                 int itemid,
 150                 const wxString& text,
 151                 wxMenu *submenu,
 152                 const wxString& help = wxEmptyString)
 153     {
 154         Insert(pos, wxMenuItem::New((wxMenu *)this, itemid, text, help,
 155                                     wxITEM_NORMAL, submenu));
 156     }
 157
 158     // prepend an item to the menu
 159     void Prepend(wxMenuItem *item)
 160     {
 161         Insert(0u, item);
 162     }
 163
 164     // prepend any item to the menu
 165     void Prepend(int itemid,
 166                  const wxString& text,
 167                  const wxString& help = wxEmptyString,
 168                  wxItemKind kind = wxITEM_NORMAL)
 169     {
 170         Insert(0u, itemid, text, help, kind);
 171     }
 172
 173     // prepend a separator
 174     void PrependSeparator()
 175     {
 176         InsertSeparator(0u);
 177     }
 178
 179     // prepend a check item
 180     void PrependCheckItem(int itemid,
 181                           const wxString& text,
 182                           const wxString& help = wxEmptyString)
 183     {
 184         InsertCheckItem(0u, itemid, text, help);
 185     }
 186
 187     // prepend a radio item
 188     void PrependRadioItem(int itemid,
 189                           const wxString& text,
 190                           const wxString& help = wxEmptyString)
 191     {
 192         InsertRadioItem(0u, itemid, text, help);
 193     }
 194
 195     // prepend a submenu
 196     void Prepend(int itemid,
 197                  const wxString& text,
 198                  wxMenu *submenu,
 199                  const wxString& help = wxEmptyString)
 200     {
 201         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)
 276     wxMenuBar *GetMenuBar() const { return m_menuBar; }
 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 m_menuBar != 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 #if WXWIN_COMPATIBILITY
 334     bool Enabled(int itemid) const { return IsEnabled(itemid); }
 335     bool Checked(int itemid) const { return IsChecked(itemid); }
 336
 337     wxMenuItem* FindItemForId(int itemId, wxMenu **itemMenu) const
 338         { return FindItem(itemId, itemMenu); }
 339
 340     wxList& GetItems() const { return (wxList &)m_items; }
 341 #endif // WXWIN_COMPATIBILITY
 342
 343 protected:
 344     // virtuals to override in derived classes
 345     // ---------------------------------------
 346
 347     virtual bool DoAppend(wxMenuItem *item);
 348     virtual bool DoInsert(size_t pos, wxMenuItem *item);
 349
 350     virtual wxMenuItem *DoRemove(wxMenuItem *item);
 351     virtual bool DoDelete(wxMenuItem *item);
 352     virtual bool DoDestroy(wxMenuItem *item);
 353
 354     // helpers
 355     // -------
 356
 357     // common part of all ctors
 358     void Init(long style);
 359
 360     // associate the submenu with this menu
 361     void AddSubMenu(wxMenu *submenu);
 362
 363     wxMenuBar     *m_menuBar;           // menubar we belong to or NULL
 364     wxMenu        *m_menuParent;        // parent menu or NULL
 365
 366     wxString       m_title;             // the menu title or label
 367     wxMenuItemList m_items;             // the list of menu items
 368
 369     wxWindow      *m_invokingWindow;    // for popup menus
 370
 371     long           m_style;             // combination of wxMENU_XXX flags
 372
 373     wxEvtHandler  *m_eventHandler;      // a pluggable in event handler
 374
 375     DECLARE_NO_COPY_CLASS(wxMenuBase)
 376 };
 377
 378 // ----------------------------------------------------------------------------
 379 // wxMenuBar
 380 // ----------------------------------------------------------------------------
 381
 382 class WXDLLEXPORT wxMenuBarBase : public wxWindow
 383 {
 384 public:
 385     // default ctor
 386     wxMenuBarBase();
 387
 388     // dtor will delete all menus we own
 389     virtual ~wxMenuBarBase();
 390
 391     // menu bar construction
 392     // ---------------------
 393
 394     // append a menu to the end of menubar, return TRUE if ok
 395     virtual bool Append(wxMenu *menu, const wxString& title);
 396
 397     // insert a menu before the given position into the menubar, return TRUE
 398     // if inserted ok
 399     virtual bool Insert(size_t pos, wxMenu *menu, const wxString& title);
 400
 401     // menu bar items access
 402     // ---------------------
 403
 404     // get the number of menus in the menu bar
 405     size_t GetMenuCount() const { return m_menus.GetCount(); }
 406
 407     // get the menu at given position
 408     wxMenu *GetMenu(size_t pos) const;
 409
 410     // replace the menu at given position with another one, returns the
 411     // previous menu (which should be deleted by the caller)
 412     virtual wxMenu *Replace(size_t pos, wxMenu *menu, const wxString& title);
 413
 414     // delete the menu at given position from the menu bar, return the pointer
 415     // to the menu (which should be  deleted by the caller)
 416     virtual wxMenu *Remove(size_t pos);
 417
 418     // enable or disable a submenu
 419     virtual void EnableTop(size_t pos, bool enable) = 0;
 420
 421     // is the menu enabled?
 422     virtual bool IsEnabledTop(size_t WXUNUSED(pos)) const { return TRUE; }
 423
 424     // get or change the label of the menu at given position
 425     virtual void SetLabelTop(size_t pos, const wxString& label) = 0;
 426     virtual wxString GetLabelTop(size_t pos) const = 0;
 427
 428     // item search
 429     // -----------
 430
 431     // by menu and item names, returns wxNOT_FOUND if not found or id of the
 432     // found item
 433     virtual int FindMenuItem(const wxString& menu, const wxString& item) const;
 434
 435     // find item by id (in any menu), returns NULL if not found
 436     //
 437     // if menu is !NULL, it will be filled with wxMenu this item belongs to
 438     virtual wxMenuItem* FindItem(int itemid, wxMenu **menu = NULL) const;
 439
 440     // find menu by its caption, return wxNOT_FOUND on failure
 441     int FindMenu(const wxString& title) const;
 442
 443     // item access
 444     // -----------
 445
 446     // all these functions just use FindItem() and then call an appropriate
 447     // method on it
 448     //
 449     // NB: under MSW, these methods can only be used after the menubar had
 450     //     been attached to the frame
 451
 452     void Enable(int itemid, bool enable);
 453     void Check(int itemid, bool check);
 454     bool IsChecked(int itemid) const;
 455     bool IsEnabled(int itemid) const;
 456
 457     void SetLabel(int itemid, const wxString &label);
 458     wxString GetLabel(int itemid) const;
 459
 460     void SetHelpString(int itemid, const wxString& helpString);
 461     wxString GetHelpString(int itemid) const;
 462
 463     // implementation helpers
 464
 465     // get the frame we are attached to (may return NULL)
 466     wxFrame *GetFrame() const { return m_menuBarFrame; }
 467
 468     // returns TRUE if we're attached to a frame
 469     bool IsAttached() const { return GetFrame() != NULL; }
 470
 471     // associate the menubar with the frame
 472     virtual void Attach(wxFrame *frame);
 473
 474     // called before deleting the menubar normally
 475     virtual void Detach();
 476
 477     // need to override these ones to avoid virtual function hiding
 478     virtual bool Enable(bool enable = TRUE) { return wxWindow::Enable(enable); }
 479     virtual void SetLabel(const wxString& s) { wxWindow::SetLabel(s); }
 480     virtual wxString GetLabel() const { return wxWindow::GetLabel(); }
 481
 482     // don't want menu bars to accept the focus by tabbing to them
 483     virtual bool AcceptsFocusFromKeyboard() const { return FALSE; }
 484
 485     // compatibility only: these functions are deprecated, use the new ones
 486     // instead
 487 #if WXWIN_COMPATIBILITY
 488     bool Enabled(int itemid) const { return IsEnabled(itemid); }
 489     bool Checked(int itemid) const { return IsChecked(itemid); }
 490
 491     wxMenuItem* FindMenuItemById(int itemid) const
 492         { return FindItem(itemid); }
 493     wxMenuItem* FindItemForId(int itemid, wxMenu **menu = NULL) const
 494         { return FindItem(itemid, menu); }
 495 #endif // WXWIN_COMPATIBILITY
 496
 497 protected:
 498     // the list of all our menus
 499     wxMenuList m_menus;
 500
 501     // the frame we are attached to (may be NULL)
 502     wxFrame *m_menuBarFrame;
 503
 504     DECLARE_NO_COPY_CLASS(wxMenuBarBase)
 505 };
 506
 507 // ----------------------------------------------------------------------------
 508 // include the real class declaration
 509 // ----------------------------------------------------------------------------
 510
 511 #ifdef wxUSE_BASE_CLASSES_ONLY
 512     #define wxMenuItem wxMenuItemBase
 513 #else // !wxUSE_BASE_CLASSES_ONLY
 514 #if defined(__WXUNIVERSAL__)
 515     #include "wx/univ/menu.h"
 516 #elif defined(__WXMSW__)
 517     #include "wx/msw/menu.h"
 518 #elif defined(__WXMOTIF__)
 519     #include "wx/motif/menu.h"
 520 #elif defined(__WXGTK__)
 521     #include "wx/gtk/menu.h"
 522 #elif defined(__WXMAC__)
 523     #include "wx/mac/menu.h"
 524 #elif defined(__WXCOCOA__)
 525     #include "wx/cocoa/menu.h"
 526 #elif defined(__WXPM__)
 527     #include "wx/os2/menu.h"
 528 #endif
 529 #endif // wxUSE_BASE_CLASSES_ONLY/!wxUSE_BASE_CLASSES_ONLY
 530
 531 #endif // wxUSE_MENUS
 532
 533 #endif
 534     // _WX_MENU_H_BASE_