interface/wx/menu.h

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