interface/wx/menu.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        menu.h
   3 // Purpose:     interface of wxMenuBar
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxMenuBar
  11
  12     A menu bar is a series of menus accessible from the top of a frame.
  13
  14     @remarks
  15     To respond to a menu selection, provide a handler for EVT_MENU, in the frame
  16     that contains the menu bar.
  17
  18     If you have a toolbar which uses the same identifiers as your EVT_MENU entries,
  19     events from the toolbar will also be processed by your EVT_MENU event handlers.
  20
  21     Tip: under Windows, if you discover that menu shortcuts (for example, Alt-F
  22     to show the file menu) are not working, check any EVT_CHAR events you are
  23     handling in child windows.
  24     If you are not calling event.Skip() for events that you don't process in
  25     these event handlers, menu shortcuts may cease to work.
  26
  27     @library{wxcore}
  28     @category{menus}
  29
  30     @see wxMenu, @ref overview_events
  31 */
  32 class wxMenuBar : public wxWindow
  33 {
  34 public:
  35     /**
  36         Construct an empty menu bar.
  37
  38         @param style
  39             If wxMB_DOCKABLE the menu bar can be detached (wxGTK only).
  40     */
  41     wxMenuBar(long style = 0);
  42
  43     /**
  44         Construct a menu bar from arrays of menus and titles.
  45
  46         @param n
  47             The number of menus.
  48         @param menus
  49             An array of menus. Do not use this array again - it now belongs to
  50             the menu bar.
  51         @param titles
  52             An array of title strings. Deallocate this array after creating
  53             the menu bar.
  54         @param style
  55             If wxMB_DOCKABLE the menu bar can be detached (wxGTK only).
  56
  57         @beginWxPerlOnly
  58         Not supported by wxPerl.
  59         @endWxPerlOnly
  60     */
  61     wxMenuBar(size_t n, wxMenu* menus[], const wxString titles[],
  62               long style = 0);
  63
  64     /**
  65         Destructor, destroying the menu bar and removing it from the parent
  66         frame (if any).
  67     */
  68     virtual ~wxMenuBar();
  69
  70     /**
  71         Adds the item to the end of the menu bar.
  72
  73         @param menu
  74             The menu to add. Do not deallocate this menu after calling Append().
  75         @param title
  76             The title of the menu, must be non-empty.
  77
  78         @return @true on success, @false if an error occurred.
  79
  80         @see Insert()
  81     */
  82     virtual bool Append(wxMenu* menu, const wxString& title);
  83
  84     /**
  85         Checks or unchecks a menu item.
  86
  87         @param id
  88             The menu item identifier.
  89         @param check
  90             If @true, checks the menu item, otherwise the item is unchecked.
  91
  92         @remarks Only use this when the menu bar has been associated with a
  93                  frame; otherwise, use the wxMenu equivalent call.
  94     */
  95     void Check(int id, bool check);
  96
  97     /**
  98         Enables or disables (greys out) a menu item.
  99
 100         @param id
 101             The menu item identifier.
 102         @param enable
 103             @true to enable the item, @false to disable it.
 104
 105         @remarks Only use this when the menu bar has been associated with a
 106                  frame; otherwise, use the wxMenu equivalent call.
 107     */
 108     void Enable(int id, bool enable);
 109
 110     /**
 111         Returns true if the menu with the given index is enabled.
 112
 113         @param pos
 114             The menu position (0-based)
 115
 116         @since 2.9.4
 117     */
 118     bool IsEnabledTop(size_t pos) const;
 119
 120     /**
 121         Enables or disables a whole menu.
 122
 123         @param pos
 124             The position of the menu, starting from zero.
 125         @param enable
 126             @true to enable the menu, @false to disable it.
 127
 128         @remarks Only use this when the menu bar has been associated with a frame.
 129     */
 130     virtual void EnableTop(size_t pos, bool enable);
 131
 132     /**
 133         Finds the menu item object associated with the given menu item identifier.
 134
 135         @param id
 136             Menu item identifier.
 137         @param menu
 138             If not @NULL, menu will get set to the associated menu.
 139
 140         @return The found menu item object, or @NULL if one was not found.
 141
 142         @beginWxPerlOnly
 143         In wxPerl this method takes just the @a id parameter;
 144         in scalar context it returns the associated @c Wx::MenuItem, in list
 145         context it returns a 2-element list (item, submenu).
 146         @endWxPerlOnly
 147     */
 148     virtual wxMenuItem* FindItem(int id, wxMenu** menu = NULL) const;
 149
 150     /**
 151         Returns the index of the menu with the given @a title or @c wxNOT_FOUND if no
 152         such menu exists in this menubar.
 153
 154         The @a title parameter may specify either the menu title
 155         (with accelerator characters, i.e. @c "&File") or just the
 156         menu label (@c "File") indifferently.
 157     */
 158     int FindMenu(const wxString& title) const;
 159
 160     /**
 161         Finds the menu item id for a menu name/menu item string pair.
 162
 163         @param menuString
 164             Menu title to find.
 165         @param itemString
 166             Item to find.
 167
 168         @return The menu item identifier, or wxNOT_FOUND if none was found.
 169
 170         @remarks Any special menu codes are stripped out of source and target
 171                  strings before matching.
 172     */
 173     virtual int FindMenuItem(const wxString& menuString,
 174                              const wxString& itemString) const;
 175
 176     /**
 177         Gets the help string associated with the menu item identifier.
 178
 179         @param id
 180             The menu item identifier.
 181
 182         @return The help string, or the empty string if there was no help string
 183                 or the menu item was not found.
 184
 185         @see SetHelpString()
 186     */
 187     wxString GetHelpString(int id) const;
 188
 189     /**
 190         Gets the label associated with a menu item.
 191
 192         @param id
 193             The menu item identifier.
 194
 195         @return The menu item label, or the empty string if the item was not
 196                 found.
 197
 198         @remarks Use only after the menubar has been associated with a frame.
 199     */
 200     wxString GetLabel(int id) const;
 201
 202     /**
 203         Returns the label of a top-level menu. Note that the returned string does not
 204         include the accelerator characters which could have been specified in the menu
 205         title string during its construction.
 206
 207         @param pos
 208             Position of the menu on the menu bar, starting from zero.
 209
 210         @return The menu label, or the empty string if the menu was not found.
 211
 212         @remarks Use only after the menubar has been associated with a frame.
 213
 214         @deprecated
 215         This function is deprecated in favour of GetMenuLabel() and GetMenuLabelText().
 216
 217         @see SetLabelTop()
 218     */
 219     wxString GetLabelTop(size_t pos) const;
 220
 221     /**
 222         Returns the menu at @a menuIndex (zero-based).
 223     */
 224     wxMenu* GetMenu(size_t menuIndex) const;
 225
 226     /**
 227         Returns the number of menus in this menubar.
 228     */
 229     size_t GetMenuCount() const;
 230
 231     /**
 232         Returns the label of a top-level menu. Note that the returned string
 233         includes the accelerator characters that have been specified in the menu
 234         title string during its construction.
 235
 236         @param pos
 237             Position of the menu on the menu bar, starting from zero.
 238
 239         @return The menu label, or the empty string if the menu was not found.
 240
 241         @remarks Use only after the menubar has been associated with a frame.
 242
 243         @see GetMenuLabelText(), SetMenuLabel()
 244     */
 245     virtual wxString GetMenuLabel(size_t pos) const;
 246
 247     /**
 248         Returns the label of a top-level menu. Note that the returned string does not
 249         include any accelerator characters that may have been specified in the menu
 250         title string during its construction.
 251
 252         @param pos
 253             Position of the menu on the menu bar, starting from zero.
 254
 255         @return The menu label, or the empty string if the menu was not found.
 256
 257         @remarks Use only after the menubar has been associated with a frame.
 258
 259         @see GetMenuLabel(), SetMenuLabel()
 260     */
 261     virtual wxString GetMenuLabelText(size_t pos) const;
 262
 263     /**
 264         Inserts the menu at the given position into the menu bar. Inserting menu at
 265         position 0 will insert it in the very beginning of it, inserting at position
 266         GetMenuCount() is the same as calling Append().
 267
 268         @param pos
 269             The position of the new menu in the menu bar
 270         @param menu
 271             The menu to add. wxMenuBar owns the menu and will free it.
 272         @param title
 273             The title of the menu.
 274
 275         @return @true on success, @false if an error occurred.
 276
 277         @see Append()
 278     */
 279     virtual bool Insert(size_t pos, wxMenu* menu, const wxString& title);
 280
 281     /**
 282         Determines whether an item is checked.
 283
 284         @param id
 285             The menu item identifier.
 286
 287         @return @true if the item was found and is checked, @false otherwise.
 288     */
 289     bool IsChecked(int id) const;
 290
 291     /**
 292         Determines whether an item is enabled.
 293
 294         @param id
 295             The menu item identifier.
 296
 297         @return @true if the item was found and is enabled, @false otherwise.
 298     */
 299     bool IsEnabled(int id) const;
 300
 301     /**
 302         Redraw the menu bar
 303     */
 304     virtual void Refresh(bool eraseBackground = true, const wxRect* rect = NULL);
 305
 306     /**
 307         Removes the menu from the menu bar and returns the menu object - the caller
 308         is responsible for deleting it. This function may be used together with
 309         Insert() to change the menubar dynamically.
 310
 311         @see Replace()
 312     */
 313     virtual wxMenu* Remove(size_t pos);
 314
 315     /**
 316         Replaces the menu at the given position with another one.
 317
 318         @param pos
 319             The position of the new menu in the menu bar
 320         @param menu
 321             The menu to add.
 322         @param title
 323             The title of the menu.
 324
 325         @return The menu which was previously at position pos.
 326                 The caller is responsible for deleting it.
 327
 328         @see Insert(), Remove()
 329     */
 330     virtual wxMenu* Replace(size_t pos, wxMenu* menu, const wxString& title);
 331
 332     /**
 333         Sets the help string associated with a menu item.
 334
 335         @param id
 336             Menu item identifier.
 337         @param helpString
 338             Help string to associate with the menu item.
 339
 340         @see GetHelpString()
 341     */
 342     void SetHelpString(int id, const wxString& helpString);
 343
 344     /**
 345         Sets the label of a menu item.
 346
 347         @param id
 348             Menu item identifier.
 349         @param label
 350             Menu item label.
 351
 352         @remarks Use only after the menubar has been associated with a frame.
 353
 354         @see GetLabel()
 355     */
 356     void SetLabel(int id, const wxString& label);
 357
 358     /**
 359         Sets the label of a top-level menu.
 360
 361         @param pos
 362             The position of a menu on the menu bar, starting from zero.
 363         @param label
 364             The menu label.
 365
 366         @remarks Use only after the menubar has been associated with a frame.
 367
 368         @deprecated
 369         This function has been deprecated in favour of SetMenuLabel().
 370
 371         @see GetLabelTop()
 372     */
 373     void SetLabelTop(size_t pos, const wxString& label);
 374
 375     /**
 376         Sets the label of a top-level menu.
 377
 378         @param pos
 379             The position of a menu on the menu bar, starting from zero.
 380         @param label
 381             The menu label.
 382
 383         @remarks Use only after the menubar has been associated with a frame.
 384     */
 385     virtual void SetMenuLabel(size_t pos, const wxString& label);
 386
 387     /**
 388         Enables you to set the global menubar on Mac, that is, the menubar displayed
 389         when the app is running without any frames open.
 390
 391         @param menubar
 392             The menubar to set.
 393
 394         @remarks Only exists on Mac, other platforms do not have this method.
 395     */
 396     static void MacSetCommonMenuBar(wxMenuBar* menubar);
 397
 398     /**
 399         Enables you to get the global menubar on Mac, that is, the menubar displayed
 400         when the app is running without any frames open.
 401
 402         @return The global menubar.
 403
 404         @remarks Only exists on Mac, other platforms do not have this method.
 405     */
 406     static wxMenuBar* MacGetCommonMenuBar();
 407
 408     wxFrame *GetFrame() const;
 409     bool IsAttached() const;
 410     virtual void Attach(wxFrame *frame);
 411     virtual void Detach();
 412
 413 };
 414
 415
 416
 417 /**
 418     @class wxMenu
 419
 420     A menu is a popup (or pull down) list of items, one of which may be
 421     selected before the menu goes away (clicking elsewhere dismisses the
 422     menu). Menus may be used to construct either menu bars or popup menus.
 423
 424     A menu item has an integer ID associated with it which can be used to
 425     identify the selection, or to change the menu item in some way. A menu item
 426     with a special identifier @e wxID_SEPARATOR is a separator item and doesn't
 427     have an associated command but just makes a separator line appear in the
 428     menu.
 429
 430     @note
 431     Please note that @e wxID_ABOUT and @e wxID_EXIT are predefined by wxWidgets
 432     and have a special meaning since entries using these IDs will be taken out
 433     of the normal menus under MacOS X and will be inserted into the system menu
 434     (following the appropriate MacOS X interface guideline).
 435
 436     Menu items may be either @e normal items, @e check items or @e radio items.
 437     Normal items don't have any special properties while the check items have a
 438     boolean flag associated to them and they show a checkmark in the menu when
 439     the flag is set.
 440     wxWidgets automatically toggles the flag value when the item is clicked and its
 441     value may be retrieved using either wxMenu::IsChecked method of wxMenu or
 442     wxMenuBar itself or by using wxEvent::IsChecked when you get the menu
 443     notification for the item in question.
 444
 445     The radio items are similar to the check items except that all the other items
 446     in the same radio group are unchecked when a radio item is checked. The radio
 447     group is formed by a contiguous range of radio items, i.e. it starts at the
 448     first item of this kind and ends with the first item of a different kind (or
 449     the end of the menu). Notice that because the radio groups are defined in terms
 450     of the item positions inserting or removing the items in the menu containing
 451     the radio items risks to not work correctly.
 452
 453
 454     @section menu_allocation Allocation strategy
 455
 456     All menus must be created on the @b heap because all menus attached to a
 457     menubar or to another menu will be deleted by their parent when it is
 458     deleted. The only exception to this rule are the popup menus (i.e. menus
 459     used with wxWindow::PopupMenu()) as wxWidgets does not destroy them to
 460     allow reusing the same menu more than once. But the exception applies only
 461     to the menus themselves and not to any submenus of popup menus which are
 462     still destroyed by wxWidgets as usual and so must be heap-allocated.
 463
 464     As the frame menubar is deleted by the frame itself, it means that normally
 465     all menus used are deleted automatically.
 466
 467
 468     @section menu_eventhandling Event handling
 469
 470     If the menu is part of a menubar, then wxMenuBar event processing is used.
 471
 472     With a popup menu (see wxWindow::PopupMenu), there is a variety of ways to
 473     handle a menu selection event (@c wxEVT_COMMAND_MENU_SELECTED):
 474     - Provide @c EVT_MENU handlers in the window which pops up the menu, or in an
 475       ancestor of that window (the simplest method);
 476     - Derive a new class from wxMenu and define event table entries using the @c EVT_MENU macro;
 477     - Set a new event handler for wxMenu, through wxEvtHandler::SetNextHandler,
 478       specifying an object whose class has @c EVT_MENU entries;
 479
 480     Note that instead of static @c EVT_MENU macros you can also use dynamic
 481     connection; see @ref overview_events_bind.
 482
 483     @library{wxcore}
 484     @category{menus}
 485
 486     @see wxMenuBar, wxWindow::PopupMenu, @ref overview_events,
 487          @ref wxFileHistory "wxFileHistory (most recently used files menu)"
 488 */
 489 class wxMenu : public wxEvtHandler
 490 {
 491 public:
 492
 493     /**
 494         Constructs a wxMenu object.
 495     */
 496     wxMenu();
 497
 498     /**
 499         Constructs a wxMenu object.
 500
 501         @param style
 502             If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only).
 503     */
 504     wxMenu(long style);
 505
 506     /**
 507         Constructs a wxMenu object with a title.
 508
 509         @param title
 510             Title at the top of the menu (not always supported).
 511         @param style
 512             If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only).
 513     */
 514     wxMenu(const wxString& title, long style = 0);
 515
 516     /**
 517         Destructor, destroying the menu.
 518
 519         @note
 520             Under Motif, a popup menu must have a valid parent (the window
 521             it was last popped up on) when being destroyed. Therefore, make sure
 522             you delete or re-use the popup menu @e before destroying the parent
 523             window. Re-use in this context means popping up the menu on a different
 524             window from last time, which causes an implicit destruction and
 525             recreation of internal data structures.
 526     */
 527     virtual ~wxMenu();
 528
 529     /**
 530         Adds a menu item.
 531
 532         @param id
 533             The menu command identifier.
 534         @param item
 535             The string to appear on the menu item.
 536             See wxMenuItem::SetItemLabel() for more details.
 537         @param helpString
 538             An optional help string associated with the item.
 539             By default, the handler for the @c wxEVT_MENU_HIGHLIGHT event displays
 540             this string in the status line.
 541         @param kind
 542             May be @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, @c wxITEM_CHECK or @c wxITEM_RADIO.
 543
 544         Example:
 545         @code
 546         m_pFileMenu->Append(ID_NEW_FILE, "&New file\tCTRL+N", "Creates a new XYZ document");
 547         @endcode
 548         or even better for stock menu items (see wxMenuItem::wxMenuItem):
 549         @code
 550         m_pFileMenu->Append(wxID_NEW, "", "Creates a new XYZ document");
 551         @endcode
 552
 553         @remarks
 554         This command can be used after the menu has been shown, as well as on
 555         initial creation of a menu or menubar.
 556
 557         @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
 558              AppendSubMenu(), Insert(), SetLabel(), GetHelpString(),
 559              SetHelpString(), wxMenuItem
 560     */
 561     wxMenuItem* Append(int id, const wxString& item = wxEmptyString,
 562                        const wxString& helpString = wxEmptyString,
 563                        wxItemKind kind = wxITEM_NORMAL);
 564
 565     /**
 566         Adds a submenu.
 567
 568         @deprecated This function is deprecated, use AppendSubMenu() instead.
 569
 570         @param id
 571             The menu command identifier.
 572         @param item
 573             The string to appear on the menu item.
 574         @param subMenu
 575             Pull-right submenu.
 576         @param helpString
 577             An optional help string associated with the item.
 578             By default, the handler for the @c wxEVT_MENU_HIGHLIGHT event displays
 579             this string in the status line.
 580
 581         @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
 582              AppendSubMenu(), Insert(), SetLabel(), GetHelpString(),
 583              SetHelpString(), wxMenuItem
 584     */
 585     wxMenuItem* Append(int id, const wxString& item, wxMenu* subMenu,
 586                        const wxString& helpString = wxEmptyString);
 587
 588     /**
 589         Adds a menu item object.
 590
 591         This is the most generic variant of Append() method because it may be
 592         used for both items (including separators) and submenus and because
 593         you can also specify various extra properties of a menu item this way,
 594         such as bitmaps and fonts.
 595
 596         @param menuItem
 597             A menuitem object. It will be owned by the wxMenu object after this
 598             function is called, so do not delete it yourself.
 599
 600         @remarks
 601             See the remarks for the other Append() overloads.
 602
 603         @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
 604              AppendSubMenu(), Insert(), SetLabel(), GetHelpString(),
 605              SetHelpString(), wxMenuItem
 606     */
 607     wxMenuItem* Append(wxMenuItem* menuItem);
 608
 609     /**
 610         Adds a checkable item to the end of the menu.
 611
 612         @see Append(), InsertCheckItem()
 613     */
 614     wxMenuItem* AppendCheckItem(int id, const wxString& item,
 615                                 const wxString& help = wxEmptyString);
 616
 617     /**
 618         Adds a radio item to the end of the menu.
 619         All consequent radio items form a group and when an item in the group is
 620         checked, all the others are automatically unchecked.
 621
 622         @note Radio items are not supported under wxMotif.
 623
 624         @see Append(), InsertRadioItem()
 625     */
 626     wxMenuItem* AppendRadioItem(int id, const wxString& item,
 627                                 const wxString& help = wxEmptyString);
 628
 629     /**
 630         Adds a separator to the end of the menu.
 631
 632         @see Append(), InsertSeparator()
 633     */
 634     wxMenuItem* AppendSeparator();
 635
 636     /**
 637         Adds the given @a submenu to this menu. @a text is the text shown in the
 638         menu for it and @a help is the help string shown in the status bar when the
 639         submenu item is selected.
 640     */
 641     wxMenuItem* AppendSubMenu(wxMenu* submenu, const wxString& text,
 642                               const wxString& help = wxEmptyString);
 643
 644     /**
 645         Inserts a break in a menu, causing the next appended item to appear in
 646         a new column.
 647     */
 648     virtual void Break();
 649
 650     /**
 651         Checks or unchecks the menu item.
 652
 653         @param id
 654             The menu item identifier.
 655         @param check
 656             If @true, the item will be checked, otherwise it will be unchecked.
 657
 658         @see IsChecked()
 659     */
 660     void Check(int id, bool check);
 661
 662     /**
 663         Deletes the menu item from the menu. If the item is a submenu, it will
 664         @b not be deleted. Use Destroy() if you want to delete a submenu.
 665
 666         @param id
 667             Id of the menu item to be deleted.
 668
 669         @see FindItem(), Destroy(), Remove()
 670     */
 671     bool Delete(int id);
 672
 673     /**
 674         Deletes the menu item from the menu. If the item is a submenu, it will
 675         @b not be deleted. Use Destroy() if you want to delete a submenu.
 676
 677         @param item
 678             Menu item to be deleted.
 679
 680         @see FindItem(), Destroy(), Remove()
 681     */
 682     bool Delete(wxMenuItem* item);
 683
 684     /**
 685         Deletes the menu item from the menu. If the item is a submenu, it will
 686         be deleted. Use Remove() if you want to keep the submenu (for example,
 687         to reuse it later).
 688
 689         @param id
 690             Id of the menu item to be deleted.
 691
 692         @see FindItem(), Delete(), Remove()
 693     */
 694     bool Destroy(int id);
 695
 696     /**
 697         Deletes the menu item from the menu. If the item is a submenu, it will
 698         be deleted. Use Remove() if you want to keep the submenu (for example,
 699         to reuse it later).
 700
 701         @param item
 702             Menu item to be deleted.
 703
 704         @see FindItem(), Delete(), Remove()
 705     */
 706     bool Destroy(wxMenuItem* item);
 707
 708     /**
 709         Enables or disables (greys out) a menu item.
 710
 711         @param id
 712             The menu item identifier.
 713         @param enable
 714             @true to enable the menu item, @false to disable it.
 715
 716         @see IsEnabled()
 717     */
 718     void Enable(int id, bool enable);
 719
 720     /**
 721       Finds the menu item object associated with the given menu item identifier
 722       and, optionally, the position of the item in the menu.
 723
 724       Unlike FindItem(), this function doesn't recurse but only looks at the
 725       direct children of this menu.
 726
 727       @param id
 728           The identifier of the menu item to find.
 729       @param pos
 730           If the pointer is not @NULL, it is filled with the item's position if
 731           it was found or @c (size_t)wxNOT_FOUND otherwise.
 732       @return
 733         Menu item object or @NULL if not found.
 734      */
 735     wxMenuItem *FindChildItem(int id, size_t *pos = NULL) const;
 736
 737     /**
 738         Finds the menu id for a menu item string.
 739
 740         @param itemString
 741             Menu item string to find.
 742
 743         @return Menu item identifier, or wxNOT_FOUND if none is found.
 744
 745         @remarks Any special menu codes are stripped out of source and target
 746                  strings before matching.
 747     */
 748     virtual int FindItem(const wxString& itemString) const;
 749
 750     /**
 751         Finds the menu item object associated with the given menu item identifier and,
 752         optionally, the (sub)menu it belongs to.
 753
 754         @param id
 755             Menu item identifier.
 756         @param menu
 757             If the pointer is not @NULL, it will be filled with the item's
 758             parent menu (if the item was found)
 759
 760         @return Menu item object or NULL if none is found.
 761     */
 762     wxMenuItem* FindItem(int id, wxMenu** menu = NULL) const;
 763
 764     /**
 765         Returns the wxMenuItem given a position in the menu.
 766     */
 767     wxMenuItem* FindItemByPosition(size_t position) const;
 768
 769     /**
 770         Returns the help string associated with a menu item.
 771
 772         @param id
 773             The menu item identifier.
 774
 775         @return The help string, or the empty string if there is no help string
 776                 or the item was not found.
 777
 778         @see SetHelpString(), Append()
 779     */
 780     virtual wxString GetHelpString(int id) const;
 781
 782     /**
 783         Returns a menu item label.
 784
 785         @param id
 786             The menu item identifier.
 787
 788         @return The item label, or the empty string if the item was not found.
 789
 790         @see GetLabelText(), SetLabel()
 791     */
 792     wxString GetLabel(int id) const;
 793
 794     /**
 795         Returns a menu item label, without any of the original mnemonics and
 796         accelerators.
 797
 798         @param id
 799             The menu item identifier.
 800
 801         @return The item label, or the empty string if the item was not found.
 802
 803         @see GetLabel(), SetLabel()
 804     */
 805     wxString GetLabelText(int id) const;
 806
 807     /**
 808         Returns the number of items in the menu.
 809     */
 810     size_t GetMenuItemCount() const;
 811
 812     //@{
 813     /**
 814         Returns the list of items in the menu.
 815
 816         wxMenuItemList is a pseudo-template list class containing wxMenuItem
 817         pointers, see wxList.
 818     */
 819     wxMenuItemList& GetMenuItems() const;
 820     const wxMenuItemList& GetMenuItems() const;
 821     //@}
 822
 823     /**
 824         Returns the title of the menu.
 825
 826         @see SetTitle()
 827     */
 828     const wxString& GetTitle() const;
 829
 830     /**
 831         Inserts the given @a item before the position @a pos.
 832
 833         Inserting the item at position GetMenuItemCount() is the same
 834         as appending it.
 835
 836         @see Append(), Prepend()
 837     */
 838     wxMenuItem* Insert(size_t pos, wxMenuItem* menuItem);
 839
 840     /**
 841         Inserts the given @a item before the position @a pos.
 842
 843         Inserting the item at position GetMenuItemCount() is the same
 844         as appending it.
 845
 846         @see Append(), Prepend()
 847     */
 848     wxMenuItem* Insert(size_t pos, int id,
 849                        const wxString& item = wxEmptyString,
 850                        const wxString& helpString = wxEmptyString,
 851                        wxItemKind kind = wxITEM_NORMAL);
 852
 853     /**
 854         Inserts a checkable item at the given position.
 855
 856         @see Insert(), AppendCheckItem()
 857     */
 858     wxMenuItem* InsertCheckItem(size_t pos, int id, const wxString& item,
 859                                 const wxString& helpString = wxEmptyString);
 860
 861     /**
 862         Inserts a radio item at the given position.
 863
 864         @see Insert(), AppendRadioItem()
 865     */
 866     wxMenuItem* InsertRadioItem(size_t pos, int id, const wxString& item,
 867                                 const wxString& helpString = wxEmptyString);
 868
 869     /**
 870         Inserts a separator at the given position.
 871
 872         @see Insert(), AppendSeparator()
 873     */
 874     wxMenuItem* InsertSeparator(size_t pos);
 875
 876     /**
 877         Determines whether a menu item is checked.
 878
 879         @param id
 880             The menu item identifier.
 881
 882         @return @true if the menu item is checked, @false otherwise.
 883
 884         @see Check()
 885     */
 886     bool IsChecked(int id) const;
 887
 888     /**
 889         Determines whether a menu item is enabled.
 890
 891         @param id
 892             The menu item identifier.
 893
 894         @return @true if the menu item is enabled, @false otherwise.
 895
 896         @see Enable()
 897     */
 898     bool IsEnabled(int id) const;
 899
 900     /**
 901         Inserts the given @a item at position 0, i.e. before all the other
 902         existing items.
 903
 904         @see Append(), Insert()
 905     */
 906     wxMenuItem* Prepend(wxMenuItem* item);
 907
 908     /**
 909         Inserts the given @a item at position 0, i.e. before all the other
 910         existing items.
 911
 912         @see Append(), Insert()
 913     */
 914     wxMenuItem* Prepend(int id, const wxString& item = wxEmptyString,
 915                         const wxString& helpString = wxEmptyString,
 916                         wxItemKind kind = wxITEM_NORMAL);
 917
 918     /**
 919         Inserts a checkable item at position 0.
 920
 921         @see Prepend(), AppendCheckItem()
 922     */
 923     wxMenuItem* PrependCheckItem(int id, const wxString& item,
 924                                  const wxString& helpString = wxEmptyString);
 925
 926     /**
 927         Inserts a radio item at position 0.
 928
 929         @see Prepend(), AppendRadioItem()
 930     */
 931     wxMenuItem* PrependRadioItem(int id, const wxString& item,
 932                                  const wxString& helpString = wxEmptyString);
 933
 934     /**
 935         Inserts a separator at position 0.
 936
 937         @see Prepend(), AppendSeparator()
 938     */
 939     wxMenuItem* PrependSeparator();
 940
 941     /**
 942         Removes the menu item from the menu but doesn't delete the associated C++
 943         object. This allows you to reuse the same item later by adding it back to
 944         the menu (especially useful with submenus).
 945
 946         @param id
 947             The identifier of the menu item to remove.
 948
 949         @return A pointer to the item which was detached from the menu.
 950     */
 951     wxMenuItem* Remove(int id);
 952
 953     /**
 954         Removes the menu item from the menu but doesn't delete the associated C++
 955         object. This allows you to reuse the same item later by adding it back to
 956         the menu (especially useful with submenus).
 957
 958         @param item
 959             The menu item to remove.
 960
 961         @return A pointer to the item which was detached from the menu.
 962     */
 963     wxMenuItem* Remove(wxMenuItem* item);
 964
 965     /**
 966         Sets an item's help string.
 967
 968         @param id
 969             The menu item identifier.
 970         @param helpString
 971             The help string to set.
 972
 973         @see GetHelpString()
 974     */
 975     virtual void SetHelpString(int id, const wxString& helpString);
 976
 977     /**
 978         Sets the label of a menu item.
 979
 980         @param id
 981             The menu item identifier.
 982         @param label
 983             The menu item label to set.
 984
 985         @see Append(), GetLabel()
 986     */
 987     void SetLabel(int id, const wxString& label);
 988
 989     /**
 990         Sets the title of the menu.
 991
 992         @param title
 993             The title to set.
 994
 995         @remarks Notice that you can only call this method directly for the
 996             popup menus, to change the title of a menu that is part of a menu
 997             bar you need to use wxMenuBar::SetLabelTop().
 998
 999         @see GetTitle()
1000     */
1001     virtual void SetTitle(const wxString& title);
1002
1003     /**
1004         Sends events to @a source (or owning window if @NULL) to update the
1005         menu UI.
1006
1007         This is called just before the menu is popped up with wxWindow::PopupMenu,
1008         but the application may call it at other times if required.
1009     */
1010     void UpdateUI(wxEvtHandler* source = NULL);
1011
1012
1013     void SetInvokingWindow(wxWindow *win);
1014     wxWindow *GetInvokingWindow() const;
1015     wxWindow *GetWindow() const;
1016     long GetStyle() const;
1017     void SetParent(wxMenu *parent);
1018     wxMenu *GetParent() const;
1019
1020     virtual void Attach(wxMenuBar *menubar);
1021     virtual void Detach();
1022     bool IsAttached() const;
1023
1024 };
1025