]>
git.saurik.com Git - wxWidgets.git/blob - interface/menu.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxMenuBar
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
13 A menu bar is a series of menus accessible from the top of a frame.
18 @see wxMenu, @ref overview_eventhandlingoverview
20 class wxMenuBar
: public wxWindow
24 Construct an empty menu barM
27 If wxMB_DOCKABLE the menu bar can be detached (wxGTK only).
29 wxMenuBar(long style
= 0);
32 Construct a menu bar from arrays of menus and titles.
37 An array of menus. Do not use this array again - it now belongs to
40 An array of title strings. Deallocate this array after creating
43 If wxMB_DOCKABLE the menu bar can be detached (wxGTK only).
45 wxMenuBar(size_t n
, wxMenu
* menus
[], const wxString titles
[],
49 Destructor, destroying the menu bar and removing it from the parent frame (if
55 Adds the item to the end of the menu bar.
58 The menu to add. Do not deallocate this menu after calling Append.
60 The title of the menu.
62 @return @true on success, @false if an error occurred.
66 bool Append(wxMenu
* menu
, const wxString
& title
);
69 Checks or unchecks a menu item.
72 The menu item identifier.
74 If @true, checks the menu item, otherwise the item is unchecked.
76 @remarks Only use this when the menu bar has been associated with a
77 frame; otherwise, use the wxMenu equivalent call.
79 void Check(int id
, const bool check
);
82 Enables or disables (greys out) a menu item.
85 The menu item identifier.
87 @true to enable the item, @false to disable it.
89 @remarks Only use this when the menu bar has been associated with a
90 frame; otherwise, use the wxMenu equivalent call.
92 void Enable(int id
, const bool enable
);
95 Enables or disables a whole menu.
98 The position of the menu, starting from zero.
100 @true to enable the menu, @false to disable it.
102 @remarks Only use this when the menu bar has been associated with a frame.
104 void EnableTop(int pos
, const bool enable
);
107 Finds the menu item object associated with the given menu item identifier.
110 Menu item identifier.
112 If not @NULL, menu will get set to the associated menu.
114 @return The found menu item object, or @NULL if one was not found.
116 wxMenuItem
* FindItem(int id
, wxMenu menu
= NULL
) const;
119 Returns the index of the menu with the given @a title or @c wxNOT_FOUND if no
120 such menu exists in this menubar. The @a title parameter may specify either
121 the menu title (with accelerator characters, i.e. @c "File") or just the
122 menu label (@c "File") indifferently.
124 int FindMenu(const wxString
& title
) const;
127 Finds the menu item id for a menu name/menu item string pair.
134 @return The menu item identifier, or wxNOT_FOUND if none was found.
136 @remarks Any special menu codes are stripped out of source and target
137 strings before matching.
139 int FindMenuItem(const wxString
& menuString
,
140 const wxString
& itemString
) const;
143 Gets the help string associated with the menu item identifier.
146 The menu item identifier.
148 @return The help string, or the empty string if there was no help string
149 or the menu item was not found.
153 wxString
GetHelpString(int id
) const;
156 Gets the label associated with a menu item.
159 The menu item identifier.
161 @return The menu item label, or the empty string if the item was not
164 @remarks Use only after the menubar has been associated with a frame.
166 wxString
GetLabel(int id
) const;
169 Returns the label of a top-level menu. Note that the returned string does not
170 include the accelerator characters which could have been specified in the menu
171 title string during its construction.
174 Position of the menu on the menu bar, starting from zero.
176 @return The menu label, or the empty string if the menu was not found.
178 @remarks Use only after the menubar has been associated with a frame.
182 wxString
GetLabelTop(int pos
) const;
185 Returns the menu at @a menuIndex (zero-based).
187 wxMenu
* GetMenu(int menuIndex
) const;
190 Returns the number of menus in this menubar.
192 size_t GetMenuCount() const;
195 Returns the label of a top-level menu. Note that the returned string
196 includes the accelerator characters that have been specified in the menu
197 title string during its construction.
200 Position of the menu on the menu bar, starting from zero.
202 @return The menu label, or the empty string if the menu was not found.
204 @remarks Use only after the menubar has been associated with a frame.
206 @see GetMenuLabelText(), SetMenuLabel()
208 wxString
GetMenuLabel(int pos
) const;
211 Returns the label of a top-level menu. Note that the returned string does not
212 include any accelerator characters that may have been specified in the menu
213 title string during its construction.
216 Position of the menu on the menu bar, starting from zero.
218 @return The menu label, or the empty string if the menu was not found.
220 @remarks Use only after the menubar has been associated with a frame.
222 @see GetMenuLabel(), SetMenuLabel()
224 wxString
GetMenuLabelText(int pos
) const;
227 Inserts the menu at the given position into the menu bar. Inserting menu at
228 position 0 will insert it in the very beginning of it, inserting at position
229 GetMenuCount() is the same as calling
233 The position of the new menu in the menu bar
235 The menu to add. wxMenuBar owns the menu and will free it.
237 The title of the menu.
239 @return @true on success, @false if an error occurred.
243 bool Insert(size_t pos
, wxMenu
* menu
, const wxString
& title
);
246 Determines whether an item is checked.
249 The menu item identifier.
251 @return @true if the item was found and is checked, @false otherwise.
253 bool IsChecked(int id
) const;
256 Determines whether an item is enabled.
259 The menu item identifier.
261 @return @true if the item was found and is enabled, @false otherwise.
263 bool IsEnabled(int id
) const;
271 Removes the menu from the menu bar and returns the menu object - the caller is
272 responsible for deleting it. This function may be used together with
273 Insert() to change the menubar
278 wxMenu
* Remove(size_t pos
);
281 Replaces the menu at the given position with another one.
284 The position of the new menu in the menu bar
288 The title of the menu.
290 @return The menu which was previously at position pos. The caller is
291 responsible for deleting it.
293 @see Insert(), Remove()
295 wxMenu
* Replace(size_t pos
, wxMenu
* menu
, const wxString
& title
);
298 Sets the help string associated with a menu item.
301 Menu item identifier.
303 Help string to associate with the menu item.
307 void SetHelpString(int id
, const wxString
& helpString
);
310 Sets the label of a menu item.
313 Menu item identifier.
317 @remarks Use only after the menubar has been associated with a frame.
321 void SetLabel(int id
, const wxString
& label
);
324 Sets the label of a top-level menu.
327 The position of a menu on the menu bar, starting from zero.
331 @remarks Use only after the menubar has been associated with a frame.
335 void SetLabelTop(int pos
, const wxString
& label
);
338 Sets the label of a top-level menu.
341 The position of a menu on the menu bar, starting from zero.
345 @remarks Use only after the menubar has been associated with a frame.
347 void SetMenuLabel(int pos
, const wxString
& label
);
356 A menu is a popup (or pull down) list of items, one of which may be
357 selected before the menu goes away (clicking elsewhere dismisses the
358 menu). Menus may be used to construct either menu bars or popup menus.
360 A menu item has an integer ID associated with it which can be used to
361 identify the selection, or to change the menu item in some way. A menu item
362 with a special identifier -1 is a separator item and doesn't have an
363 associated command but just makes a separator line appear in the menu.
365 @note Please note that @e wxID_ABOUT and @e wxID_EXIT are
366 predefined by wxWidgets and have a special meaning since entries
367 using these IDs will be taken out of the normal menus under MacOS X
368 and will be inserted into the system menu (following the appropriate
369 MacOS X interface guideline). On PalmOS @e wxID_EXIT is disabled according
370 to Palm OS Companion guidelines.
372 Menu items may be either normal items, check items or radio items. Normal items
373 don't have any special properties while the check items have a boolean flag
374 associated to them and they show a checkmark in the menu when the flag is set.
375 wxWidgets automatically toggles the flag value when the item is clicked and its
376 value may be retrieved using either wxMenu::IsChecked method
377 of wxMenu or wxMenuBar itself or by using
378 wxEvent::IsChecked when you get the menu
379 notification for the item in question.
381 The radio items are similar to the check items except that all the other items
382 in the same radio group are unchecked when a radio item is checked. The radio
383 group is formed by a contiguous range of radio items, i.e. it starts at the
384 first item of this kind and ends with the first item of a different kind (or
385 the end of the menu). Notice that because the radio groups are defined in terms
386 of the item positions inserting or removing the items in the menu containing
387 the radio items risks to not work correctly. Finally note that radio items
388 are not supported under Motif.
393 @see wxMenuBar, wxWindow::PopupMenu, @ref overview_eventhandlingoverview, @ref
394 overview_wxfilehistory "wxFileHistory (most recently used files menu)"
396 class wxMenu
: public wxEvtHandler
400 Constructs a wxMenu object.
403 If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only).
408 Constructs a wxMenu object with a title
411 Title at the top of the menu (not always supported).
413 If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only).
415 wxMenu(const wxString
& title
= "", long style
= 0);
418 Destructor, destroying the menu.
419 Note: under Motif, a popup menu must have a valid parent (the window
420 it was last popped up on) when being destroyed. Therefore, make sure
421 you delete or re-use the popup menu @e before destroying the
422 parent window. Re-use in this context means popping up the menu on
423 a different window from last time, which causes an implicit destruction
424 and recreation of internal data structures.
432 The menu command identifier.
434 The string to appear on the menu item.
436 May be wxITEM_SEPARATOR, wxITEM_NORMAL,
437 wxITEM_CHECK or wxITEM_RADIO
439 An optional help string associated with the item.
440 By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays
441 this string in the status line.
443 @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
444 AppendSubMenu(), Insert(), SetLabel(),
445 GetHelpString(), SetHelpString(), wxMenuItem
447 wxMenuItem
* Append(int id
, const wxString
& item
= "",
448 const wxString
& helpString
= "",
449 wxItemKind kind
= wxITEM_NORMAL
);
455 The menu command identifier.
457 The string to appear on the menu item.
461 An optional help string associated with the item.
462 By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays
463 this string in the status line.
465 @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
466 AppendSubMenu(), Insert(), SetLabel(),
467 GetHelpString(), SetHelpString(), wxMenuItem
469 wxMenuItem
* Append(int id
, const wxString
& item
,
471 const wxString
& helpString
= "");
474 Adds a menu item object. This is the most generic variant of Append() method
475 because it may be used for both items (including separators) and submenus and
476 because you can also specify various extra properties of a menu item this way,
477 such as bitmaps and fonts.
480 A menuitem object. It will be owned by the wxMenu object after this function
481 is called, so do not delete it yourself.
483 @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
484 AppendSubMenu(), Insert(), SetLabel(),
485 GetHelpString(), SetHelpString(), wxMenuItem
487 wxMenuItem
* Append(wxMenuItem
* menuItem
);
490 Adds a checkable item to the end of the menu.
492 @see Append(), InsertCheckItem()
494 wxMenuItem
* AppendCheckItem(int id
, const wxString
& item
,
495 const wxString
& helpString
= "");
498 Adds a radio item to the end of the menu. All consequent radio items form a
499 group and when an item in the group is checked, all the others are
500 automatically unchecked.
502 @see Append(), InsertRadioItem()
504 wxMenuItem
* AppendRadioItem(int id
, const wxString
& item
,
505 const wxString
& helpString
= "");
508 Adds a separator to the end of the menu.
510 @see Append(), InsertSeparator()
512 wxMenuItem
* AppendSeparator();
515 Adds the given @a submenu to this menu. @a text is the text shown in the
516 menu for it and @a help is the help string shown in the status bar when the
517 submenu item is selected.
519 wxMenuItem
* AppendSubMenu(wxMenu
* submenu
, const wxString
& text
,
520 const wxString
& help
= wxEmptyString
);
523 Inserts a break in a menu, causing the next appended item to appear in a new
529 Checks or unchecks the menu item.
532 The menu item identifier.
534 If @true, the item will be checked, otherwise it will be unchecked.
538 void Check(int id
, const bool check
);
541 Deletes the menu item from the menu. If the item is a submenu, it will
542 @b not be deleted. Use Destroy() if you want to delete a submenu.
545 Id of the menu item to be deleted.
547 @see FindItem(), Destroy(), Remove()
552 Deletes the menu item from the menu. If the item is a submenu, it will
553 @b not be deleted. Use Destroy() if you want to delete a submenu.
556 Menu item to be deleted.
558 @see FindItem(), Destroy(), Remove()
560 void Delete(wxMenuItem
* item
);
563 Deletes the menu item from the menu. If the item is a submenu, it will
564 be deleted. Use Remove() if you want to keep the submenu (for example,
568 Id of the menu item to be deleted.
570 @see FindItem(), Deletes(), Remove()
572 void Destroy(int id
);
575 Deletes the menu item from the menu. If the item is a submenu, it will
576 be deleted. Use Remove() if you want to keep the submenu (for example,
580 Menu item to be deleted.
582 @see FindItem(), Deletes(), Remove()
584 void Destroy(wxMenuItem
* item
);
587 Enables or disables (greys out) a menu item.
590 The menu item identifier.
592 @true to enable the menu item, @false to disable it.
596 void Enable(int id
, const bool enable
);
599 Finds the menu id for a menu item string.
602 Menu item string to find.
604 @return Menu item identifier, or wxNOT_FOUND if none is found.
606 @remarks Any special menu codes are stripped out of source and target
607 strings before matching.
609 int FindItem(const wxString
& itemString
) const;
612 Finds the menu item object associated with the given menu item identifier and,
613 optionally, the (sub)menu it belongs to.
616 Menu item identifier.
618 If the pointer is not @NULL, it will be filled with the item's
619 parent menu (if the item was found)
621 @return Menu item object or NULL if none is found.
623 const wxMenuItem
* FindItem(int id
, wxMenu
** menu
= NULL
) const;
626 Returns the wxMenuItem given a position in the menu.
628 wxMenuItem
* FindItemByPosition(size_t position
) const;
631 Returns the help string associated with a menu item.
634 The menu item identifier.
636 @return The help string, or the empty string if there is no help string
637 or the item was not found.
639 @see SetHelpString(), Append()
641 wxString
GetHelpString(int id
) const;
644 Returns a menu item label.
647 The menu item identifier.
649 @return The item label, or the empty string if the item was not found.
651 @see GetLabelText(), SetLabel()
653 wxString
GetLabel(int id
) const;
656 Returns a menu item label, without any of the original mnemonics and
660 The menu item identifier.
662 @return The item label, or the empty string if the item was not found.
664 @see GetLabel(), SetLabel()
666 wxString
GetLabelText(int id
) const;
669 Returns the number of items in the menu.
671 size_t GetMenuItemCount() const;
674 Returns the list of items in the menu. wxMenuItemList is a pseudo-template
675 list class containing wxMenuItem pointers, see wxList.
677 wxMenuItemList
GetMenuItems() const;
680 Returns the title of the menu.
682 @remarks This is relevant only to popup menus, use
683 wxMenuBar::GetMenuLabel for the menus in the menubar.
687 wxString
GetTitle() const;
690 Inserts the given @a item before the position @e pos. Inserting the item
691 at position GetMenuItemCount() is the same
694 @see Append(), Prepend()
696 wxMenuItem
* Insert(size_t pos
, wxMenuItem
* item
);
699 Inserts the given @a item before the position @e pos. Inserting the item
700 at position GetMenuItemCount() is the same
703 @see Append(), Prepend()
705 wxMenuItem
* Insert(size_t pos
, int id
,
706 const wxString
& item
= "",
707 const wxString
& helpString
= "",
708 wxItemKind kind
= wxITEM_NORMAL
);
711 Inserts a checkable item at the given position.
713 @see Insert(), AppendCheckItem()
715 wxMenuItem
* InsertCheckItem(size_t pos
, int id
,
716 const wxString
& item
,
717 const wxString
& helpString
= "");
720 Inserts a radio item at the given position.
722 @see Insert(), AppendRadioItem()
724 wxMenuItem
* InsertRadioItem(size_t pos
, int id
,
725 const wxString
& item
,
726 const wxString
& helpString
= "");
729 Inserts a separator at the given position.
731 @see Insert(), AppendSeparator()
733 wxMenuItem
* InsertSeparator(size_t pos
);
736 Determines whether a menu item is checked.
739 The menu item identifier.
741 @return @true if the menu item is checked, @false otherwise.
745 bool IsChecked(int id
) const;
748 Determines whether a menu item is enabled.
751 The menu item identifier.
753 @return @true if the menu item is enabled, @false otherwise.
757 bool IsEnabled(int id
) const;
760 Inserts the given @a item at position 0, i.e. before all the other
763 @see Append(), Insert()
765 wxMenuItem
* Prepend(wxMenuItem
* item
);
768 Inserts the given @a item at position 0, i.e. before all the other
771 @see Append(), Insert()
773 wxMenuItem
* Prepend(int id
, const wxString
& item
= "",
774 const wxString
& helpString
= "",
775 wxItemKind kind
= wxITEM_NORMAL
);
778 Inserts a checkable item at position 0.
780 @see Prepend(), AppendCheckItem()
782 wxMenuItem
* PrependCheckItem(int id
, const wxString
& item
,
783 const wxString
& helpString
= "");
786 Inserts a radio item at position 0.
788 @see Prepend(), AppendRadioItem()
790 wxMenuItem
* PrependRadioItem(int id
, const wxString
& item
,
791 const wxString
& helpString
= "");
794 Inserts a separator at position 0.
796 @see Prepend(), AppendSeparator()
798 wxMenuItem
* PrependSeparator();
801 Removes the menu item from the menu but doesn't delete the associated C++
802 object. This allows to reuse the same item later by adding it back to the menu
803 (especially useful with submenus).
806 The identifier of the menu item to remove.
808 @return The item which was detached from the menu.
810 wxMenuItem
* Remove(int id
);
813 Removes the menu item from the menu but doesn't delete the associated C++
814 object. This allows to reuse the same item later by adding it back to the menu
815 (especially useful with submenus).
818 The menu item to remove.
820 @return The item which was detached from the menu.
822 wxMenuItem
* Remove(wxMenuItem
* item
);
825 Sets an item's help string.
828 The menu item identifier.
830 The help string to set.
834 void SetHelpString(int id
, const wxString
& helpString
);
837 Sets the label of a menu item.
840 The menu item identifier.
842 The menu item label to set.
844 @see Append(), GetLabel()
846 void SetLabel(int id
, const wxString
& label
);
849 Sets the title of the menu.
854 @remarks This is relevant only to popup menus, use
855 wxMenuBar::SetLabelTop for the menus in the menubar.
859 void SetTitle(const wxString
& title
);
862 Sends events to @a source (or owning window if @NULL) to update the
863 menu UI. This is called just before the menu is popped up with
864 wxWindow::PopupMenu, but
865 the application may call it at other times if required.
867 void UpdateUI(wxEvtHandler
* source
= NULL
) const;