interface/menu.h

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