]>
git.saurik.com Git - wxWidgets.git/blob - interface/wx/menu.h
87922d10a8138f07566e57baa17d5ba4030df4d6
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxMenuBar
4 // Author: wxWidgets team
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
12 A menu bar is a series of menus accessible from the top of a frame.
15 To respond to a menu selection, provide a handler for EVT_MENU, in the frame
16 that contains the menu bar.
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.
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.
30 @see wxMenu, @ref overview_events
32 class wxMenuBar
: public wxWindow
36 Construct an empty menu bar.
39 If wxMB_DOCKABLE the menu bar can be detached (wxGTK only).
41 wxMenuBar(long style
= 0);
44 Construct a menu bar from arrays of menus and titles.
49 An array of menus. Do not use this array again - it now belongs to
52 An array of title strings. Deallocate this array after creating
55 If wxMB_DOCKABLE the menu bar can be detached (wxGTK only).
58 Not supported by wxPerl.
61 wxMenuBar(size_t n
, wxMenu
* menus
[], const wxString titles
[],
65 Destructor, destroying the menu bar and removing it from the parent
71 Adds the item to the end of the menu bar.
74 The menu to add. Do not deallocate this menu after calling Append().
76 The title of the menu, must be non-empty.
78 @return @true on success, @false if an error occurred.
82 virtual bool Append(wxMenu
* menu
, const wxString
& title
);
85 Checks or unchecks a menu item.
88 The menu item identifier.
90 If @true, checks the menu item, otherwise the item is unchecked.
92 @remarks Only use this when the menu bar has been associated with a
93 frame; otherwise, use the wxMenu equivalent call.
95 void Check(int id
, bool check
);
98 Enables or disables (greys out) a menu item.
101 The menu item identifier.
103 @true to enable the item, @false to disable it.
105 @remarks Only use this when the menu bar has been associated with a
106 frame; otherwise, use the wxMenu equivalent call.
108 void Enable(int id
, bool enable
);
111 Enables or disables a whole menu.
114 The position of the menu, starting from zero.
116 @true to enable the menu, @false to disable it.
118 @remarks Only use this when the menu bar has been associated with a frame.
120 virtual void EnableTop(size_t pos
, bool enable
);
123 Finds the menu item object associated with the given menu item identifier.
126 Menu item identifier.
128 If not @NULL, menu will get set to the associated menu.
130 @return The found menu item object, or @NULL if one was not found.
133 In wxPerl this method takes just the @a id parameter;
134 in scalar context it returns the associated @c Wx::MenuItem, in list
135 context it returns a 2-element list (item, submenu).
138 virtual wxMenuItem
* FindItem(int id
, wxMenu
** menu
= NULL
) const;
141 Returns the index of the menu with the given @a title or @c wxNOT_FOUND if no
142 such menu exists in this menubar.
144 The @a title parameter may specify either the menu title
145 (with accelerator characters, i.e. @c "&File") or just the
146 menu label (@c "File") indifferently.
148 int FindMenu(const wxString
& title
) const;
151 Finds the menu item id for a menu name/menu item string pair.
158 @return The menu item identifier, or wxNOT_FOUND if none was found.
160 @remarks Any special menu codes are stripped out of source and target
161 strings before matching.
163 virtual int FindMenuItem(const wxString
& menuString
,
164 const wxString
& itemString
) const;
167 Gets the help string associated with the menu item identifier.
170 The menu item identifier.
172 @return The help string, or the empty string if there was no help string
173 or the menu item was not found.
177 wxString
GetHelpString(int id
) const;
180 Gets the label associated with a menu item.
183 The menu item identifier.
185 @return The menu item label, or the empty string if the item was not
188 @remarks Use only after the menubar has been associated with a frame.
190 wxString
GetLabel(int id
) const;
193 Returns the label of a top-level menu. Note that the returned string does not
194 include the accelerator characters which could have been specified in the menu
195 title string during its construction.
198 Position of the menu on the menu bar, starting from zero.
200 @return The menu label, or the empty string if the menu was not found.
202 @remarks Use only after the menubar has been associated with a frame.
205 This function is deprecated in favour of GetMenuLabel() and GetMenuLabelText().
209 wxString
GetLabelTop(size_t pos
) const;
212 Returns the menu at @a menuIndex (zero-based).
214 wxMenu
* GetMenu(size_t menuIndex
) const;
217 Returns the number of menus in this menubar.
219 size_t GetMenuCount() const;
222 Returns the label of a top-level menu. Note that the returned string
223 includes the accelerator characters that have been specified in the menu
224 title string during its construction.
227 Position of the menu on the menu bar, starting from zero.
229 @return The menu label, or the empty string if the menu was not found.
231 @remarks Use only after the menubar has been associated with a frame.
233 @see GetMenuLabelText(), SetMenuLabel()
235 virtual wxString
GetMenuLabel(size_t pos
) const;
238 Returns the label of a top-level menu. Note that the returned string does not
239 include any accelerator characters that may have been specified in the menu
240 title string during its construction.
243 Position of the menu on the menu bar, starting from zero.
245 @return The menu label, or the empty string if the menu was not found.
247 @remarks Use only after the menubar has been associated with a frame.
249 @see GetMenuLabel(), SetMenuLabel()
251 virtual wxString
GetMenuLabelText(size_t pos
) const;
254 Inserts the menu at the given position into the menu bar. Inserting menu at
255 position 0 will insert it in the very beginning of it, inserting at position
256 GetMenuCount() is the same as calling Append().
259 The position of the new menu in the menu bar
261 The menu to add. wxMenuBar owns the menu and will free it.
263 The title of the menu.
265 @return @true on success, @false if an error occurred.
269 virtual bool Insert(size_t pos
, wxMenu
* menu
, const wxString
& title
);
272 Determines whether an item is checked.
275 The menu item identifier.
277 @return @true if the item was found and is checked, @false otherwise.
279 bool IsChecked(int id
) const;
282 Determines whether an item is enabled.
285 The menu item identifier.
287 @return @true if the item was found and is enabled, @false otherwise.
289 bool IsEnabled(int id
) const;
294 virtual void Refresh(bool eraseBackground
= true, const wxRect
* rect
= NULL
);
297 Removes the menu from the menu bar and returns the menu object - the caller
298 is responsible for deleting it. This function may be used together with
299 Insert() to change the menubar dynamically.
303 virtual wxMenu
* Remove(size_t pos
);
306 Replaces the menu at the given position with another one.
309 The position of the new menu in the menu bar
313 The title of the menu.
315 @return The menu which was previously at position pos.
316 The caller is responsible for deleting it.
318 @see Insert(), Remove()
320 virtual wxMenu
* Replace(size_t pos
, wxMenu
* menu
, const wxString
& title
);
323 Sets the help string associated with a menu item.
326 Menu item identifier.
328 Help string to associate with the menu item.
332 void SetHelpString(int id
, const wxString
& helpString
);
335 Sets the label of a menu item.
338 Menu item identifier.
342 @remarks Use only after the menubar has been associated with a frame.
346 void SetLabel(int id
, const wxString
& label
);
349 Sets the label of a top-level menu.
352 The position of a menu on the menu bar, starting from zero.
356 @remarks Use only after the menubar has been associated with a frame.
359 This function has been deprecated in favour of SetMenuLabel().
363 void SetLabelTop(size_t pos
, const wxString
& label
);
366 Sets the label of a top-level menu.
369 The position of a menu on the menu bar, starting from zero.
373 @remarks Use only after the menubar has been associated with a frame.
375 virtual void SetMenuLabel(size_t pos
, const wxString
& label
);
383 A menu is a popup (or pull down) list of items, one of which may be
384 selected before the menu goes away (clicking elsewhere dismisses the
385 menu). Menus may be used to construct either menu bars or popup menus.
387 A menu item has an integer ID associated with it which can be used to
388 identify the selection, or to change the menu item in some way. A menu item
389 with a special identifier @e wxID_SEPARATOR is a separator item and doesn't
390 have an associated command but just makes a separator line appear in the
394 Please note that @e wxID_ABOUT and @e wxID_EXIT are predefined by wxWidgets
395 and have a special meaning since entries using these IDs will be taken out
396 of the normal menus under MacOS X and will be inserted into the system menu
397 (following the appropriate MacOS X interface guideline).
398 On PalmOS @e wxID_EXIT is disabled according to Palm OS Companion guidelines.
400 Menu items may be either @e normal items, @e check items or @e radio items.
401 Normal items don't have any special properties while the check items have a
402 boolean flag associated to them and they show a checkmark in the menu when
404 wxWidgets automatically toggles the flag value when the item is clicked and its
405 value may be retrieved using either wxMenu::IsChecked method of wxMenu or
406 wxMenuBar itself or by using wxEvent::IsChecked when you get the menu
407 notification for the item in question.
409 The radio items are similar to the check items except that all the other items
410 in the same radio group are unchecked when a radio item is checked. The radio
411 group is formed by a contiguous range of radio items, i.e. it starts at the
412 first item of this kind and ends with the first item of a different kind (or
413 the end of the menu). Notice that because the radio groups are defined in terms
414 of the item positions inserting or removing the items in the menu containing
415 the radio items risks to not work correctly.
418 @section menu_allocation Allocation strategy
420 All menus must be created on the @b heap because all menus attached to a
421 menubar or to another menu will be deleted by their parent when it is
422 deleted. The only exception to this rule are the popup menus (i.e. menus
423 used with wxWindow::PopupMenu()) as wxWidgets does not destroy them to
424 allow reusing the same menu more than once. But the exception applies only
425 to the menus themselves and not to any submenus of popup menus which are
426 still destroyed by wxWidgets as usual and so must be heap-allocated.
428 As the frame menubar is deleted by the frame itself, it means that normally
429 all menus used are deleted automatically.
432 @section menu_eventhandling Event handling
434 If the menu is part of a menubar, then wxMenuBar event processing is used.
436 With a popup menu (see wxWindow::PopupMenu), there is a variety of ways to
437 handle a menu selection event (@c wxEVT_COMMAND_MENU_SELECTED):
438 - Provide @c EVT_MENU handlers in the window which pops up the menu, or in an
439 ancestor of that window (the simplest method);
440 - Derive a new class from wxMenu and define event table entries using the @c EVT_MENU macro;
441 - Set a new event handler for wxMenu, through wxEvtHandler::SetNextHandler,
442 specifying an object whose class has @c EVT_MENU entries;
444 Note that instead of static @c EVT_MENU macros you can also use dynamic
445 connection; see @ref overview_events_bind.
450 @see wxMenuBar, wxWindow::PopupMenu, @ref overview_events,
451 @ref wxFileHistory "wxFileHistory (most recently used files menu)"
453 class wxMenu
: public wxEvtHandler
458 Constructs a wxMenu object.
463 Constructs a wxMenu object.
466 If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only).
471 Constructs a wxMenu object with a title.
474 Title at the top of the menu (not always supported).
476 If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only).
478 wxMenu(const wxString
& title
, long style
= 0);
481 Destructor, destroying the menu.
484 Under Motif, a popup menu must have a valid parent (the window
485 it was last popped up on) when being destroyed. Therefore, make sure
486 you delete or re-use the popup menu @e before destroying the parent
487 window. Re-use in this context means popping up the menu on a different
488 window from last time, which causes an implicit destruction and
489 recreation of internal data structures.
497 The menu command identifier.
499 The string to appear on the menu item.
500 See wxMenuItem::SetItemLabel() for more details.
502 An optional help string associated with the item.
503 By default, the handler for the @c wxEVT_MENU_HIGHLIGHT event displays
504 this string in the status line.
506 May be @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, @c wxITEM_CHECK or @c wxITEM_RADIO.
510 m_pFileMenu->Append(ID_NEW_FILE, "&New file\tCTRL+N", "Creates a new XYZ document");
512 or even better for stock menu items (see wxMenuItem::wxMenuItem):
514 m_pFileMenu->Append(wxID_NEW, "", "Creates a new XYZ document");
518 This command can be used after the menu has been shown, as well as on
519 initial creation of a menu or menubar.
521 @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
522 AppendSubMenu(), Insert(), SetLabel(), GetHelpString(),
523 SetHelpString(), wxMenuItem
525 wxMenuItem
* Append(int id
, const wxString
& item
= wxEmptyString
,
526 const wxString
& helpString
= wxEmptyString
,
527 wxItemKind kind
= wxITEM_NORMAL
);
532 @deprecated This function is deprecated, use AppendSubMenu() instead.
535 The menu command identifier.
537 The string to appear on the menu item.
541 An optional help string associated with the item.
542 By default, the handler for the @c wxEVT_MENU_HIGHLIGHT event displays
543 this string in the status line.
545 @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
546 AppendSubMenu(), Insert(), SetLabel(), GetHelpString(),
547 SetHelpString(), wxMenuItem
549 wxMenuItem
* Append(int id
, const wxString
& item
, wxMenu
* subMenu
,
550 const wxString
& helpString
= wxEmptyString
);
553 Adds a menu item object.
555 This is the most generic variant of Append() method because it may be
556 used for both items (including separators) and submenus and because
557 you can also specify various extra properties of a menu item this way,
558 such as bitmaps and fonts.
561 A menuitem object. It will be owned by the wxMenu object after this
562 function is called, so do not delete it yourself.
565 See the remarks for the other Append() overloads.
567 @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
568 AppendSubMenu(), Insert(), SetLabel(), GetHelpString(),
569 SetHelpString(), wxMenuItem
571 wxMenuItem
* Append(wxMenuItem
* menuItem
);
574 Adds a checkable item to the end of the menu.
576 @see Append(), InsertCheckItem()
578 wxMenuItem
* AppendCheckItem(int id
, const wxString
& item
,
579 const wxString
& help
= wxEmptyString
);
582 Adds a radio item to the end of the menu.
583 All consequent radio items form a group and when an item in the group is
584 checked, all the others are automatically unchecked.
586 @note Radio items are not supported under wxMotif.
588 @see Append(), InsertRadioItem()
590 wxMenuItem
* AppendRadioItem(int id
, const wxString
& item
,
591 const wxString
& help
= wxEmptyString
);
594 Adds a separator to the end of the menu.
596 @see Append(), InsertSeparator()
598 wxMenuItem
* AppendSeparator();
601 Adds the given @a submenu to this menu. @a text is the text shown in the
602 menu for it and @a help is the help string shown in the status bar when the
603 submenu item is selected.
605 wxMenuItem
* AppendSubMenu(wxMenu
* submenu
, const wxString
& text
,
606 const wxString
& help
= wxEmptyString
);
609 Inserts a break in a menu, causing the next appended item to appear in
612 virtual void Break();
615 Checks or unchecks the menu item.
618 The menu item identifier.
620 If @true, the item will be checked, otherwise it will be unchecked.
624 void Check(int id
, bool check
);
627 Deletes the menu item from the menu. If the item is a submenu, it will
628 @b not be deleted. Use Destroy() if you want to delete a submenu.
631 Id of the menu item to be deleted.
633 @see FindItem(), Destroy(), Remove()
638 Deletes the menu item from the menu. If the item is a submenu, it will
639 @b not be deleted. Use Destroy() if you want to delete a submenu.
642 Menu item to be deleted.
644 @see FindItem(), Destroy(), Remove()
646 bool Delete(wxMenuItem
* item
);
649 Deletes the menu item from the menu. If the item is a submenu, it will
650 be deleted. Use Remove() if you want to keep the submenu (for example,
654 Id of the menu item to be deleted.
656 @see FindItem(), Delete(), Remove()
658 bool Destroy(int id
);
661 Deletes the menu item from the menu. If the item is a submenu, it will
662 be deleted. Use Remove() if you want to keep the submenu (for example,
666 Menu item to be deleted.
668 @see FindItem(), Delete(), Remove()
670 bool Destroy(wxMenuItem
* item
);
673 Enables or disables (greys out) a menu item.
676 The menu item identifier.
678 @true to enable the menu item, @false to disable it.
682 void Enable(int id
, bool enable
);
685 Finds the menu item object associated with the given menu item identifier
686 and, optionally, the position of the item in the menu.
688 Unlike FindItem(), this function doesn't recurse but only looks at the
689 direct children of this menu.
692 The identifier of the menu item to find.
694 If the pointer is not @NULL, it is filled with the item's position if
695 it was found or @c (size_t)wxNOT_FOUND otherwise.
697 Menu item object or @NULL if not found.
699 wxMenuItem
*FindChildItem(int id
, size_t *pos
= NULL
) const;
702 Finds the menu id for a menu item string.
705 Menu item string to find.
707 @return Menu item identifier, or wxNOT_FOUND if none is found.
709 @remarks Any special menu codes are stripped out of source and target
710 strings before matching.
712 virtual int FindItem(const wxString
& itemString
) const;
715 Finds the menu item object associated with the given menu item identifier and,
716 optionally, the (sub)menu it belongs to.
719 Menu item identifier.
721 If the pointer is not @NULL, it will be filled with the item's
722 parent menu (if the item was found)
724 @return Menu item object or NULL if none is found.
726 wxMenuItem
* FindItem(int id
, wxMenu
** menu
= NULL
) const;
729 Returns the wxMenuItem given a position in the menu.
731 wxMenuItem
* FindItemByPosition(size_t position
) const;
734 Returns the help string associated with a menu item.
737 The menu item identifier.
739 @return The help string, or the empty string if there is no help string
740 or the item was not found.
742 @see SetHelpString(), Append()
744 virtual wxString
GetHelpString(int id
) const;
747 Returns a menu item label.
750 The menu item identifier.
752 @return The item label, or the empty string if the item was not found.
754 @see GetLabelText(), SetLabel()
756 wxString
GetLabel(int id
) const;
759 Returns a menu item label, without any of the original mnemonics and
763 The menu item identifier.
765 @return The item label, or the empty string if the item was not found.
767 @see GetLabel(), SetLabel()
769 wxString
GetLabelText(int id
) const;
772 Returns the number of items in the menu.
774 size_t GetMenuItemCount() const;
778 Returns the list of items in the menu.
780 wxMenuItemList is a pseudo-template list class containing wxMenuItem
781 pointers, see wxList.
783 wxMenuItemList
& GetMenuItems() const;
784 const wxMenuItemList
& GetMenuItems() const;
788 Returns the title of the menu.
792 const wxString
& GetTitle() const;
795 Inserts the given @a item before the position @a pos.
797 Inserting the item at position GetMenuItemCount() is the same
800 @see Append(), Prepend()
802 wxMenuItem
* Insert(size_t pos
, wxMenuItem
* item
);
805 Inserts the given @a item before the position @a pos.
807 Inserting the item at position GetMenuItemCount() is the same
810 @see Append(), Prepend()
812 wxMenuItem
* Insert(size_t pos
, int id
,
813 const wxString
& item
= wxEmptyString
,
814 const wxString
& helpString
= wxEmptyString
,
815 wxItemKind kind
= wxITEM_NORMAL
);
818 Inserts a checkable item at the given position.
820 @see Insert(), AppendCheckItem()
822 wxMenuItem
* InsertCheckItem(size_t pos
, int id
, const wxString
& item
,
823 const wxString
& helpString
= wxEmptyString
);
826 Inserts a radio item at the given position.
828 @see Insert(), AppendRadioItem()
830 wxMenuItem
* InsertRadioItem(size_t pos
, int id
, const wxString
& item
,
831 const wxString
& helpString
= wxEmptyString
);
834 Inserts a separator at the given position.
836 @see Insert(), AppendSeparator()
838 wxMenuItem
* InsertSeparator(size_t pos
);
841 Determines whether a menu item is checked.
844 The menu item identifier.
846 @return @true if the menu item is checked, @false otherwise.
850 bool IsChecked(int id
) const;
853 Determines whether a menu item is enabled.
856 The menu item identifier.
858 @return @true if the menu item is enabled, @false otherwise.
862 bool IsEnabled(int id
) const;
865 Inserts the given @a item at position 0, i.e. before all the other
868 @see Append(), Insert()
870 wxMenuItem
* Prepend(wxMenuItem
* item
);
873 Inserts the given @a item at position 0, i.e. before all the other
876 @see Append(), Insert()
878 wxMenuItem
* Prepend(int id
, const wxString
& item
= wxEmptyString
,
879 const wxString
& helpString
= wxEmptyString
,
880 wxItemKind kind
= wxITEM_NORMAL
);
883 Inserts a checkable item at position 0.
885 @see Prepend(), AppendCheckItem()
887 wxMenuItem
* PrependCheckItem(int id
, const wxString
& item
,
888 const wxString
& helpString
= wxEmptyString
);
891 Inserts a radio item at position 0.
893 @see Prepend(), AppendRadioItem()
895 wxMenuItem
* PrependRadioItem(int id
, const wxString
& item
,
896 const wxString
& helpString
= wxEmptyString
);
899 Inserts a separator at position 0.
901 @see Prepend(), AppendSeparator()
903 wxMenuItem
* PrependSeparator();
906 Removes the menu item from the menu but doesn't delete the associated C++
907 object. This allows you to reuse the same item later by adding it back to
908 the menu (especially useful with submenus).
911 The identifier of the menu item to remove.
913 @return A pointer to the item which was detached from the menu.
915 wxMenuItem
* Remove(int id
);
918 Removes the menu item from the menu but doesn't delete the associated C++
919 object. This allows you to reuse the same item later by adding it back to
920 the menu (especially useful with submenus).
923 The menu item to remove.
925 @return A pointer to the item which was detached from the menu.
927 wxMenuItem
* Remove(wxMenuItem
* item
);
930 Sets an item's help string.
933 The menu item identifier.
935 The help string to set.
939 virtual void SetHelpString(int id
, const wxString
& helpString
);
942 Sets the label of a menu item.
945 The menu item identifier.
947 The menu item label to set.
949 @see Append(), GetLabel()
951 void SetLabel(int id
, const wxString
& label
);
954 Sets the title of the menu.
959 @remarks Notice that you can only call this method directly for the
960 popup menus, to change the title of a menu that is part of a menu
961 bar you need to use wxMenuBar::SetLabelTop().
965 virtual void SetTitle(const wxString
& title
);
968 Sends events to @a source (or owning window if @NULL) to update the
971 This is called just before the menu is popped up with wxWindow::PopupMenu,
972 but the application may call it at other times if required.
974 void UpdateUI(wxEvtHandler
* source
= NULL
);