interface/menu.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        menu.h
   3 // Purpose:     documentation for wxMenuBar class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxMenuBar
  11     @wxheader{menu.h}
  12
  13     A menu bar is a series of menus accessible from the top of a frame.
  14
  15     @library{wxcore}
  16     @category{menus}
  17
  18     @seealso
  19     wxMenu, @ref overview_eventhandlingoverview
  20 */
  21 class wxMenuBar : public wxWindow
  22 {
  23 public:
  24     //@{
  25     /**
  26         Construct a menu bar from arrays of menus and titles.
  27
  28         @param n
  29             The number of menus.
  30         @param menus
  31             An array of menus. Do not use this array again - it now belongs to the
  32             menu bar.
  33         @param titles
  34             An array of title strings. Deallocate this array after creating the menu
  35         bar.
  36         @param style
  37             If wxMB_DOCKABLE the menu bar can be detached (wxGTK only).
  38     */
  39     wxMenuBar(long style = 0);
  40     wxMenuBar(size_t n, wxMenu* menus[], const wxString titles[],
  41               long style = 0);
  42     //@}
  43
  44     /**
  45         Destructor, destroying the menu bar and removing it from the parent frame (if
  46         any).
  47     */
  48     ~wxMenuBar();
  49
  50     /**
  51         Adds the item to the end of the menu bar.
  52
  53         @param menu
  54             The menu to add. Do not deallocate this menu after calling Append.
  55         @param title
  56             The title of the menu.
  57
  58         @returns @true on success, @false if an error occurred.
  59
  60         @see Insert()
  61     */
  62     bool Append(wxMenu* menu, const wxString& title);
  63
  64     /**
  65         Checks or unchecks a menu item.
  66
  67         @param id
  68             The menu item identifier.
  69         @param check
  70             If @true, checks the menu item, otherwise the item is unchecked.
  71
  72         @remarks Only use this when the menu bar has been associated with a
  73                  frame; otherwise, use the wxMenu equivalent call.
  74     */
  75     void Check(int id, const bool check);
  76
  77     /**
  78         Enables or disables (greys out) a menu item.
  79
  80         @param id
  81             The menu item identifier.
  82         @param enable
  83             @true to enable the item, @false to disable it.
  84
  85         @remarks Only use this when the menu bar has been associated with a
  86                  frame; otherwise, use the wxMenu equivalent call.
  87     */
  88     void Enable(int id, const bool enable);
  89
  90     /**
  91         Enables or disables a whole menu.
  92
  93         @param pos
  94             The position of the menu, starting from zero.
  95         @param enable
  96             @true to enable the menu, @false to disable it.
  97
  98         @remarks Only use this when the menu bar has been associated with a frame.
  99     */
 100     void EnableTop(int pos, const bool enable);
 101
 102     /**
 103         Finds the menu item object associated with the given menu item identifier.
 104
 105         @param id
 106             Menu item identifier.
 107         @param menu
 108             If not @NULL, menu will get set to the associated menu.
 109
 110         @returns The found menu item object, or @NULL if one was not found.
 111     */
 112     wxMenuItem* FindItem(int id, wxMenu menu = NULL) const;
 113
 114     /**
 115         Returns the index of the menu with the given @a title or @c wxNOT_FOUND if no
 116         such menu exists in this menubar. The @a title parameter may specify either
 117         the menu title (with accelerator characters, i.e. @c "File") or just the
 118         menu label (@c "File") indifferently.
 119     */
 120     int FindMenu(const wxString& title) const;
 121
 122     /**
 123         Finds the menu item id for a menu name/menu item string pair.
 124
 125         @param menuString
 126             Menu title to find.
 127         @param itemString
 128             Item to find.
 129
 130         @returns The menu item identifier, or wxNOT_FOUND if none was found.
 131
 132         @remarks Any special menu codes are stripped out of source and target
 133                  strings before matching.
 134     */
 135     int FindMenuItem(const wxString& menuString,
 136                      const wxString& itemString) const;
 137
 138     /**
 139         Gets the help string associated with the menu item identifier.
 140
 141         @param id
 142             The menu item identifier.
 143
 144         @returns The help string, or the empty string if there was no help string
 145                  or the menu item was not found.
 146
 147         @see SetHelpString()
 148     */
 149     wxString GetHelpString(int id) const;
 150
 151     /**
 152         Gets the label associated with a menu item.
 153
 154         @param id
 155             The menu item identifier.
 156
 157         @returns The menu item label, or the empty string if the item was not
 158                  found.
 159
 160         @remarks Use only after the menubar has been associated with a frame.
 161     */
 162     wxString GetLabel(int id) const;
 163
 164     /**
 165         Returns the label of a top-level menu. Note that the returned string does not
 166         include the accelerator characters which could have been specified in the menu
 167         title string during its construction.
 168
 169         @param pos
 170             Position of the menu on the menu bar, starting from zero.
 171
 172         @returns The menu label, or the empty string if the menu was not found.
 173
 174         @remarks Use only after the menubar has been associated with a frame.
 175
 176         @see SetLabelTop()
 177     */
 178     wxString GetLabelTop(int pos) const;
 179
 180     /**
 181         Returns the menu at @a menuIndex (zero-based).
 182     */
 183     wxMenu* GetMenu(int menuIndex) const;
 184
 185     /**
 186         Returns the number of menus in this menubar.
 187     */
 188     size_t GetMenuCount() const;
 189
 190     /**
 191         Returns the label of a top-level menu. Note that the returned string
 192         includes the accelerator characters that have been specified in the menu
 193         title string during its construction.
 194
 195         @param pos
 196             Position of the menu on the menu bar, starting from zero.
 197
 198         @returns The menu label, or the empty string if the menu was not found.
 199
 200         @remarks Use only after the menubar has been associated with a frame.
 201
 202         @see GetMenuLabelText(), SetMenuLabel()
 203     */
 204     wxString GetMenuLabel(int pos) const;
 205
 206     /**
 207         Returns the label of a top-level menu. Note that the returned string does not
 208         include any accelerator characters that may have been specified in the menu
 209         title string during its construction.
 210
 211         @param pos
 212             Position of the menu on the menu bar, starting from zero.
 213
 214         @returns The menu label, or the empty string if the menu was not found.
 215
 216         @remarks Use only after the menubar has been associated with a frame.
 217
 218         @see GetMenuLabel(), SetMenuLabel()
 219     */
 220     wxString GetMenuLabelText(int pos) const;
 221
 222     /**
 223         Inserts the menu at the given position into the menu bar. Inserting menu at
 224         position 0 will insert it in the very beginning of it, inserting at position
 225         GetMenuCount() is the same as calling
 226         Append().
 227
 228         @param pos
 229             The position of the new menu in the menu bar
 230         @param menu
 231             The menu to add. wxMenuBar owns the menu and will free it.
 232         @param title
 233             The title of the menu.
 234
 235         @returns @true on success, @false if an error occurred.
 236
 237         @see Append()
 238     */
 239     bool Insert(size_t pos, wxMenu* menu, const wxString& title);
 240
 241     /**
 242         Determines whether an item is checked.
 243
 244         @param id
 245             The menu item identifier.
 246
 247         @returns @true if the item was found and is checked, @false otherwise.
 248     */
 249     bool IsChecked(int id) const;
 250
 251     /**
 252         Determines whether an item is enabled.
 253
 254         @param id
 255             The menu item identifier.
 256
 257         @returns @true if the item was found and is enabled, @false otherwise.
 258     */
 259     bool IsEnabled(int id) const;
 260
 261     /**
 262         Redraw the menu bar
 263     */
 264     void Refresh();
 265
 266     /**
 267         Removes the menu from the menu bar and returns the menu object - the caller is
 268         responsible for deleting it. This function may be used together with
 269         Insert() to change the menubar
 270         dynamically.
 271
 272         @see Replace()
 273     */
 274     wxMenu* Remove(size_t pos);
 275
 276     /**
 277         Replaces the menu at the given position with another one.
 278
 279         @param pos
 280             The position of the new menu in the menu bar
 281         @param menu
 282             The menu to add.
 283         @param title
 284             The title of the menu.
 285
 286         @returns The menu which was previously at position pos. The caller is
 287                  responsible for deleting it.
 288
 289         @see Insert(), Remove()
 290     */
 291     wxMenu* Replace(size_t pos, wxMenu* menu, const wxString& title);
 292
 293     /**
 294         Sets the help string associated with a menu item.
 295
 296         @param id
 297             Menu item identifier.
 298         @param helpString
 299             Help string to associate with the menu item.
 300
 301         @see GetHelpString()
 302     */
 303     void SetHelpString(int id, const wxString& helpString);
 304
 305     /**
 306         Sets the label of a menu item.
 307
 308         @param id
 309             Menu item identifier.
 310         @param label
 311             Menu item label.
 312
 313         @remarks Use only after the menubar has been associated with a frame.
 314
 315         @see GetLabel()
 316     */
 317     void SetLabel(int id, const wxString& label);
 318
 319     /**
 320         Sets the label of a top-level menu.
 321
 322         @param pos
 323             The position of a menu on the menu bar, starting from zero.
 324         @param label
 325             The menu label.
 326
 327         @remarks Use only after the menubar has been associated with a frame.
 328
 329         @see GetLabelTop()
 330     */
 331     void SetLabelTop(int pos, const wxString& label);
 332
 333     /**
 334         Sets the label of a top-level menu.
 335
 336         @param pos
 337             The position of a menu on the menu bar, starting from zero.
 338         @param label
 339             The menu label.
 340
 341         @remarks Use only after the menubar has been associated with a frame.
 342     */
 343     void SetMenuLabel(int pos, const wxString& label);
 344 };
 345
 346
 347 /**
 348     @class wxMenu
 349     @wxheader{menu.h}
 350
 351     A menu is a popup (or pull down) list of items, one of which may be
 352     selected before the menu goes away (clicking elsewhere dismisses the
 353     menu). Menus may be used to construct either menu bars or popup menus.
 354
 355     A menu item has an integer ID associated with it which can be used to
 356     identify the selection, or to change the menu item in some way. A menu item
 357     with a special identifier -1 is a separator item and doesn't have an
 358     associated command but just makes a separator line appear in the menu.
 359
 360     @b NB: Please note that @e wxID_ABOUT and @e wxID_EXIT are
 361     predefined by wxWidgets and have a special meaning since entries
 362     using these IDs will be taken out of the normal menus under MacOS X
 363     and will be inserted into the system menu (following the appropriate
 364     MacOS X interface guideline). On PalmOS @e wxID_EXIT is disabled according
 365     to Palm OS Companion guidelines.
 366
 367     Menu items may be either normal items, check items or radio items. Normal items
 368     don't have any special properties while the check items have a boolean flag
 369     associated to them and they show a checkmark in the menu when the flag is set.
 370     wxWidgets automatically toggles the flag value when the item is clicked and its
 371     value may be retrieved using either wxMenu::IsChecked method
 372     of wxMenu or wxMenuBar itself or by using
 373     wxEvent::IsChecked when you get the menu
 374     notification for the item in question.
 375
 376     The radio items are similar to the check items except that all the other items
 377     in the same radio group are unchecked when a radio item is checked. The radio
 378     group is formed by a contiguous range of radio items, i.e. it starts at the
 379     first item of this kind and ends with the first item of a different kind (or
 380     the end of the menu). Notice that because the radio groups are defined in terms
 381     of the item positions inserting or removing the items in the menu containing
 382     the radio items risks to not work correctly. Finally note that radio items
 383     are not supported under Motif.
 384
 385     @library{wxcore}
 386     @category{menus}
 387
 388     @seealso
 389     wxMenuBar, wxWindow::PopupMenu, @ref overview_eventhandlingoverview, @ref
 390     overview_wxfilehistory "wxFileHistory (most recently used files menu)"
 391 */
 392 class wxMenu : public wxEvtHandler
 393 {
 394 public:
 395     //@{
 396     /**
 397         Constructs a wxMenu object.
 398
 399         @param style
 400             If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only).
 401     */
 402     wxMenu(const wxString& title = "", long style = 0);
 403     wxMenu(long style);
 404     //@}
 405
 406     /**
 407         Destructor, destroying the menu.
 408         Note: under Motif, a popup menu must have a valid parent (the window
 409         it was last popped up on) when being destroyed. Therefore, make sure
 410         you delete or re-use the popup menu @e before destroying the
 411         parent window. Re-use in this context means popping up the menu on
 412         a different window from last time, which causes an implicit destruction
 413         and recreation of internal data structures.
 414     */
 415     ~wxMenu();
 416
 417     //@{
 418     /**
 419         Adds a menu item object. This is the most generic variant of Append() method
 420         because it may be used for both items (including separators) and submenus and
 421         because you can also specify various extra properties of a menu item this way,
 422         such as bitmaps and fonts.
 423
 424         @param id
 425             The menu command identifier.
 426         @param item
 427             The string to appear on the menu item.
 428         @param menu
 429             Pull-right submenu.
 430         @param kind
 431             May be wxITEM_SEPARATOR, wxITEM_NORMAL,
 432             wxITEM_CHECK or wxITEM_RADIO
 433         @param helpString
 434             An optional help string associated with the item.
 435             By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays
 436             this string in the status line.
 437         @param menuItem
 438             A menuitem object. It will be owned by the wxMenu object after this function
 439             is called, so do not delete it yourself.
 440
 441         @remarks This command can be used after the menu has been shown, as well
 442                  as on initial creation of a menu or menubar.
 443
 444         @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
 445              AppendSubMenu(), Insert(), SetLabel(),
 446              GetHelpString(), SetHelpString(), wxMenuItem
 447     */
 448     wxMenuItem* Append(int id, const wxString& item = "",
 449                        const wxString& helpString = "",
 450                        wxItemKind kind = wxITEM_NORMAL);
 451     wxMenuItem* Append(int id, const wxString& item,
 452                        wxMenu* subMenu,
 453                        const wxString& helpString = "");
 454     wxMenuItem* Append(wxMenuItem* menuItem);
 455     //@}
 456
 457     /**
 458         Adds a checkable item to the end of the menu.
 459
 460         @see Append(), InsertCheckItem()
 461     */
 462     wxMenuItem* AppendCheckItem(int id, const wxString& item,
 463                                 const wxString& helpString = "");
 464
 465     /**
 466         Adds a radio item to the end of the menu. All consequent radio items form a
 467         group and when an item in the group is checked, all the others are
 468         automatically unchecked.
 469
 470         @see Append(), InsertRadioItem()
 471     */
 472     wxMenuItem* AppendRadioItem(int id, const wxString& item,
 473                                 const wxString& helpString = "");
 474
 475     /**
 476         Adds a separator to the end of the menu.
 477
 478         @see Append(), InsertSeparator()
 479     */
 480     wxMenuItem* AppendSeparator();
 481
 482     /**
 483         Adds the given @a submenu to this menu. @a text is the text shown in the
 484         menu for it and @a help is the help string shown in the status bar when the
 485         submenu item is selected.
 486     */
 487     wxMenuItem* AppendSubMenu(wxMenu* submenu, const wxString& text,
 488                               const wxString& help = wxEmptyString);
 489
 490     /**
 491         Inserts a break in a menu, causing the next appended item to appear in a new
 492         column.
 493     */
 494     void Break();
 495
 496     /**
 497         Checks or unchecks the menu item.
 498
 499         @param id
 500             The menu item identifier.
 501         @param check
 502             If @true, the item will be checked, otherwise it will be unchecked.
 503
 504         @see IsChecked()
 505     */
 506     void Check(int id, const bool check);
 507
 508     //@{
 509     /**
 510         Deletes the menu item from the menu. If the item is a submenu, it will
 511         @b not be deleted. Use Destroy() if you want to
 512         delete a submenu.
 513
 514         @param id
 515             Id of the menu item to be deleted.
 516         @param item
 517             Menu item to be deleted.
 518
 519         @see FindItem(), Destroy(), Remove()
 520     */
 521     void Delete(int id);
 522     void Delete(wxMenuItem* item);
 523     //@}
 524
 525     //@{
 526     /**
 527         Deletes the menu item from the menu. If the item is a submenu, it will
 528         be deleted. Use Remove() if you want to keep the submenu
 529         (for example, to reuse it later).
 530
 531         @param id
 532             Id of the menu item to be deleted.
 533         @param item
 534             Menu item to be deleted.
 535
 536         @see FindItem(), Deletes(), Remove()
 537     */
 538     void Destroy(int id);
 539     void Destroy(wxMenuItem* item);
 540     //@}
 541
 542     /**
 543         Enables or disables (greys out) a menu item.
 544
 545         @param id
 546             The menu item identifier.
 547         @param enable
 548             @true to enable the menu item, @false to disable it.
 549
 550         @see IsEnabled()
 551     */
 552     void Enable(int id, const bool enable);
 553
 554     //@{
 555     /**
 556         Finds the menu item object associated with the given menu item identifier and,
 557         optionally, the (sub)menu it belongs to.
 558
 559         @param itemString
 560             Menu item string to find.
 561         @param id
 562             Menu item identifier.
 563         @param menu
 564             If the pointer is not @NULL, it will be filled with the item's
 565             parent menu (if the item was found)
 566
 567         @returns First form: menu item identifier, or wxNOT_FOUND if none is
 568                  found.
 569
 570         @remarks Any special menu codes are stripped out of source and target
 571                  strings before matching.
 572     */
 573     int FindItem(const wxString& itemString) const;
 574     const wxMenuItem *  FindItem(int id, wxMenu** menu = NULL) const;
 575     //@}
 576
 577     /**
 578         Returns the wxMenuItem given a position in the menu.
 579     */
 580     wxMenuItem* FindItemByPosition(size_t position) const;
 581
 582     /**
 583         Returns the help string associated with a menu item.
 584
 585         @param id
 586             The menu item identifier.
 587
 588         @returns The help string, or the empty string if there is no help string
 589                  or the item was not found.
 590
 591         @see SetHelpString(), Append()
 592     */
 593     wxString GetHelpString(int id) const;
 594
 595     /**
 596         Returns a menu item label.
 597
 598         @param id
 599             The menu item identifier.
 600
 601         @returns The item label, or the empty string if the item was not found.
 602
 603         @see GetLabelText(), SetLabel()
 604     */
 605     wxString GetLabel(int id) const;
 606
 607     /**
 608         Returns a menu item label, without any of the original mnemonics and
 609         accelerators.
 610
 611         @param id
 612             The menu item identifier.
 613
 614         @returns The item label, or the empty string if the item was not found.
 615
 616         @see GetLabel(), SetLabel()
 617     */
 618     wxString GetLabelText(int id) const;
 619
 620     /**
 621         Returns the number of items in the menu.
 622     */
 623     size_t GetMenuItemCount() const;
 624
 625     /**
 626         Returns the list of items in the menu. wxMenuItemList is a pseudo-template
 627         list class containing wxMenuItem pointers, see wxList.
 628     */
 629     wxMenuItemList GetMenuItems() const;
 630
 631     /**
 632         Returns the title of the menu.
 633
 634         @remarks This is relevant only to popup menus, use
 635                  wxMenuBar::GetMenuLabel for the menus in the menubar.
 636
 637         @see SetTitle()
 638     */
 639     wxString GetTitle() const;
 640
 641     //@{
 642     /**
 643         Inserts the given @a item before the position @e pos. Inserting the item
 644         at position GetMenuItemCount() is the same
 645         as appending it.
 646
 647         @see Append(), Prepend()
 648     */
 649     wxMenuItem* Insert(size_t pos, wxMenuItem* item);
 650     wxMenuItem* Insert(size_t pos, int id,
 651                        const wxString& item = "",
 652                        const wxString& helpString = "",
 653                        wxItemKind kind = wxITEM_NORMAL);
 654     //@}
 655
 656     /**
 657         Inserts a checkable item at the given position.
 658
 659         @see Insert(), AppendCheckItem()
 660     */
 661     wxMenuItem* InsertCheckItem(size_t pos, int id,
 662                                 const wxString& item,
 663                                 const wxString& helpString = "");
 664
 665     /**
 666         Inserts a radio item at the given position.
 667
 668         @see Insert(), AppendRadioItem()
 669     */
 670     wxMenuItem* InsertRadioItem(size_t pos, int id,
 671                                 const wxString& item,
 672                                 const wxString& helpString = "");
 673
 674     /**
 675         Inserts a separator at the given position.
 676
 677         @see Insert(), AppendSeparator()
 678     */
 679     wxMenuItem* InsertSeparator(size_t pos);
 680
 681     /**
 682         Determines whether a menu item is checked.
 683
 684         @param id
 685             The menu item identifier.
 686
 687         @returns @true if the menu item is checked, @false otherwise.
 688
 689         @see Check()
 690     */
 691     bool IsChecked(int id) const;
 692
 693     /**
 694         Determines whether a menu item is enabled.
 695
 696         @param id
 697             The menu item identifier.
 698
 699         @returns @true if the menu item is enabled, @false otherwise.
 700
 701         @see Enable()
 702     */
 703     bool IsEnabled(int id) const;
 704
 705     //@{
 706     /**
 707         Inserts the given @a item at position 0, i.e. before all the other
 708         existing items.
 709
 710         @see Append(), Insert()
 711     */
 712     wxMenuItem* Prepend(wxMenuItem* item);
 713     wxMenuItem* Prepend(int id, const wxString& item = "",
 714                         const wxString& helpString = "",
 715                         wxItemKind kind = wxITEM_NORMAL);
 716     //@}
 717
 718     /**
 719         Inserts a checkable item at position 0.
 720
 721         @see Prepend(), AppendCheckItem()
 722     */
 723     wxMenuItem* PrependCheckItem(int id, const wxString& item,
 724                                  const wxString& helpString = "");
 725
 726     /**
 727         Inserts a radio item at position 0.
 728
 729         @see Prepend(), AppendRadioItem()
 730     */
 731     wxMenuItem* PrependRadioItem(int id, const wxString& item,
 732                                  const wxString& helpString = "");
 733
 734     /**
 735         Inserts a separator at position 0.
 736
 737         @see Prepend(), AppendSeparator()
 738     */
 739     wxMenuItem* PrependSeparator();
 740
 741     //@{
 742     /**
 743         Removes the menu item from the menu but doesn't delete the associated C++
 744         object. This allows to reuse the same item later by adding it back to the menu
 745         (especially useful with submenus).
 746
 747         @param id
 748             The identifier of the menu item to remove.
 749         @param item
 750             The menu item to remove.
 751
 752         @returns The item which was detached from the menu.
 753     */
 754     wxMenuItem* Remove(int id);
 755     wxMenuItem* Remove(wxMenuItem* item);
 756     //@}
 757
 758     /**
 759         Sets an item's help string.
 760
 761         @param id
 762             The menu item identifier.
 763         @param helpString
 764             The help string to set.
 765
 766         @see GetHelpString()
 767     */
 768     void SetHelpString(int id, const wxString& helpString);
 769
 770     /**
 771         Sets the label of a menu item.
 772
 773         @param id
 774             The menu item identifier.
 775         @param label
 776             The menu item label to set.
 777
 778         @see Append(), GetLabel()
 779     */
 780     void SetLabel(int id, const wxString& label);
 781
 782     /**
 783         Sets the title of the menu.
 784
 785         @param title
 786             The title to set.
 787
 788         @remarks This is relevant only to popup menus, use
 789                  wxMenuBar::SetLabelTop for the menus in the menubar.
 790
 791         @see GetTitle()
 792     */
 793     void SetTitle(const wxString& title);
 794
 795     /**
 796         Sends events to @a source (or owning window if @NULL) to update the
 797         menu UI. This is called just before the menu is popped up with
 798         wxWindow::PopupMenu, but
 799         the application may call it at other times if required.
 800     */
 801     void UpdateUI(wxEvtHandler* source = NULL) const;
 802 };