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 protected:
 334     // virtuals to override in derived classes
 335     // ---------------------------------------
 336
 337     virtual bool DoAppend(wxMenuItem *item);
 338     virtual bool DoInsert(size_t pos, wxMenuItem *item);
 339
 340     virtual wxMenuItem *DoRemove(wxMenuItem *item);
 341     virtual bool DoDelete(wxMenuItem *item);
 342     virtual bool DoDestroy(wxMenuItem *item);
 343
 344     // helpers
 345     // -------
 346
 347     // common part of all ctors
 348     void Init(long style);
 349
 350     // associate the submenu with this menu
 351     void AddSubMenu(wxMenu *submenu);
 352
 353     wxMenuBar     *m_menuBar;           // menubar we belong to or NULL
 354     wxMenu        *m_menuParent;        // parent menu or NULL
 355
 356     wxString       m_title;             // the menu title or label
 357     wxMenuItemList m_items;             // the list of menu items
 358
 359     wxWindow      *m_invokingWindow;    // for popup menus
 360
 361     long           m_style;             // combination of wxMENU_XXX flags
 362
 363     wxEvtHandler  *m_eventHandler;      // a pluggable in event handler
 364
 365     DECLARE_NO_COPY_CLASS(wxMenuBase)
 366 };
 367
 368 // ----------------------------------------------------------------------------
 369 // wxMenuBar
 370 // ----------------------------------------------------------------------------
 371
 372 class WXDLLEXPORT wxMenuBarBase : public wxWindow
 373 {
 374 public:
 375     // default ctor
 376     wxMenuBarBase();
 377
 378     // dtor will delete all menus we own
 379     virtual ~wxMenuBarBase();
 380
 381     // menu bar construction
 382     // ---------------------
 383
 384     // append a menu to the end of menubar, return TRUE if ok
 385     virtual bool Append(wxMenu *menu, const wxString& title);
 386
 387     // insert a menu before the given position into the menubar, return TRUE
 388     // if inserted ok
 389     virtual bool Insert(size_t pos, wxMenu *menu, const wxString& title);
 390
 391     // menu bar items access
 392     // ---------------------
 393
 394     // get the number of menus in the menu bar
 395     size_t GetMenuCount() const { return m_menus.GetCount(); }
 396
 397     // get the menu at given position
 398     wxMenu *GetMenu(size_t pos) const;
 399
 400     // replace the menu at given position with another one, returns the
 401     // previous menu (which should be deleted by the caller)
 402     virtual wxMenu *Replace(size_t pos, wxMenu *menu, const wxString& title);
 403
 404     // delete the menu at given position from the menu bar, return the pointer
 405     // to the menu (which should be  deleted by the caller)
 406     virtual wxMenu *Remove(size_t pos);
 407
 408     // enable or disable a submenu
 409     virtual void EnableTop(size_t pos, bool enable) = 0;
 410
 411     // is the menu enabled?
 412     virtual bool IsEnabledTop(size_t WXUNUSED(pos)) const { return TRUE; }
 413
 414     // get or change the label of the menu at given position
 415     virtual void SetLabelTop(size_t pos, const wxString& label) = 0;
 416     virtual wxString GetLabelTop(size_t pos) const = 0;
 417
 418     // item search
 419     // -----------
 420
 421     // by menu and item names, returns wxNOT_FOUND if not found or id of the
 422     // found item
 423     virtual int FindMenuItem(const wxString& menu, const wxString& item) const;
 424
 425     // find item by id (in any menu), returns NULL if not found
 426     //
 427     // if menu is !NULL, it will be filled with wxMenu this item belongs to
 428     virtual wxMenuItem* FindItem(int itemid, wxMenu **menu = NULL) const;
 429
 430     // find menu by its caption, return wxNOT_FOUND on failure
 431     int FindMenu(const wxString& title) const;
 432
 433     // item access
 434     // -----------
 435
 436     // all these functions just use FindItem() and then call an appropriate
 437     // method on it
 438     //
 439     // NB: under MSW, these methods can only be used after the menubar had
 440     //     been attached to the frame
 441
 442     void Enable(int itemid, bool enable);
 443     void Check(int itemid, bool check);
 444     bool IsChecked(int itemid) const;
 445     bool IsEnabled(int itemid) const;
 446
 447     void SetLabel(int itemid, const wxString &label);
 448     wxString GetLabel(int itemid) const;
 449
 450     void SetHelpString(int itemid, const wxString& helpString);
 451     wxString GetHelpString(int itemid) const;
 452
 453     // implementation helpers
 454
 455     // get the frame we are attached to (may return NULL)
 456     wxFrame *GetFrame() const { return m_menuBarFrame; }
 457
 458     // returns TRUE if we're attached to a frame
 459     bool IsAttached() const { return GetFrame() != NULL; }
 460
 461     // associate the menubar with the frame
 462     virtual void Attach(wxFrame *frame);
 463
 464     // called before deleting the menubar normally
 465     virtual void Detach();
 466
 467     // need to override these ones to avoid virtual function hiding
 468     virtual bool Enable(bool enable = TRUE) { return wxWindow::Enable(enable); }
 469     virtual void SetLabel(const wxString& s) { wxWindow::SetLabel(s); }
 470     virtual wxString GetLabel() const { return wxWindow::GetLabel(); }
 471
 472     // don't want menu bars to accept the focus by tabbing to them
 473     virtual bool AcceptsFocusFromKeyboard() const { return FALSE; }
 474
 475 protected:
 476     // the list of all our menus
 477     wxMenuList m_menus;
 478
 479     // the frame we are attached to (may be NULL)
 480     wxFrame *m_menuBarFrame;
 481
 482     DECLARE_NO_COPY_CLASS(wxMenuBarBase)
 483 };
 484
 485 // ----------------------------------------------------------------------------
 486 // include the real class declaration
 487 // ----------------------------------------------------------------------------
 488
 489 #ifdef wxUSE_BASE_CLASSES_ONLY
 490     #define wxMenuItem wxMenuItemBase
 491 #else // !wxUSE_BASE_CLASSES_ONLY
 492 #if defined(__WXUNIVERSAL__)
 493     #include "wx/univ/menu.h"
 494 #elif defined(__WXMSW__)
 495     #include "wx/msw/menu.h"
 496 #elif defined(__WXMOTIF__)
 497     #include "wx/motif/menu.h"
 498 #elif defined(__WXGTK__)
 499     #include "wx/gtk/menu.h"
 500 #elif defined(__WXMAC__)
 501     #include "wx/mac/menu.h"
 502 #elif defined(__WXCOCOA__)
 503     #include "wx/cocoa/menu.h"
 504 #elif defined(__WXPM__)
 505     #include "wx/os2/menu.h"
 506 #endif
 507 #endif // wxUSE_BASE_CLASSES_ONLY/!wxUSE_BASE_CLASSES_ONLY
 508
 509 #endif // wxUSE_MENUS
 510
 511 #endif
 512     // _WX_MENU_H_BASE_