]>
git.saurik.com Git - wxWidgets.git/blob - interface/wx/menu.h
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
457 Constructs a wxMenu object.
460 If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only).
465 Constructs a wxMenu object with a title.
468 Title at the top of the menu (not always supported).
470 If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only).
472 wxMenu(const wxString
& title
, long style
= 0);
475 Destructor, destroying the menu.
478 Under Motif, a popup menu must have a valid parent (the window
479 it was last popped up on) when being destroyed. Therefore, make sure
480 you delete or re-use the popup menu @e before destroying the parent
481 window. Re-use in this context means popping up the menu on a different
482 window from last time, which causes an implicit destruction and
483 recreation of internal data structures.
491 The menu command identifier.
493 The string to appear on the menu item.
494 See wxMenuItem::SetItemLabel() for more details.
496 An optional help string associated with the item.
497 By default, the handler for the @c wxEVT_MENU_HIGHLIGHT event displays
498 this string in the status line.
500 May be @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, @c wxITEM_CHECK or @c wxITEM_RADIO.
504 m_pFileMenu->Append(ID_NEW_FILE, "&New file\tCTRL+N", "Creates a new XYZ document");
506 or even better for stock menu items (see wxMenuItem::wxMenuItem):
508 m_pFileMenu->Append(wxID_NEW, "", "Creates a new XYZ document");
512 This command can be used after the menu has been shown, as well as on
513 initial creation of a menu or menubar.
515 @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
516 AppendSubMenu(), Insert(), SetLabel(), GetHelpString(),
517 SetHelpString(), wxMenuItem
519 wxMenuItem
* Append(int id
, const wxString
& item
= wxEmptyString
,
520 const wxString
& helpString
= wxEmptyString
,
521 wxItemKind kind
= wxITEM_NORMAL
);
526 @deprecated This function is deprecated, use AppendSubMenu() instead.
529 The menu command identifier.
531 The string to appear on the menu item.
535 An optional help string associated with the item.
536 By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays
537 this string in the status line.
539 @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
540 AppendSubMenu(), Insert(), SetLabel(), GetHelpString(),
541 SetHelpString(), wxMenuItem
543 wxMenuItem
* Append(int id
, const wxString
& item
, wxMenu
* subMenu
,
544 const wxString
& helpString
= wxEmptyString
);
547 Adds a menu item object.
549 This is the most generic variant of Append() method because it may be
550 used for both items (including separators) and submenus and because
551 you can also specify various extra properties of a menu item this way,
552 such as bitmaps and fonts.
555 A menuitem object. It will be owned by the wxMenu object after this
556 function is called, so do not delete it yourself.
559 See the remarks for the other Append() overloads.
561 @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
562 AppendSubMenu(), Insert(), SetLabel(), GetHelpString(),
563 SetHelpString(), wxMenuItem
565 wxMenuItem
* Append(wxMenuItem
* menuItem
);
568 Adds a checkable item to the end of the menu.
570 @see Append(), InsertCheckItem()
572 wxMenuItem
* AppendCheckItem(int id
, const wxString
& item
,
573 const wxString
& help
= wxEmptyString
);
576 Adds a radio item to the end of the menu.
577 All consequent radio items form a group and when an item in the group is
578 checked, all the others are automatically unchecked.
580 @note Radio items are not supported under wxMotif.
582 @see Append(), InsertRadioItem()
584 wxMenuItem
* AppendRadioItem(int id
, const wxString
& item
,
585 const wxString
& help
= wxEmptyString
);
588 Adds a separator to the end of the menu.
590 @see Append(), InsertSeparator()
592 wxMenuItem
* AppendSeparator();
595 Adds the given @a submenu to this menu. @a text is the text shown in the
596 menu for it and @a help is the help string shown in the status bar when the
597 submenu item is selected.
599 wxMenuItem
* AppendSubMenu(wxMenu
* submenu
, const wxString
& text
,
600 const wxString
& help
= wxEmptyString
);
603 Inserts a break in a menu, causing the next appended item to appear in
606 virtual void Break();
609 Checks or unchecks the menu item.
612 The menu item identifier.
614 If @true, the item will be checked, otherwise it will be unchecked.
618 void Check(int id
, bool check
);
621 Deletes the menu item from the menu. If the item is a submenu, it will
622 @b not be deleted. Use Destroy() if you want to delete a submenu.
625 Id of the menu item to be deleted.
627 @see FindItem(), Destroy(), Remove()
632 Deletes the menu item from the menu. If the item is a submenu, it will
633 @b not be deleted. Use Destroy() if you want to delete a submenu.
636 Menu item to be deleted.
638 @see FindItem(), Destroy(), Remove()
640 bool Delete(wxMenuItem
* item
);
643 Deletes the menu item from the menu. If the item is a submenu, it will
644 be deleted. Use Remove() if you want to keep the submenu (for example,
648 Id of the menu item to be deleted.
650 @see FindItem(), Delete(), Remove()
652 bool Destroy(int id
);
655 Deletes the menu item from the menu. If the item is a submenu, it will
656 be deleted. Use Remove() if you want to keep the submenu (for example,
660 Menu item to be deleted.
662 @see FindItem(), Delete(), Remove()
664 bool Destroy(wxMenuItem
* item
);
667 Enables or disables (greys out) a menu item.
670 The menu item identifier.
672 @true to enable the menu item, @false to disable it.
676 void Enable(int id
, bool enable
);
679 Finds the menu item object associated with the given menu item identifier
680 and, optionally, the position of the item in the menu.
682 Unlike FindItem(), this function doesn't recurse but only looks at the
683 direct children of this menu.
686 The identifier of the menu item to find.
688 If the pointer is not @NULL, it is filled with the item's position if
689 it was found or @c (size_t)wxNOT_FOUND otherwise.
691 Menu item object or @NULL if not found.
693 wxMenuItem
*FindChildItem(int id
, size_t *pos
= NULL
) const;
696 Finds the menu id for a menu item string.
699 Menu item string to find.
701 @return Menu item identifier, or wxNOT_FOUND if none is found.
703 @remarks Any special menu codes are stripped out of source and target
704 strings before matching.
706 virtual int FindItem(const wxString
& itemString
) const;
709 Finds the menu item object associated with the given menu item identifier and,
710 optionally, the (sub)menu it belongs to.
713 Menu item identifier.
715 If the pointer is not @NULL, it will be filled with the item's
716 parent menu (if the item was found)
718 @return Menu item object or NULL if none is found.
720 wxMenuItem
* FindItem(int id
, wxMenu
** menu
= NULL
) const;
723 Returns the wxMenuItem given a position in the menu.
725 wxMenuItem
* FindItemByPosition(size_t position
) const;
728 Returns the help string associated with a menu item.
731 The menu item identifier.
733 @return The help string, or the empty string if there is no help string
734 or the item was not found.
736 @see SetHelpString(), Append()
738 virtual wxString
GetHelpString(int id
) const;
741 Returns a menu item label.
744 The menu item identifier.
746 @return The item label, or the empty string if the item was not found.
748 @see GetLabelText(), SetLabel()
750 wxString
GetLabel(int id
) const;
753 Returns a menu item label, without any of the original mnemonics and
757 The menu item identifier.
759 @return The item label, or the empty string if the item was not found.
761 @see GetLabel(), SetLabel()
763 wxString
GetLabelText(int id
) const;
766 Returns the number of items in the menu.
768 size_t GetMenuItemCount() const;
772 Returns the list of items in the menu.
774 wxMenuItemList is a pseudo-template list class containing wxMenuItem
775 pointers, see wxList.
777 wxMenuItemList
& GetMenuItems() const;
778 const wxMenuItemList
& GetMenuItems() const;
782 Returns the title of the menu.
784 @remarks This is relevant only to popup menus, use
785 wxMenuBar::GetMenuLabel for the menus in the menubar.
789 const wxString
& GetTitle() const;
792 Inserts the given @a item before the position @a pos.
794 Inserting the item at position GetMenuItemCount() is the same
797 @see Append(), Prepend()
799 wxMenuItem
* Insert(size_t pos
, wxMenuItem
* item
);
802 Inserts the given @a item before the position @a pos.
804 Inserting the item at position GetMenuItemCount() is the same
807 @see Append(), Prepend()
809 wxMenuItem
* Insert(size_t pos
, int id
,
810 const wxString
& item
= wxEmptyString
,
811 const wxString
& helpString
= wxEmptyString
,
812 wxItemKind kind
= wxITEM_NORMAL
);
815 Inserts a checkable item at the given position.
817 @see Insert(), AppendCheckItem()
819 wxMenuItem
* InsertCheckItem(size_t pos
, int id
, const wxString
& item
,
820 const wxString
& helpString
= wxEmptyString
);
823 Inserts a radio item at the given position.
825 @see Insert(), AppendRadioItem()
827 wxMenuItem
* InsertRadioItem(size_t pos
, int id
, const wxString
& item
,
828 const wxString
& helpString
= wxEmptyString
);
831 Inserts a separator at the given position.
833 @see Insert(), AppendSeparator()
835 wxMenuItem
* InsertSeparator(size_t pos
);
838 Determines whether a menu item is checked.
841 The menu item identifier.
843 @return @true if the menu item is checked, @false otherwise.
847 bool IsChecked(int id
) const;
850 Determines whether a menu item is enabled.
853 The menu item identifier.
855 @return @true if the menu item is enabled, @false otherwise.
859 bool IsEnabled(int id
) const;
862 Inserts the given @a item at position 0, i.e. before all the other
865 @see Append(), Insert()
867 wxMenuItem
* Prepend(wxMenuItem
* item
);
870 Inserts the given @a item at position 0, i.e. before all the other
873 @see Append(), Insert()
875 wxMenuItem
* Prepend(int id
, const wxString
& item
= wxEmptyString
,
876 const wxString
& helpString
= wxEmptyString
,
877 wxItemKind kind
= wxITEM_NORMAL
);
880 Inserts a checkable item at position 0.
882 @see Prepend(), AppendCheckItem()
884 wxMenuItem
* PrependCheckItem(int id
, const wxString
& item
,
885 const wxString
& helpString
= wxEmptyString
);
888 Inserts a radio item at position 0.
890 @see Prepend(), AppendRadioItem()
892 wxMenuItem
* PrependRadioItem(int id
, const wxString
& item
,
893 const wxString
& helpString
= wxEmptyString
);
896 Inserts a separator at position 0.
898 @see Prepend(), AppendSeparator()
900 wxMenuItem
* PrependSeparator();
903 Removes the menu item from the menu but doesn't delete the associated C++
904 object. This allows you to reuse the same item later by adding it back to
905 the menu (especially useful with submenus).
908 The identifier of the menu item to remove.
910 @return A pointer to the item which was detached from the menu.
912 wxMenuItem
* Remove(int id
);
915 Removes the menu item from the menu but doesn't delete the associated C++
916 object. This allows you to reuse the same item later by adding it back to
917 the menu (especially useful with submenus).
920 The menu item to remove.
922 @return A pointer to the item which was detached from the menu.
924 wxMenuItem
* Remove(wxMenuItem
* item
);
927 Sets an item's help string.
930 The menu item identifier.
932 The help string to set.
936 virtual void SetHelpString(int id
, const wxString
& helpString
);
939 Sets the label of a menu item.
942 The menu item identifier.
944 The menu item label to set.
946 @see Append(), GetLabel()
948 void SetLabel(int id
, const wxString
& label
);
951 Sets the title of the menu.
956 @remarks This is relevant only to popup menus, use
957 wxMenuBar::SetLabelTop for the menus in the menubar.
961 virtual void SetTitle(const wxString
& title
);
964 Sends events to @a source (or owning window if @NULL) to update the
967 This is called just before the menu is popped up with wxWindow::PopupMenu,
968 but the application may call it at other times if required.
970 void UpdateUI(wxEvtHandler
* source
= NULL
);