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