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