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