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 license
   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     @library{wxcore}
  15     @category{menus}
  16
  17     @see wxMenu, @ref overview_eventhandling "Event Handling Overview"
  18 */
  19 class wxMenuBar : public wxWindow
  20 {
  21 public:
  22     /**
  23         Construct an empty menu barM
  24
  25         @param style
  26             If wxMB_DOCKABLE the menu bar can be detached (wxGTK only).
  27     */
  28     wxMenuBar(long style = 0);
  29
  30     /**
  31         Construct a menu bar from arrays of menus and titles.
  32
  33         @param n
  34             The number of menus.
  35         @param menus
  36             An array of menus. Do not use this array again - it now belongs to
  37             the menu bar.
  38         @param titles
  39             An array of title strings. Deallocate this array after creating
  40             the menu bar.
  41         @param style
  42             If wxMB_DOCKABLE the menu bar can be detached (wxGTK only).
  43     */
  44     wxMenuBar(size_t n, wxMenu* menus[], const wxString titles[],
  45               long style = 0);
  46
  47     /**
  48         Destructor, destroying the menu bar and removing it from the parent frame (if
  49         any).
  50     */
  51     ~wxMenuBar();
  52
  53     /**
  54         Adds the item to the end of the menu bar.
  55
  56         @param menu
  57             The menu to add. Do not deallocate this menu after calling Append.
  58         @param title
  59             The title of the menu.
  60
  61         @return @true on success, @false if an error occurred.
  62
  63         @see Insert()
  64     */
  65     bool Append(wxMenu* menu, const wxString& title);
  66
  67     /**
  68         Checks or unchecks a menu item.
  69
  70         @param id
  71             The menu item identifier.
  72         @param check
  73             If @true, checks the menu item, otherwise the item is unchecked.
  74
  75         @remarks Only use this when the menu bar has been associated with a
  76                  frame; otherwise, use the wxMenu equivalent call.
  77     */
  78     void Check(int id, const bool check);
  79
  80     /**
  81         Enables or disables (greys out) a menu item.
  82
  83         @param id
  84             The menu item identifier.
  85         @param enable
  86             @true to enable the item, @false to disable it.
  87
  88         @remarks Only use this when the menu bar has been associated with a
  89                  frame; otherwise, use the wxMenu equivalent call.
  90     */
  91     void Enable(int id, const bool enable);
  92
  93     /**
  94         Enables or disables a whole menu.
  95
  96         @param pos
  97             The position of the menu, starting from zero.
  98         @param enable
  99             @true to enable the menu, @false to disable it.
 100
 101         @remarks Only use this when the menu bar has been associated with a frame.
 102     */
 103     void EnableTop(int pos, const bool enable);
 104
 105     /**
 106         Finds the menu item object associated with the given menu item identifier.
 107
 108         @param id
 109             Menu item identifier.
 110         @param menu
 111             If not @NULL, menu will get set to the associated menu.
 112
 113         @return The found menu item object, or @NULL if one was not found.
 114     */
 115     wxMenuItem* FindItem(int id, wxMenu menu = NULL) const;
 116
 117     /**
 118         Returns the index of the menu with the given @a title or @c wxNOT_FOUND if no
 119         such menu exists in this menubar. The @a title parameter may specify either
 120         the menu title (with accelerator characters, i.e. @c "File") or just the
 121         menu label (@c "File") indifferently.
 122     */
 123     int FindMenu(const wxString& title) const;
 124
 125     /**
 126         Finds the menu item id for a menu name/menu item string pair.
 127
 128         @param menuString
 129             Menu title to find.
 130         @param itemString
 131             Item to find.
 132
 133         @return The menu item identifier, or wxNOT_FOUND if none was found.
 134
 135         @remarks Any special menu codes are stripped out of source and target
 136                  strings before matching.
 137     */
 138     int FindMenuItem(const wxString& menuString,
 139                      const wxString& itemString) const;
 140
 141     /**
 142         Gets the help string associated with the menu item identifier.
 143
 144         @param id
 145             The menu item identifier.
 146
 147         @return The help string, or the empty string if there was no help string
 148                 or the menu item was not found.
 149
 150         @see SetHelpString()
 151     */
 152     wxString GetHelpString(int id) const;
 153
 154     /**
 155         Gets the label associated with a menu item.
 156
 157         @param id
 158             The menu item identifier.
 159
 160         @return The menu item label, or the empty string if the item was not
 161                 found.
 162
 163         @remarks Use only after the menubar has been associated with a frame.
 164     */
 165     wxString GetLabel(int id) const;
 166
 167     /**
 168         Returns the label of a top-level menu. Note that the returned string does not
 169         include the accelerator characters which could have been specified in the menu
 170         title string during its construction.
 171
 172         @param pos
 173             Position of the menu on the menu bar, starting from zero.
 174
 175         @return The menu label, or the empty string if the menu was not found.
 176
 177         @remarks Use only after the menubar has been associated with a frame.
 178
 179         @see SetLabelTop()
 180     */
 181     wxString GetLabelTop(int pos) const;
 182
 183     /**
 184         Returns the menu at @a menuIndex (zero-based).
 185     */
 186     wxMenu* GetMenu(int menuIndex) const;
 187
 188     /**
 189         Returns the number of menus in this menubar.
 190     */
 191     size_t GetMenuCount() const;
 192
 193     /**
 194         Returns the label of a top-level menu. Note that the returned string
 195         includes the accelerator characters that have been specified in the menu
 196         title string during its construction.
 197
 198         @param pos
 199             Position of the menu on the menu bar, starting from zero.
 200
 201         @return The menu label, or the empty string if the menu was not found.
 202
 203         @remarks Use only after the menubar has been associated with a frame.
 204
 205         @see GetMenuLabelText(), SetMenuLabel()
 206     */
 207     wxString GetMenuLabel(int pos) const;
 208
 209     /**
 210         Returns the label of a top-level menu. Note that the returned string does not
 211         include any accelerator characters that may have been specified in the menu
 212         title string during its construction.
 213
 214         @param pos
 215             Position of the menu on the menu bar, starting from zero.
 216
 217         @return The menu label, or the empty string if the menu was not found.
 218
 219         @remarks Use only after the menubar has been associated with a frame.
 220
 221         @see GetMenuLabel(), SetMenuLabel()
 222     */
 223     wxString GetMenuLabelText(int pos) const;
 224
 225     /**
 226         Inserts the menu at the given position into the menu bar. Inserting menu at
 227         position 0 will insert it in the very beginning of it, inserting at position
 228         GetMenuCount() is the same as calling
 229         Append().
 230
 231         @param pos
 232             The position of the new menu in the menu bar
 233         @param menu
 234             The menu to add. wxMenuBar owns the menu and will free it.
 235         @param title
 236             The title of the menu.
 237
 238         @return @true on success, @false if an error occurred.
 239
 240         @see Append()
 241     */
 242     bool Insert(size_t pos, wxMenu* menu, const wxString& title);
 243
 244     /**
 245         Determines whether an item is checked.
 246
 247         @param id
 248             The menu item identifier.
 249
 250         @return @true if the item was found and is checked, @false otherwise.
 251     */
 252     bool IsChecked(int id) const;
 253
 254     /**
 255         Determines whether an item is enabled.
 256
 257         @param id
 258             The menu item identifier.
 259
 260         @return @true if the item was found and is enabled, @false otherwise.
 261     */
 262     bool IsEnabled(int id) const;
 263
 264     /**
 265         Redraw the menu bar
 266     */
 267     void Refresh();
 268
 269     /**
 270         Removes the menu from the menu bar and returns the menu object - the caller is
 271         responsible for deleting it. This function may be used together with
 272         Insert() to change the menubar
 273         dynamically.
 274
 275         @see Replace()
 276     */
 277     wxMenu* Remove(size_t pos);
 278
 279     /**
 280         Replaces the menu at the given position with another one.
 281
 282         @param pos
 283             The position of the new menu in the menu bar
 284         @param menu
 285             The menu to add.
 286         @param title
 287             The title of the menu.
 288
 289         @return The menu which was previously at position pos. The caller is
 290                 responsible for deleting it.
 291
 292         @see Insert(), Remove()
 293     */
 294     wxMenu* Replace(size_t pos, wxMenu* menu, const wxString& title);
 295
 296     /**
 297         Sets the help string associated with a menu item.
 298
 299         @param id
 300             Menu item identifier.
 301         @param helpString
 302             Help string to associate with the menu item.
 303
 304         @see GetHelpString()
 305     */
 306     void SetHelpString(int id, const wxString& helpString);
 307
 308     /**
 309         Sets the label of a menu item.
 310
 311         @param id
 312             Menu item identifier.
 313         @param label
 314             Menu item label.
 315
 316         @remarks Use only after the menubar has been associated with a frame.
 317
 318         @see GetLabel()
 319     */
 320     void SetLabel(int id, const wxString& label);
 321
 322     /**
 323         Sets the label of a top-level menu.
 324
 325         @param pos
 326             The position of a menu on the menu bar, starting from zero.
 327         @param label
 328             The menu label.
 329
 330         @remarks Use only after the menubar has been associated with a frame.
 331
 332         @see GetLabelTop()
 333     */
 334     void SetLabelTop(int pos, const wxString& label);
 335
 336     /**
 337         Sets the label of a top-level menu.
 338
 339         @param pos
 340             The position of a menu on the menu bar, starting from zero.
 341         @param label
 342             The menu label.
 343
 344         @remarks Use only after the menubar has been associated with a frame.
 345     */
 346     void SetMenuLabel(int pos, const wxString& label);
 347 };
 348
 349
 350
 351 /**
 352     @class wxMenu
 353
 354     A menu is a popup (or pull down) list of items, one of which may be
 355     selected before the menu goes away (clicking elsewhere dismisses the
 356     menu). Menus may be used to construct either menu bars or popup menus.
 357
 358     A menu item has an integer ID associated with it which can be used to
 359     identify the selection, or to change the menu item in some way. A menu item
 360     with a special identifier -1 is a separator item and doesn't have an
 361     associated command but just makes a separator line appear in the menu.
 362
 363     @note Please note that @e wxID_ABOUT and @e wxID_EXIT are
 364     predefined by wxWidgets and have a special meaning since entries
 365     using these IDs will be taken out of the normal menus under MacOS X
 366     and will be inserted into the system menu (following the appropriate
 367     MacOS X interface guideline). On PalmOS @e wxID_EXIT is disabled according
 368     to Palm OS Companion guidelines.
 369
 370     Menu items may be either normal items, check items or radio items. Normal items
 371     don't have any special properties while the check items have a boolean flag
 372     associated to them and they show a checkmark in the menu when the flag is set.
 373     wxWidgets automatically toggles the flag value when the item is clicked and its
 374     value may be retrieved using either wxMenu::IsChecked method
 375     of wxMenu or wxMenuBar itself or by using
 376     wxEvent::IsChecked when you get the menu
 377     notification for the item in question.
 378
 379     The radio items are similar to the check items except that all the other items
 380     in the same radio group are unchecked when a radio item is checked. The radio
 381     group is formed by a contiguous range of radio items, i.e. it starts at the
 382     first item of this kind and ends with the first item of a different kind (or
 383     the end of the menu). Notice that because the radio groups are defined in terms
 384     of the item positions inserting or removing the items in the menu containing
 385     the radio items risks to not work correctly. Finally note that radio items
 386     are not supported under Motif.
 387
 388     @library{wxcore}
 389     @category{menus}
 390
 391     @see wxMenuBar, wxWindow::PopupMenu,
 392     @ref overview_eventhandling "Event Handling Overview",
 393     @ref wxFileHistory "wxFileHistory (most recently used files menu)"
 394 */
 395 class wxMenu : public wxEvtHandler
 396 {
 397 public:
 398     /**
 399         Constructs a wxMenu object.
 400
 401         @param style
 402             If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only).
 403     */
 404     wxMenu(long style);
 405
 406     /**
 407         Constructs a wxMenu object with a title
 408
 409         @param title
 410             Title at the top of the menu (not always supported).
 411         @param style
 412             If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only).
 413     */
 414     wxMenu(const wxString& title = "", long style = 0);
 415
 416     /**
 417         Destructor, destroying the menu.
 418         Note: under Motif, a popup menu must have a valid parent (the window
 419         it was last popped up on) when being destroyed. Therefore, make sure
 420         you delete or re-use the popup menu @e before destroying the
 421         parent window. Re-use in this context means popping up the menu on
 422         a different window from last time, which causes an implicit destruction
 423         and recreation of internal data structures.
 424     */
 425     ~wxMenu();
 426
 427     /**
 428         Adds a menu item.
 429
 430         @param id
 431             The menu command identifier.
 432         @param item
 433             The string to appear on the menu item.
 434         @param helpString
 435             An optional help string associated with the item.
 436             By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays
 437             this string in the status line.
 438         @param kind
 439             May be wxITEM_SEPARATOR, wxITEM_NORMAL,
 440             wxITEM_CHECK or wxITEM_RADIO
 441
 442         @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
 443              AppendSubMenu(), Insert(), SetLabel(),
 444              GetHelpString(), SetHelpString(), wxMenuItem
 445     */
 446     wxMenuItem* Append(int id, const wxString& item = wxEmptyString,
 447                        const wxString& helpString = wxEmptyString,
 448                        wxItemKind kind = wxITEM_NORMAL);
 449
 450     /**
 451         Adds a submenu.
 452
 453         @deprecated This function is deprecated, use AppendSubMenu() instead.
 454
 455         @param id
 456             The menu command identifier.
 457         @param item
 458             The string to appear on the menu item.
 459         @param subMenu
 460             Pull-right submenu.
 461         @param helpString
 462             An optional help string associated with the item.
 463             By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays
 464             this string in the status line.
 465
 466         @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
 467              AppendSubMenu(), Insert(), SetLabel(),
 468              GetHelpString(), SetHelpString(), wxMenuItem
 469     */
 470     wxMenuItem* Append(int id, const wxString& item,
 471                        wxMenu* subMenu,
 472                        const wxString& helpString = wxEmptyString);
 473
 474     /**
 475         Adds a menu item object. This is the most generic variant of Append() method
 476         because it may be used for both items (including separators) and submenus and
 477         because you can also specify various extra properties of a menu item this way,
 478         such as bitmaps and fonts.
 479
 480         @param menuItem
 481             A menuitem object. It will be owned by the wxMenu object after this function
 482             is called, so do not delete it yourself.
 483
 484         @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
 485              AppendSubMenu(), Insert(), SetLabel(),
 486              GetHelpString(), SetHelpString(), wxMenuItem
 487     */
 488     wxMenuItem* Append(wxMenuItem* menuItem);
 489
 490     /**
 491         Adds a checkable item to the end of the menu.
 492
 493         @see Append(), InsertCheckItem()
 494     */
 495     wxMenuItem* AppendCheckItem(int id, const wxString& item,
 496                                 const wxString& helpString = "");
 497
 498     /**
 499         Adds a radio item to the end of the menu. All consequent radio items form a
 500         group and when an item in the group is checked, all the others are
 501         automatically unchecked.
 502
 503         @see Append(), InsertRadioItem()
 504     */
 505     wxMenuItem* AppendRadioItem(int id, const wxString& item,
 506                                 const wxString& helpString = "");
 507
 508     /**
 509         Adds a separator to the end of the menu.
 510
 511         @see Append(), InsertSeparator()
 512     */
 513     wxMenuItem* AppendSeparator();
 514
 515     /**
 516         Adds the given @a submenu to this menu. @a text is the text shown in the
 517         menu for it and @a help is the help string shown in the status bar when the
 518         submenu item is selected.
 519     */
 520     wxMenuItem* AppendSubMenu(wxMenu* submenu, const wxString& text,
 521                               const wxString& help = wxEmptyString);
 522
 523     /**
 524         Inserts a break in a menu, causing the next appended item to appear in a new
 525         column.
 526     */
 527     void Break();
 528
 529     /**
 530         Checks or unchecks the menu item.
 531
 532         @param id
 533             The menu item identifier.
 534         @param check
 535             If @true, the item will be checked, otherwise it will be unchecked.
 536
 537         @see IsChecked()
 538     */
 539     void Check(int id, const bool check);
 540
 541     /**
 542         Deletes the menu item from the menu. If the item is a submenu, it will
 543         @b not be deleted. Use Destroy() if you want to delete a submenu.
 544
 545         @param id
 546             Id of the menu item to be deleted.
 547
 548         @see FindItem(), Destroy(), Remove()
 549     */
 550     void Delete(int id);
 551
 552     /**
 553         Deletes the menu item from the menu. If the item is a submenu, it will
 554         @b not be deleted. Use Destroy() if you want to delete a submenu.
 555
 556         @param item
 557             Menu item to be deleted.
 558
 559         @see FindItem(), Destroy(), Remove()
 560     */
 561     void Delete(wxMenuItem* item);
 562
 563     /**
 564         Deletes the menu item from the menu. If the item is a submenu, it will
 565         be deleted. Use Remove() if you want to keep the submenu (for example,
 566         to reuse it later).
 567
 568         @param id
 569             Id of the menu item to be deleted.
 570
 571         @see FindItem(), Deletes(), Remove()
 572     */
 573     void Destroy(int id);
 574
 575     /**
 576         Deletes the menu item from the menu. If the item is a submenu, it will
 577         be deleted. Use Remove() if you want to keep the submenu (for example,
 578         to reuse it later).
 579
 580         @param item
 581             Menu item to be deleted.
 582
 583         @see FindItem(), Deletes(), Remove()
 584     */
 585     void Destroy(wxMenuItem* item);
 586
 587     /**
 588         Enables or disables (greys out) a menu item.
 589
 590         @param id
 591             The menu item identifier.
 592         @param enable
 593             @true to enable the menu item, @false to disable it.
 594
 595         @see IsEnabled()
 596     */
 597     void Enable(int id, const bool enable);
 598
 599     /**
 600         Finds the menu id for a menu item string.
 601
 602         @param itemString
 603             Menu item string to find.
 604
 605         @return Menu item identifier, or wxNOT_FOUND if none is found.
 606
 607         @remarks Any special menu codes are stripped out of source and target
 608                  strings before matching.
 609     */
 610     int FindItem(const wxString& itemString) const;
 611
 612     /**
 613         Finds the menu item object associated with the given menu item identifier and,
 614         optionally, the (sub)menu it belongs to.
 615
 616         @param id
 617             Menu item identifier.
 618         @param menu
 619             If the pointer is not @NULL, it will be filled with the item's
 620             parent menu (if the item was found)
 621
 622         @return Menu item object or NULL if none is found.
 623     */
 624     const wxMenuItem *  FindItem(int id, wxMenu** menu = NULL) const;
 625
 626     /**
 627         Returns the wxMenuItem given a position in the menu.
 628     */
 629     wxMenuItem* FindItemByPosition(size_t position) const;
 630
 631     /**
 632         Returns the help string associated with a menu item.
 633
 634         @param id
 635             The menu item identifier.
 636
 637         @return The help string, or the empty string if there is no help string
 638                 or the item was not found.
 639
 640         @see SetHelpString(), Append()
 641     */
 642     wxString GetHelpString(int id) const;
 643
 644     /**
 645         Returns a menu item label.
 646
 647         @param id
 648             The menu item identifier.
 649
 650         @return The item label, or the empty string if the item was not found.
 651
 652         @see GetLabelText(), SetLabel()
 653     */
 654     wxString GetLabel(int id) const;
 655
 656     /**
 657         Returns a menu item label, without any of the original mnemonics and
 658         accelerators.
 659
 660         @param id
 661             The menu item identifier.
 662
 663         @return The item label, or the empty string if the item was not found.
 664
 665         @see GetLabel(), SetLabel()
 666     */
 667     wxString GetLabelText(int id) const;
 668
 669     /**
 670         Returns the number of items in the menu.
 671     */
 672     size_t GetMenuItemCount() const;
 673
 674     /**
 675         Returns the list of items in the menu. wxMenuItemList is a pseudo-template
 676         list class containing wxMenuItem pointers, see wxList.
 677     */
 678     wxMenuItemList GetMenuItems() const;
 679
 680     /**
 681         Returns the title of the menu.
 682
 683         @remarks This is relevant only to popup menus, use
 684                  wxMenuBar::GetMenuLabel for the menus in the menubar.
 685
 686         @see SetTitle()
 687     */
 688     wxString GetTitle() const;
 689
 690     /**
 691         Inserts the given @a item before the position @e pos. Inserting the item
 692         at position GetMenuItemCount() is the same
 693         as appending it.
 694
 695         @see Append(), Prepend()
 696     */
 697     wxMenuItem* Insert(size_t pos, wxMenuItem* item);
 698
 699     /**
 700         Inserts the given @a item before the position @e pos. Inserting the item
 701         at position GetMenuItemCount() is the same
 702         as appending it.
 703
 704         @see Append(), Prepend()
 705     */
 706     wxMenuItem* Insert(size_t pos, int id,
 707                        const wxString& item = "",
 708                        const wxString& helpString = "",
 709                        wxItemKind kind = wxITEM_NORMAL);
 710
 711     /**
 712         Inserts a checkable item at the given position.
 713
 714         @see Insert(), AppendCheckItem()
 715     */
 716     wxMenuItem* InsertCheckItem(size_t pos, int id,
 717                                 const wxString& item,
 718                                 const wxString& helpString = "");
 719
 720     /**
 721         Inserts a radio item at the given position.
 722
 723         @see Insert(), AppendRadioItem()
 724     */
 725     wxMenuItem* InsertRadioItem(size_t pos, int id,
 726                                 const wxString& item,
 727                                 const wxString& helpString = "");
 728
 729     /**
 730         Inserts a separator at the given position.
 731
 732         @see Insert(), AppendSeparator()
 733     */
 734     wxMenuItem* InsertSeparator(size_t pos);
 735
 736     /**
 737         Determines whether a menu item is checked.
 738
 739         @param id
 740             The menu item identifier.
 741
 742         @return @true if the menu item is checked, @false otherwise.
 743
 744         @see Check()
 745     */
 746     bool IsChecked(int id) const;
 747
 748     /**
 749         Determines whether a menu item is enabled.
 750
 751         @param id
 752             The menu item identifier.
 753
 754         @return @true if the menu item is enabled, @false otherwise.
 755
 756         @see Enable()
 757     */
 758     bool IsEnabled(int id) const;
 759
 760     /**
 761         Inserts the given @a item at position 0, i.e. before all the other
 762         existing items.
 763
 764         @see Append(), Insert()
 765     */
 766     wxMenuItem* Prepend(wxMenuItem* item);
 767
 768     /**
 769         Inserts the given @a item at position 0, i.e. before all the other
 770         existing items.
 771
 772         @see Append(), Insert()
 773     */
 774     wxMenuItem* Prepend(int id, const wxString& item = "",
 775                         const wxString& helpString = "",
 776                         wxItemKind kind = wxITEM_NORMAL);
 777
 778     /**
 779         Inserts a checkable item at position 0.
 780
 781         @see Prepend(), AppendCheckItem()
 782     */
 783     wxMenuItem* PrependCheckItem(int id, const wxString& item,
 784                                  const wxString& helpString = "");
 785
 786     /**
 787         Inserts a radio item at position 0.
 788
 789         @see Prepend(), AppendRadioItem()
 790     */
 791     wxMenuItem* PrependRadioItem(int id, const wxString& item,
 792                                  const wxString& helpString = "");
 793
 794     /**
 795         Inserts a separator at position 0.
 796
 797         @see Prepend(), AppendSeparator()
 798     */
 799     wxMenuItem* PrependSeparator();
 800
 801     /**
 802         Removes the menu item from the menu but doesn't delete the associated C++
 803         object. This allows you to reuse the same item later by adding it back to the menu
 804         (especially useful with submenus).
 805
 806         @param id
 807             The identifier of the menu item to remove.
 808
 809         @return A pointer to the item which was detached from the menu.
 810     */
 811     wxMenuItem* Remove(int id);
 812
 813     /**
 814         Removes the menu item from the menu but doesn't delete the associated C++
 815         object. This allows you to reuse the same item later by adding it back to the menu
 816         (especially useful with submenus).
 817
 818         @param item
 819             The menu item to remove.
 820
 821         @return A pointer to the item which was detached from the menu.
 822     */
 823     wxMenuItem* Remove(wxMenuItem* item);
 824
 825     /**
 826         Sets an item's help string.
 827
 828         @param id
 829             The menu item identifier.
 830         @param helpString
 831             The help string to set.
 832
 833         @see GetHelpString()
 834     */
 835     void SetHelpString(int id, const wxString& helpString);
 836
 837     /**
 838         Sets the label of a menu item.
 839
 840         @param id
 841             The menu item identifier.
 842         @param label
 843             The menu item label to set.
 844
 845         @see Append(), GetLabel()
 846     */
 847     void SetLabel(int id, const wxString& label);
 848
 849     /**
 850         Sets the title of the menu.
 851
 852         @param title
 853             The title to set.
 854
 855         @remarks This is relevant only to popup menus, use
 856                  wxMenuBar::SetLabelTop for the menus in the menubar.
 857
 858         @see GetTitle()
 859     */
 860     void SetTitle(const wxString& title);
 861
 862     /**
 863         Sends events to @a source (or owning window if @NULL) to update the
 864         menu UI. This is called just before the menu is popped up with
 865         wxWindow::PopupMenu, but
 866         the application may call it at other times if required.
 867     */
 868     void UpdateUI(wxEvtHandler* source = NULL) const;
 869 };
 870