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