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