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