]>
git.saurik.com Git - wxWidgets.git/blob - interface/wx/menu.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxMenuBar
4 // Author: wxWidgets team
6 // Licence: wxWindows license
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.
31 @see wxMenu, @ref overview_eventhandling
33 class wxMenuBar
: public wxWindow
37 Construct an empty menu bar.
40 If wxMB_DOCKABLE the menu bar can be detached (wxGTK only).
42 wxMenuBar(long style
= 0);
45 Construct a menu bar from arrays of menus and titles.
50 An array of menus. Do not use this array again - it now belongs to
53 An array of title strings. Deallocate this array after creating
56 If wxMB_DOCKABLE the menu bar can be detached (wxGTK only).
58 wxMenuBar(size_t n
, wxMenu
* menus
[], const wxString titles
[],
62 Destructor, destroying the menu bar and removing it from the parent
68 Adds the item to the end of the menu bar.
71 The menu to add. Do not deallocate this menu after calling Append().
73 The title of the menu.
75 @return @true on success, @false if an error occurred.
79 virtual bool Append(wxMenu
* menu
, const wxString
& title
);
82 Checks or unchecks a menu item.
85 The menu item identifier.
87 If @true, checks the menu item, otherwise the item is unchecked.
89 @remarks Only use this when the menu bar has been associated with a
90 frame; otherwise, use the wxMenu equivalent call.
92 void Check(int id
, bool check
);
95 Enables or disables (greys out) a menu item.
98 The menu item identifier.
100 @true to enable the item, @false to disable it.
102 @remarks Only use this when the menu bar has been associated with a
103 frame; otherwise, use the wxMenu equivalent call.
105 void Enable(int id
, bool enable
);
108 Enables or disables a whole menu.
111 The position of the menu, starting from zero.
113 @true to enable the menu, @false to disable it.
115 @remarks Only use this when the menu bar has been associated with a frame.
117 virtual void EnableTop(size_t pos
, bool enable
);
120 Finds the menu item object associated with the given menu item identifier.
123 Menu item identifier.
125 If not @NULL, menu will get set to the associated menu.
127 @return The found menu item object, or @NULL if one was not found.
129 virtual wxMenuItem
* FindItem(int id
, wxMenu
* menu
= NULL
) const;
132 Returns the index of the menu with the given @a title or @c wxNOT_FOUND if no
133 such menu exists in this menubar.
135 The @a title parameter may specify either the menu title
136 (with accelerator characters, i.e. @c "&File") or just the
137 menu label (@c "File") indifferently.
139 int FindMenu(const wxString
& title
) const;
142 Finds the menu item id for a menu name/menu item string pair.
149 @return The menu item identifier, or wxNOT_FOUND if none was found.
151 @remarks Any special menu codes are stripped out of source and target
152 strings before matching.
154 virtual int FindMenuItem(const wxString
& menuString
,
155 const wxString
& itemString
) const;
158 Gets the help string associated with the menu item identifier.
161 The menu item identifier.
163 @return The help string, or the empty string if there was no help string
164 or the menu item was not found.
168 wxString
GetHelpString(int id
) const;
171 Gets the label associated with a menu item.
174 The menu item identifier.
176 @return The menu item label, or the empty string if the item was not
179 @remarks Use only after the menubar has been associated with a frame.
181 wxString
GetLabel(int id
) const;
184 Returns the label of a top-level menu. Note that the returned string does not
185 include the accelerator characters which could have been specified in the menu
186 title string during its construction.
189 Position of the menu on the menu bar, starting from zero.
191 @return The menu label, or the empty string if the menu was not found.
193 @remarks Use only after the menubar has been associated with a frame.
196 This function is deprecated in favour of GetMenuLabel() and GetMenuLabelText().
200 wxString
GetLabelTop(size_t pos
) const;
203 Returns the menu at @a menuIndex (zero-based).
205 wxMenu
* GetMenu(size_t menuIndex
) const;
208 Returns the number of menus in this menubar.
210 size_t GetMenuCount() const;
213 Returns the label of a top-level menu. Note that the returned string
214 includes the accelerator characters that have been specified in the menu
215 title string during its construction.
218 Position of the menu on the menu bar, starting from zero.
220 @return The menu label, or the empty string if the menu was not found.
222 @remarks Use only after the menubar has been associated with a frame.
224 @see GetMenuLabelText(), SetMenuLabel()
226 virtual wxString
GetMenuLabel(size_t pos
) const;
229 Returns the label of a top-level menu. Note that the returned string does not
230 include any accelerator characters that may have been specified in the menu
231 title string during its construction.
234 Position of the menu on the menu bar, starting from zero.
236 @return The menu label, or the empty string if the menu was not found.
238 @remarks Use only after the menubar has been associated with a frame.
240 @see GetMenuLabel(), SetMenuLabel()
242 virtual wxString
GetMenuLabelText(size_t pos
) const;
245 Inserts the menu at the given position into the menu bar. Inserting menu at
246 position 0 will insert it in the very beginning of it, inserting at position
247 GetMenuCount() is the same as calling Append().
250 The position of the new menu in the menu bar
252 The menu to add. wxMenuBar owns the menu and will free it.
254 The title of the menu.
256 @return @true on success, @false if an error occurred.
260 virtual bool Insert(size_t pos
, wxMenu
* menu
, const wxString
& title
);
263 Determines whether an item is checked.
266 The menu item identifier.
268 @return @true if the item was found and is checked, @false otherwise.
270 bool IsChecked(int id
) const;
273 Determines whether an item is enabled.
276 The menu item identifier.
278 @return @true if the item was found and is enabled, @false otherwise.
280 bool IsEnabled(int id
) const;
285 virtual void Refresh(bool eraseBackground
= true, const wxRect
* rect
= NULL
);
288 Removes the menu from the menu bar and returns the menu object - the caller
289 is responsible for deleting it. This function may be used together with
290 Insert() to change the menubar dynamically.
294 virtual wxMenu
* Remove(size_t pos
);
297 Replaces the menu at the given position with another one.
300 The position of the new menu in the menu bar
304 The title of the menu.
306 @return The menu which was previously at position pos.
307 The caller is responsible for deleting it.
309 @see Insert(), Remove()
311 virtual wxMenu
* Replace(size_t pos
, wxMenu
* menu
, const wxString
& title
);
314 Sets the help string associated with a menu item.
317 Menu item identifier.
319 Help string to associate with the menu item.
323 void SetHelpString(int id
, const wxString
& helpString
);
326 Sets the label of a menu item.
329 Menu item identifier.
333 @remarks Use only after the menubar has been associated with a frame.
337 void SetLabel(int id
, const wxString
& label
);
340 Sets the label of a top-level menu.
343 The position of a menu on the menu bar, starting from zero.
347 @remarks Use only after the menubar has been associated with a frame.
350 This function has been deprecated in favour of SetMenuLabel().
354 void SetLabelTop(size_t pos
, const wxString
& label
);
357 Sets the label of a top-level menu.
360 The position of a menu on the menu bar, starting from zero.
364 @remarks Use only after the menubar has been associated with a frame.
366 virtual void SetMenuLabel(size_t pos
, const wxString
& label
);
374 A menu is a popup (or pull down) list of items, one of which may be
375 selected before the menu goes away (clicking elsewhere dismisses the
376 menu). Menus may be used to construct either menu bars or popup menus.
378 A menu item has an integer ID associated with it which can be used to
379 identify the selection, or to change the menu item in some way. A menu item
380 with a special identifier -1 is a separator item and doesn't have an
381 associated command but just makes a separator line appear in the menu.
384 Please note that @e wxID_ABOUT and @e wxID_EXIT are predefined by wxWidgets
385 and have a special meaning since entries using these IDs will be taken out
386 of the normal menus under MacOS X and will be inserted into the system menu
387 (following the appropriate MacOS X interface guideline).
388 On PalmOS @e wxID_EXIT is disabled according to Palm OS Companion guidelines.
390 Menu items may be either normal items, check items or radio items.
391 Normal items don't have any special properties while the check items have a
392 boolean flag associated to them and they show a checkmark in the menu when
394 wxWidgets automatically toggles the flag value when the item is clicked and its
395 value may be retrieved using either wxMenu::IsChecked method of wxMenu or
396 wxMenuBar itself or by using wxEvent::IsChecked when you get the menu
397 notification for the item in question.
399 The radio items are similar to the check items except that all the other items
400 in the same radio group are unchecked when a radio item is checked. The radio
401 group is formed by a contiguous range of radio items, i.e. it starts at the
402 first item of this kind and ends with the first item of a different kind (or
403 the end of the menu). Notice that because the radio groups are defined in terms
404 of the item positions inserting or removing the items in the menu containing
405 the radio items risks to not work correctly. Finally note that radio items
406 are not supported under Motif.
409 @section menu_allocation Allocation strategy
411 All menus except the popup ones must be created on the heap.
412 All menus attached to a menubar or to another menu will be deleted by their
413 parent when it is deleted.
414 As the frame menubar is deleted by the frame itself, it means that normally
415 all menus used are deleted automatically.
418 @section menu_eventhandling Event handling
420 If the menu is part of a menubar, then wxMenuBar event processing is used.
421 With a popup menu, there is a variety of ways to handle a menu selection event
422 (wxEVT_COMMAND_MENU_SELECTED).
423 Derive a new class from wxMenu and define event table entries using the EVT_MENU macro.
424 Set a new event handler for wxMenu, using an object whose class has EVT_MENU entries.
425 Provide EVT_MENU handlers in the window which pops up the menu, or in an
426 ancestor of this window.
432 @see wxMenuBar, wxWindow::PopupMenu, @ref overview_eventhandling,
433 @ref wxFileHistory "wxFileHistory (most recently used files menu)"
435 class wxMenu
: public wxEvtHandler
439 Constructs a wxMenu object.
442 If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only).
447 Constructs a wxMenu object with a title.
450 Title at the top of the menu (not always supported).
452 If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only).
454 wxMenu(const wxString
& title
, long style
= 0);
457 Destructor, destroying the menu.
460 Under Motif, a popup menu must have a valid parent (the window
461 it was last popped up on) when being destroyed. Therefore, make sure
462 you delete or re-use the popup menu @e before destroying the parent
463 window. Re-use in this context means popping up the menu on a different
464 window from last time, which causes an implicit destruction and
465 recreation of internal data structures.
473 The menu command identifier.
475 The string to appear on the menu item.
477 An optional help string associated with the item.
478 By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays
479 this string in the status line.
481 May be wxITEM_SEPARATOR, wxITEM_NORMAL, wxITEM_CHECK or wxITEM_RADIO
484 This command can be used after the menu has been shown, as well as on
485 initial creation of a menu or menubar.
487 The item string for the normal menu items (not submenus or separators)
488 may include the accelerator which can be used to activate the menu item
490 The accelerator string follows the item label and is separated from it
491 by a TAB character ('\\t').
493 Its general syntax is any combination of "CTRL", "ALT" and "SHIFT" strings
494 (case doesn't matter) separated by either '-' or '+' characters and followed
495 by the accelerator itself.
496 The accelerator may be any alphanumeric character, any function key
497 (from F1 to F12) or one of the special characters listed in the table
498 below (again, case doesn't matter):
500 - DEL or DELETE: Delete key
501 - INS or INSERT: Insert key
502 - ENTER or RETURN: Enter key
505 - LEFT: Left cursor arrow key
506 - RIGHT: Right cursor arrow key
507 - UP: Up cursor arrow key
508 - DOWN: Down cursor arrow key
513 - ESC: or ESCAPE Escape key (Windows only)
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 @see Append(), InsertRadioItem()
582 wxMenuItem
* AppendRadioItem(int id
, const wxString
& item
,
583 const wxString
& help
= wxEmptyString
);
586 Adds a separator to the end of the menu.
588 @see Append(), InsertSeparator()
590 wxMenuItem
* AppendSeparator();
593 Adds the given @a submenu to this menu. @a text is the text shown in the
594 menu for it and @a help is the help string shown in the status bar when the
595 submenu item is selected.
597 wxMenuItem
* AppendSubMenu(wxMenu
* submenu
, const wxString
& text
,
598 const wxString
& help
= wxEmptyString
);
601 Inserts a break in a menu, causing the next appended item to appear in
604 virtual void Break();
607 Checks or unchecks the menu item.
610 The menu item identifier.
612 If @true, the item will be checked, otherwise it will be unchecked.
616 void Check(int id
, bool check
);
619 Deletes the menu item from the menu. If the item is a submenu, it will
620 @b not be deleted. Use Destroy() if you want to delete a submenu.
623 Id of the menu item to be deleted.
625 @see FindItem(), Destroy(), Remove()
630 Deletes the menu item from the menu. If the item is a submenu, it will
631 @b not be deleted. Use Destroy() if you want to delete a submenu.
634 Menu item to be deleted.
636 @see FindItem(), Destroy(), Remove()
638 bool Delete(wxMenuItem
* item
);
641 Deletes the menu item from the menu. If the item is a submenu, it will
642 be deleted. Use Remove() if you want to keep the submenu (for example,
646 Id of the menu item to be deleted.
648 @see FindItem(), Deletes(), Remove()
650 bool Destroy(int id
);
653 Deletes the menu item from the menu. If the item is a submenu, it will
654 be deleted. Use Remove() if you want to keep the submenu (for example,
658 Menu item to be deleted.
660 @see FindItem(), Deletes(), Remove()
662 bool Destroy(wxMenuItem
* item
);
665 Enables or disables (greys out) a menu item.
668 The menu item identifier.
670 @true to enable the menu item, @false to disable it.
674 void Enable(int id
, bool enable
);
677 Finds the menu id for a menu item string.
680 Menu item string to find.
682 @return Menu item identifier, or wxNOT_FOUND if none is found.
684 @remarks Any special menu codes are stripped out of source and target
685 strings before matching.
687 virtual int FindItem(const wxString
& itemString
) const;
690 Finds the menu item object associated with the given menu item identifier and,
691 optionally, the (sub)menu it belongs to.
694 Menu item identifier.
696 If the pointer is not @NULL, it will be filled with the item's
697 parent menu (if the item was found)
699 @return Menu item object or NULL if none is found.
701 wxMenuItem
* FindItem(int id
, wxMenu
** menu
= NULL
) const;
704 Returns the wxMenuItem given a position in the menu.
706 wxMenuItem
* FindItemByPosition(size_t position
) const;
709 Returns the help string associated with a menu item.
712 The menu item identifier.
714 @return The help string, or the empty string if there is no help string
715 or the item was not found.
717 @see SetHelpString(), Append()
719 virtual wxString
GetHelpString(int id
) const;
722 Returns a menu item label.
725 The menu item identifier.
727 @return The item label, or the empty string if the item was not found.
729 @see GetLabelText(), SetLabel()
731 wxString
GetLabel(int id
) const;
734 Returns a menu item label, without any of the original mnemonics and
738 The menu item identifier.
740 @return The item label, or the empty string if the item was not found.
742 @see GetLabel(), SetLabel()
744 wxString
GetLabelText(int id
) const;
747 Returns the number of items in the menu.
749 size_t GetMenuItemCount() const;
753 Returns the list of items in the menu.
755 wxMenuItemList is a pseudo-template list class containing wxMenuItem
756 pointers, see wxList.
758 wxMenuItemList
& GetMenuItems() const;
759 const wxMenuItemList
& GetMenuItems() const;
763 Returns the title of the menu.
765 @remarks This is relevant only to popup menus, use
766 wxMenuBar::GetMenuLabel for the menus in the menubar.
770 const wxString
& GetTitle() const;
773 Inserts the given @a item before the position @a pos.
775 Inserting the item at position GetMenuItemCount() is the same
778 @see Append(), Prepend()
780 wxMenuItem
* Insert(size_t pos
, wxMenuItem
* item
);
783 Inserts the given @a item before the position @a pos.
785 Inserting the item at position GetMenuItemCount() is the same
788 @see Append(), Prepend()
790 wxMenuItem
* Insert(size_t pos
, int id
,
791 const wxString
& item
= wxEmptyString
,
792 const wxString
& helpString
= wxEmptyString
,
793 wxItemKind kind
= wxITEM_NORMAL
);
796 Inserts a checkable item at the given position.
798 @see Insert(), AppendCheckItem()
800 wxMenuItem
* InsertCheckItem(size_t pos
, int id
, const wxString
& item
,
801 const wxString
& helpString
= wxEmptyString
);
804 Inserts a radio item at the given position.
806 @see Insert(), AppendRadioItem()
808 wxMenuItem
* InsertRadioItem(size_t pos
, int id
, const wxString
& item
,
809 const wxString
& helpString
= wxEmptyString
);
812 Inserts a separator at the given position.
814 @see Insert(), AppendSeparator()
816 wxMenuItem
* InsertSeparator(size_t pos
);
819 Determines whether a menu item is checked.
822 The menu item identifier.
824 @return @true if the menu item is checked, @false otherwise.
828 bool IsChecked(int id
) const;
831 Determines whether a menu item is enabled.
834 The menu item identifier.
836 @return @true if the menu item is enabled, @false otherwise.
840 bool IsEnabled(int id
) const;
843 Inserts the given @a item at position 0, i.e. before all the other
846 @see Append(), Insert()
848 wxMenuItem
* Prepend(wxMenuItem
* item
);
851 Inserts the given @a item at position 0, i.e. before all the other
854 @see Append(), Insert()
856 wxMenuItem
* Prepend(int id
, const wxString
& item
= wxEmptyString
,
857 const wxString
& helpString
= wxEmptyString
,
858 wxItemKind kind
= wxITEM_NORMAL
);
861 Inserts a checkable item at position 0.
863 @see Prepend(), AppendCheckItem()
865 wxMenuItem
* PrependCheckItem(int id
, const wxString
& item
,
866 const wxString
& helpString
= wxEmptyString
);
869 Inserts a radio item at position 0.
871 @see Prepend(), AppendRadioItem()
873 wxMenuItem
* PrependRadioItem(int id
, const wxString
& item
,
874 const wxString
& helpString
= wxEmptyString
);
877 Inserts a separator at position 0.
879 @see Prepend(), AppendSeparator()
881 wxMenuItem
* PrependSeparator();
884 Removes the menu item from the menu but doesn't delete the associated C++
885 object. This allows you to reuse the same item later by adding it back to
886 the menu (especially useful with submenus).
889 The identifier of the menu item to remove.
891 @return A pointer to the item which was detached from the menu.
893 wxMenuItem
* Remove(int id
);
896 Removes the menu item from the menu but doesn't delete the associated C++
897 object. This allows you to reuse the same item later by adding it back to
898 the menu (especially useful with submenus).
901 The menu item to remove.
903 @return A pointer to the item which was detached from the menu.
905 wxMenuItem
* Remove(wxMenuItem
* item
);
908 Sets an item's help string.
911 The menu item identifier.
913 The help string to set.
917 virtual void SetHelpString(int id
, const wxString
& helpString
);
920 Sets the label of a menu item.
923 The menu item identifier.
925 The menu item label to set.
927 @see Append(), GetLabel()
929 void SetLabel(int id
, const wxString
& label
);
932 Sets the title of the menu.
937 @remarks This is relevant only to popup menus, use
938 wxMenuBar::SetLabelTop for the menus in the menubar.
942 virtual void SetTitle(const wxString
& title
);
945 Sends events to @a source (or owning window if @NULL) to update the
948 This is called just before the menu is popped up with wxWindow::PopupMenu,
949 but the application may call it at other times if required.
951 void UpdateUI(wxEvtHandler
* source
= NULL
);