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 licence
   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, must be non-empty.
  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         Enables you to set the global menubar on Mac, that is, the menubar displayed
 379         when the app is running without any frames open.
 380
 381         @param menubar
 382             The menubar to set.
 383
 384         @remarks Only exists on Mac, other platforms do not have this method.
 385     */
 386     static void MacSetCommonMenuBar(wxMenuBar* menubar);
 387
 388     /**
 389         Enables you to get the global menubar on Mac, that is, the menubar displayed
 390         when the app is running without any frames open.
 391
 392         @return The global menubar.
 393
 394         @remarks Only exists on Mac, other platforms do not have this method.
 395     */
 396     static wxMenuBar* MacGetCommonMenuBar();
 397
 398     wxFrame *GetFrame() const;
 399     bool IsAttached() const;
 400     virtual void Attach(wxFrame *frame);
 401     virtual void Detach();
 402
 403 };
 404
 405
 406
 407 /**
 408     @class wxMenu
 409
 410     A menu is a popup (or pull down) list of items, one of which may be
 411     selected before the menu goes away (clicking elsewhere dismisses the
 412     menu). Menus may be used to construct either menu bars or popup menus.
 413
 414     A menu item has an integer ID associated with it which can be used to
 415     identify the selection, or to change the menu item in some way. A menu item
 416     with a special identifier @e wxID_SEPARATOR is a separator item and doesn't
 417     have an associated command but just makes a separator line appear in the
 418     menu.
 419
 420     @note
 421     Please note that @e wxID_ABOUT and @e wxID_EXIT are predefined by wxWidgets
 422     and have a special meaning since entries using these IDs will be taken out
 423     of the normal menus under MacOS X and will be inserted into the system menu
 424     (following the appropriate MacOS X interface guideline).
 425
 426     Menu items may be either @e normal items, @e check items or @e radio items.
 427     Normal items don't have any special properties while the check items have a
 428     boolean flag associated to them and they show a checkmark in the menu when
 429     the flag is set.
 430     wxWidgets automatically toggles the flag value when the item is clicked and its
 431     value may be retrieved using either wxMenu::IsChecked method of wxMenu or
 432     wxMenuBar itself or by using wxEvent::IsChecked when you get the menu
 433     notification for the item in question.
 434
 435     The radio items are similar to the check items except that all the other items
 436     in the same radio group are unchecked when a radio item is checked. The radio
 437     group is formed by a contiguous range of radio items, i.e. it starts at the
 438     first item of this kind and ends with the first item of a different kind (or
 439     the end of the menu). Notice that because the radio groups are defined in terms
 440     of the item positions inserting or removing the items in the menu containing
 441     the radio items risks to not work correctly.
 442
 443
 444     @section menu_allocation Allocation strategy
 445
 446     All menus must be created on the @b heap because all menus attached to a
 447     menubar or to another menu will be deleted by their parent when it is
 448     deleted. The only exception to this rule are the popup menus (i.e. menus
 449     used with wxWindow::PopupMenu()) as wxWidgets does not destroy them to
 450     allow reusing the same menu more than once. But the exception applies only
 451     to the menus themselves and not to any submenus of popup menus which are
 452     still destroyed by wxWidgets as usual and so must be heap-allocated.
 453
 454     As the frame menubar is deleted by the frame itself, it means that normally
 455     all menus used are deleted automatically.
 456
 457
 458     @section menu_eventhandling Event handling
 459
 460     If the menu is part of a menubar, then wxMenuBar event processing is used.
 461
 462     With a popup menu (see wxWindow::PopupMenu), there is a variety of ways to
 463     handle a menu selection event (@c wxEVT_COMMAND_MENU_SELECTED):
 464     - Provide @c EVT_MENU handlers in the window which pops up the menu, or in an
 465       ancestor of that window (the simplest method);
 466     - Derive a new class from wxMenu and define event table entries using the @c EVT_MENU macro;
 467     - Set a new event handler for wxMenu, through wxEvtHandler::SetNextHandler,
 468       specifying an object whose class has @c EVT_MENU entries;
 469
 470     Note that instead of static @c EVT_MENU macros you can also use dynamic
 471     connection; see @ref overview_events_bind.
 472
 473     @library{wxcore}
 474     @category{menus}
 475
 476     @see wxMenuBar, wxWindow::PopupMenu, @ref overview_events,
 477          @ref wxFileHistory "wxFileHistory (most recently used files menu)"
 478 */
 479 class wxMenu : public wxEvtHandler
 480 {
 481 public:
 482
 483     /**
 484         Constructs a wxMenu object.
 485     */
 486     wxMenu();
 487
 488     /**
 489         Constructs a wxMenu object.
 490
 491         @param style
 492             If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only).
 493     */
 494     wxMenu(long style);
 495
 496     /**
 497         Constructs a wxMenu object with a title.
 498
 499         @param title
 500             Title at the top of the menu (not always supported).
 501         @param style
 502             If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only).
 503     */
 504     wxMenu(const wxString& title, long style = 0);
 505
 506     /**
 507         Destructor, destroying the menu.
 508
 509         @note
 510             Under Motif, a popup menu must have a valid parent (the window
 511             it was last popped up on) when being destroyed. Therefore, make sure
 512             you delete or re-use the popup menu @e before destroying the parent
 513             window. Re-use in this context means popping up the menu on a different
 514             window from last time, which causes an implicit destruction and
 515             recreation of internal data structures.
 516     */
 517     virtual ~wxMenu();
 518
 519     /**
 520         Adds a menu item.
 521
 522         @param id
 523             The menu command identifier.
 524         @param item
 525             The string to appear on the menu item.
 526             See wxMenuItem::SetItemLabel() for more details.
 527         @param helpString
 528             An optional help string associated with the item.
 529             By default, the handler for the @c wxEVT_MENU_HIGHLIGHT event displays
 530             this string in the status line.
 531         @param kind
 532             May be @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, @c wxITEM_CHECK or @c wxITEM_RADIO.
 533
 534         Example:
 535         @code
 536         m_pFileMenu->Append(ID_NEW_FILE, "&New file\tCTRL+N", "Creates a new XYZ document");
 537         @endcode
 538         or even better for stock menu items (see wxMenuItem::wxMenuItem):
 539         @code
 540         m_pFileMenu->Append(wxID_NEW, "", "Creates a new XYZ document");
 541         @endcode
 542
 543         @remarks
 544         This command can be used after the menu has been shown, as well as on
 545         initial creation of a menu or menubar.
 546
 547         @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
 548              AppendSubMenu(), Insert(), SetLabel(), GetHelpString(),
 549              SetHelpString(), wxMenuItem
 550     */
 551     wxMenuItem* Append(int id, const wxString& item = wxEmptyString,
 552                        const wxString& helpString = wxEmptyString,
 553                        wxItemKind kind = wxITEM_NORMAL);
 554
 555     /**
 556         Adds a submenu.
 557
 558         @deprecated This function is deprecated, use AppendSubMenu() instead.
 559
 560         @param id
 561             The menu command identifier.
 562         @param item
 563             The string to appear on the menu item.
 564         @param subMenu
 565             Pull-right submenu.
 566         @param helpString
 567             An optional help string associated with the item.
 568             By default, the handler for the @c wxEVT_MENU_HIGHLIGHT event displays
 569             this string in the status line.
 570
 571         @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
 572              AppendSubMenu(), Insert(), SetLabel(), GetHelpString(),
 573              SetHelpString(), wxMenuItem
 574     */
 575     wxMenuItem* Append(int id, const wxString& item, wxMenu* subMenu,
 576                        const wxString& helpString = wxEmptyString);
 577
 578     /**
 579         Adds a menu item object.
 580
 581         This is the most generic variant of Append() method because it may be
 582         used for both items (including separators) and submenus and because
 583         you can also specify various extra properties of a menu item this way,
 584         such as bitmaps and fonts.
 585
 586         @param menuItem
 587             A menuitem object. It will be owned by the wxMenu object after this
 588             function is called, so do not delete it yourself.
 589
 590         @remarks
 591             See the remarks for the other Append() overloads.
 592
 593         @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
 594              AppendSubMenu(), Insert(), SetLabel(), GetHelpString(),
 595              SetHelpString(), wxMenuItem
 596     */
 597     wxMenuItem* Append(wxMenuItem* menuItem);
 598
 599     /**
 600         Adds a checkable item to the end of the menu.
 601
 602         @see Append(), InsertCheckItem()
 603     */
 604     wxMenuItem* AppendCheckItem(int id, const wxString& item,
 605                                 const wxString& help = wxEmptyString);
 606
 607     /**
 608         Adds a radio item to the end of the menu.
 609         All consequent radio items form a group and when an item in the group is
 610         checked, all the others are automatically unchecked.
 611
 612         @note Radio items are not supported under wxMotif.
 613
 614         @see Append(), InsertRadioItem()
 615     */
 616     wxMenuItem* AppendRadioItem(int id, const wxString& item,
 617                                 const wxString& help = wxEmptyString);
 618
 619     /**
 620         Adds a separator to the end of the menu.
 621
 622         @see Append(), InsertSeparator()
 623     */
 624     wxMenuItem* AppendSeparator();
 625
 626     /**
 627         Adds the given @a submenu to this menu. @a text is the text shown in the
 628         menu for it and @a help is the help string shown in the status bar when the
 629         submenu item is selected.
 630     */
 631     wxMenuItem* AppendSubMenu(wxMenu* submenu, const wxString& text,
 632                               const wxString& help = wxEmptyString);
 633
 634     /**
 635         Inserts a break in a menu, causing the next appended item to appear in
 636         a new column.
 637     */
 638     virtual void Break();
 639
 640     /**
 641         Checks or unchecks the menu item.
 642
 643         @param id
 644             The menu item identifier.
 645         @param check
 646             If @true, the item will be checked, otherwise it will be unchecked.
 647
 648         @see IsChecked()
 649     */
 650     void Check(int id, bool check);
 651
 652     /**
 653         Deletes the menu item from the menu. If the item is a submenu, it will
 654         @b not be deleted. Use Destroy() if you want to delete a submenu.
 655
 656         @param id
 657             Id of the menu item to be deleted.
 658
 659         @see FindItem(), Destroy(), Remove()
 660     */
 661     bool Delete(int id);
 662
 663     /**
 664         Deletes the menu item from the menu. If the item is a submenu, it will
 665         @b not be deleted. Use Destroy() if you want to delete a submenu.
 666
 667         @param item
 668             Menu item to be deleted.
 669
 670         @see FindItem(), Destroy(), Remove()
 671     */
 672     bool Delete(wxMenuItem* item);
 673
 674     /**
 675         Deletes the menu item from the menu. If the item is a submenu, it will
 676         be deleted. Use Remove() if you want to keep the submenu (for example,
 677         to reuse it later).
 678
 679         @param id
 680             Id of the menu item to be deleted.
 681
 682         @see FindItem(), Delete(), Remove()
 683     */
 684     bool Destroy(int id);
 685
 686     /**
 687         Deletes the menu item from the menu. If the item is a submenu, it will
 688         be deleted. Use Remove() if you want to keep the submenu (for example,
 689         to reuse it later).
 690
 691         @param item
 692             Menu item to be deleted.
 693
 694         @see FindItem(), Delete(), Remove()
 695     */
 696     bool Destroy(wxMenuItem* item);
 697
 698     /**
 699         Enables or disables (greys out) a menu item.
 700
 701         @param id
 702             The menu item identifier.
 703         @param enable
 704             @true to enable the menu item, @false to disable it.
 705
 706         @see IsEnabled()
 707     */
 708     void Enable(int id, bool enable);
 709
 710     /**
 711       Finds the menu item object associated with the given menu item identifier
 712       and, optionally, the position of the item in the menu.
 713
 714       Unlike FindItem(), this function doesn't recurse but only looks at the
 715       direct children of this menu.
 716
 717       @param id
 718           The identifier of the menu item to find.
 719       @param pos
 720           If the pointer is not @NULL, it is filled with the item's position if
 721           it was found or @c (size_t)wxNOT_FOUND otherwise.
 722       @return
 723         Menu item object or @NULL if not found.
 724      */
 725     wxMenuItem *FindChildItem(int id, size_t *pos = NULL) const;
 726
 727     /**
 728         Finds the menu id for a menu item string.
 729
 730         @param itemString
 731             Menu item string to find.
 732
 733         @return Menu item identifier, or wxNOT_FOUND if none is found.
 734
 735         @remarks Any special menu codes are stripped out of source and target
 736                  strings before matching.
 737     */
 738     virtual int FindItem(const wxString& itemString) const;
 739
 740     /**
 741         Finds the menu item object associated with the given menu item identifier and,
 742         optionally, the (sub)menu it belongs to.
 743
 744         @param id
 745             Menu item identifier.
 746         @param menu
 747             If the pointer is not @NULL, it will be filled with the item's
 748             parent menu (if the item was found)
 749
 750         @return Menu item object or NULL if none is found.
 751     */
 752     wxMenuItem* FindItem(int id, wxMenu** menu = NULL) const;
 753
 754     /**
 755         Returns the wxMenuItem given a position in the menu.
 756     */
 757     wxMenuItem* FindItemByPosition(size_t position) const;
 758
 759     /**
 760         Returns the help string associated with a menu item.
 761
 762         @param id
 763             The menu item identifier.
 764
 765         @return The help string, or the empty string if there is no help string
 766                 or the item was not found.
 767
 768         @see SetHelpString(), Append()
 769     */
 770     virtual wxString GetHelpString(int id) const;
 771
 772     /**
 773         Returns a menu item label.
 774
 775         @param id
 776             The menu item identifier.
 777
 778         @return The item label, or the empty string if the item was not found.
 779
 780         @see GetLabelText(), SetLabel()
 781     */
 782     wxString GetLabel(int id) const;
 783
 784     /**
 785         Returns a menu item label, without any of the original mnemonics and
 786         accelerators.
 787
 788         @param id
 789             The menu item identifier.
 790
 791         @return The item label, or the empty string if the item was not found.
 792
 793         @see GetLabel(), SetLabel()
 794     */
 795     wxString GetLabelText(int id) const;
 796
 797     /**
 798         Returns the number of items in the menu.
 799     */
 800     size_t GetMenuItemCount() const;
 801
 802     //@{
 803     /**
 804         Returns the list of items in the menu.
 805
 806         wxMenuItemList is a pseudo-template list class containing wxMenuItem
 807         pointers, see wxList.
 808     */
 809     wxMenuItemList& GetMenuItems() const;
 810     const wxMenuItemList& GetMenuItems() const;
 811     //@}
 812
 813     /**
 814         Returns the title of the menu.
 815
 816         @see SetTitle()
 817     */
 818     const wxString& GetTitle() const;
 819
 820     /**
 821         Inserts the given @a item before the position @a pos.
 822
 823         Inserting the item at position GetMenuItemCount() is the same
 824         as appending it.
 825
 826         @see Append(), Prepend()
 827     */
 828     wxMenuItem* Insert(size_t pos, wxMenuItem* menuItem);
 829
 830     /**
 831         Inserts the given @a item before the position @a pos.
 832
 833         Inserting the item at position GetMenuItemCount() is the same
 834         as appending it.
 835
 836         @see Append(), Prepend()
 837     */
 838     wxMenuItem* Insert(size_t pos, int id,
 839                        const wxString& item = wxEmptyString,
 840                        const wxString& helpString = wxEmptyString,
 841                        wxItemKind kind = wxITEM_NORMAL);
 842
 843     /**
 844         Inserts a checkable item at the given position.
 845
 846         @see Insert(), AppendCheckItem()
 847     */
 848     wxMenuItem* InsertCheckItem(size_t pos, int id, const wxString& item,
 849                                 const wxString& helpString = wxEmptyString);
 850
 851     /**
 852         Inserts a radio item at the given position.
 853
 854         @see Insert(), AppendRadioItem()
 855     */
 856     wxMenuItem* InsertRadioItem(size_t pos, int id, const wxString& item,
 857                                 const wxString& helpString = wxEmptyString);
 858
 859     /**
 860         Inserts a separator at the given position.
 861
 862         @see Insert(), AppendSeparator()
 863     */
 864     wxMenuItem* InsertSeparator(size_t pos);
 865
 866     /**
 867         Determines whether a menu item is checked.
 868
 869         @param id
 870             The menu item identifier.
 871
 872         @return @true if the menu item is checked, @false otherwise.
 873
 874         @see Check()
 875     */
 876     bool IsChecked(int id) const;
 877
 878     /**
 879         Determines whether a menu item is enabled.
 880
 881         @param id
 882             The menu item identifier.
 883
 884         @return @true if the menu item is enabled, @false otherwise.
 885
 886         @see Enable()
 887     */
 888     bool IsEnabled(int id) const;
 889
 890     /**
 891         Inserts the given @a item at position 0, i.e. before all the other
 892         existing items.
 893
 894         @see Append(), Insert()
 895     */
 896     wxMenuItem* Prepend(wxMenuItem* item);
 897
 898     /**
 899         Inserts the given @a item at position 0, i.e. before all the other
 900         existing items.
 901
 902         @see Append(), Insert()
 903     */
 904     wxMenuItem* Prepend(int id, const wxString& item = wxEmptyString,
 905                         const wxString& helpString = wxEmptyString,
 906                         wxItemKind kind = wxITEM_NORMAL);
 907
 908     /**
 909         Inserts a checkable item at position 0.
 910
 911         @see Prepend(), AppendCheckItem()
 912     */
 913     wxMenuItem* PrependCheckItem(int id, const wxString& item,
 914                                  const wxString& helpString = wxEmptyString);
 915
 916     /**
 917         Inserts a radio item at position 0.
 918
 919         @see Prepend(), AppendRadioItem()
 920     */
 921     wxMenuItem* PrependRadioItem(int id, const wxString& item,
 922                                  const wxString& helpString = wxEmptyString);
 923
 924     /**
 925         Inserts a separator at position 0.
 926
 927         @see Prepend(), AppendSeparator()
 928     */
 929     wxMenuItem* PrependSeparator();
 930
 931     /**
 932         Removes the menu item from the menu but doesn't delete the associated C++
 933         object. This allows you to reuse the same item later by adding it back to
 934         the menu (especially useful with submenus).
 935
 936         @param id
 937             The identifier of the menu item to remove.
 938
 939         @return A pointer to the item which was detached from the menu.
 940     */
 941     wxMenuItem* Remove(int id);
 942
 943     /**
 944         Removes the menu item from the menu but doesn't delete the associated C++
 945         object. This allows you to reuse the same item later by adding it back to
 946         the menu (especially useful with submenus).
 947
 948         @param item
 949             The menu item to remove.
 950
 951         @return A pointer to the item which was detached from the menu.
 952     */
 953     wxMenuItem* Remove(wxMenuItem* item);
 954
 955     /**
 956         Sets an item's help string.
 957
 958         @param id
 959             The menu item identifier.
 960         @param helpString
 961             The help string to set.
 962
 963         @see GetHelpString()
 964     */
 965     virtual void SetHelpString(int id, const wxString& helpString);
 966
 967     /**
 968         Sets the label of a menu item.
 969
 970         @param id
 971             The menu item identifier.
 972         @param label
 973             The menu item label to set.
 974
 975         @see Append(), GetLabel()
 976     */
 977     void SetLabel(int id, const wxString& label);
 978
 979     /**
 980         Sets the title of the menu.
 981
 982         @param title
 983             The title to set.
 984
 985         @remarks Notice that you can only call this method directly for the
 986             popup menus, to change the title of a menu that is part of a menu
 987             bar you need to use wxMenuBar::SetLabelTop().
 988
 989         @see GetTitle()
 990     */
 991     virtual void SetTitle(const wxString& title);
 992
 993     /**
 994         Sends events to @a source (or owning window if @NULL) to update the
 995         menu UI.
 996
 997         This is called just before the menu is popped up with wxWindow::PopupMenu,
 998         but the application may call it at other times if required.
 999     */
1000     void UpdateUI(wxEvtHandler* source = NULL);
1001
1002
1003     void SetInvokingWindow(wxWindow *win);
1004     wxWindow *GetInvokingWindow() const;
1005     wxWindow *GetWindow() const;
1006     long GetStyle() const;
1007     void SetParent(wxMenu *parent);
1008     wxMenu *GetParent() const;
1009
1010     virtual void Attach(wxMenuBar *menubar);
1011     virtual void Detach();
1012     bool IsAttached() const;
1013
1014 };
1015