X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e12be2f7fb5f55553795b7c4168007173511d581..3cc305b2b4a0674c56c84d7088cfd70676b850f0:/docs/latex/wx/menu.tex diff --git a/docs/latex/wx/menu.tex b/docs/latex/wx/menu.tex index 85add9a582..824d341009 100644 --- a/docs/latex/wx/menu.tex +++ b/docs/latex/wx/menu.tex @@ -1,11 +1,56 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% Name: menu.tex +%% Purpose: wxMenu documentation +%% Author: wxWidgets Team +%% Modified by: +%% Created: +%% RCS-ID: $Id$ +%% Copyright: (c) wxWidgets Team +%% License: wxWindows license +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + \section{\class{wxMenu}}\label{wxmenu} A menu is a popup (or pull down) list of items, one of which may be selected before the menu goes away (clicking elsewhere dismisses the -menu). Menus may be used to construct either menu bars or popup menus. +menu). Menus may be used to construct either menu bars or popup menus. A menu item has an integer ID associated with it which can be used to -identify the selection, or to change the menu item in some way. +identify the selection, or to change the menu item in some way. A menu item +with a special identifier $-1$ is a separator item and doesn't have an +associated command but just makes a separator line appear in the menu. + +{\bf NB:} Please note that {\it wxID\_ABOUT} and {\it wxID\_EXIT} are +predefined by wxWidgets and have a special meaning since entries +using these IDs will be taken out of the normal menus under MacOS X +and will be inserted into the system menu (following the appropriate +MacOS X interface guideline). On PalmOS {\it wxID\_EXIT} is disabled according +to Palm OS Companion guidelines. + +Menu items may be either normal items, check items or radio items. Normal items +don't have any special properties while the check items have a boolean flag +associated to them and they show a checkmark in the menu when the flag is set. +wxWidgets automatically toggles the flag value when the item is clicked and its +value may be retrieved using either \helpref{IsChecked}{wxmenuischecked} method +of wxMenu or wxMenuBar itself or by using +\helpref{wxEvent::IsChecked}{wxcommandeventischecked} when you get the menu +notification for the item in question. + +The radio items are similar to the check items except that all the other items +in the same radio group are unchecked when a radio item is checked. The radio +group is formed by a contiguous range of radio items, i.e. it starts at the +first item of this kind and ends with the first item of a different kind (or +the end of the menu). Notice that because the radio groups are defined in terms +of the item positions inserting or removing the items in the menu containing +the radio items risks to not work correctly. Finally note that radio items +are not supported under Motif. + +\wxheading{Allocation strategy} + +All menus except the popup ones must be created on the heap. All menus +attached to a menubar or to another menu will be deleted by their parent when +it is deleted. As the frame menubar is deleted by the frame itself, it means +that normally all menus used are deleted automatically. \wxheading{Derived from} @@ -16,6 +61,10 @@ identify the selection, or to change the menu item in some way. +\wxheading{Library} + +\helpref{wxCore}{librarieslist} + \wxheading{Event handling} If the menu is part of a menubar, then \helpref{wxMenuBar}{wxmenubar} event processing is used. @@ -28,20 +77,20 @@ With a popup menu, there is a variety of ways to handle a menu selection event \item Set a new event handler for wxMenu, using an object whose class has EVT\_MENU entries. \item Provide EVT\_MENU handlers in the window which pops up the menu, or in an ancestor of this window. -\item Define a callback of type wxFunction, which you pass to the wxMenu constructor. -The callback takes a reference to the menu, and a reference to a -\helpref{wxCommandEvent}{wxcommandevent}. This method is deprecated and should -not be used in the new code, it is provided for backwards compatibility only. \end{enumerate} \wxheading{See also} \helpref{wxMenuBar}{wxmenubar}, \helpref{wxWindow::PopupMenu}{wxwindowpopupmenu},\rtfsp -\helpref{Event handling overview}{eventhandlingoverview} +\helpref{Event handling overview}{eventhandlingoverview},\rtfsp +\helpref{wxFileHistory (most recently used files menu)}{wxfilehistory} + + \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxMenu::wxMenu}\label{wxmenuconstr} + +\membersection{wxMenu::wxMenu}\label{wxmenuctor} \func{}{wxMenu}{\param{const wxString\& }{title = ""}, \param{long}{ style = 0}} @@ -51,7 +100,7 @@ Constructs a wxMenu object. \docparam{title}{A title for the popup menu: the empty string denotes no title.} -\docparam{style}{If set to {\tt wxMENU\_TEAROFF}, the menu will be detachable.} +\docparam{style}{If set to {\tt wxMENU\_TEAROFF}, the menu will be detachable (wxGTK only).} \func{}{wxMenu}{\param{long}{ style}} @@ -59,9 +108,10 @@ Constructs a wxMenu object. \wxheading{Parameters} -\docparam{style}{If set to {\tt wxMENU\_TEAROFF}, the menu will be detachable.} +\docparam{style}{If set to {\tt wxMENU\_TEAROFF}, the menu will be detachable (wxGTK only).} + -\membersection{wxMenu::\destruct{wxMenu}} +\membersection{wxMenu::\destruct{wxMenu}}\label{wxmenudtor} \func{}{\destruct{wxMenu}}{\void} @@ -74,19 +124,22 @@ parent window. Re-use in this context means popping up the menu on a different window from last time, which causes an implicit destruction and recreation of internal data structures. + \membersection{wxMenu::Append}\label{wxmenuappend} -\func{void}{Append}{\param{int}{ id}, \param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""},\rtfsp -\param{const bool}{ checkable = FALSE}} +\func{wxMenuItem*}{Append}{\param{int}{ id}, \param{const wxString\& }{ item = ""}, \param{const wxString\& }{helpString = ""},\rtfsp +\param{wxItemKind}{ kind = wxITEM\_NORMAL}} Adds a string item to the end of the menu. -\func{void}{Append}{\param{int}{ id}, \param{const wxString\& }{ item}, \param{wxMenu *}{subMenu},\rtfsp +\func{wxMenuItem*}{Append}{\param{int}{ id}, \param{const wxString\& }{ item}, \param{wxMenu *}{subMenu},\rtfsp \param{const wxString\& }{helpString = ""}} -Adds a pull-right submenu to the end of the menu. +Adds a pull-right submenu to the end of the menu. Append the submenu to the parent +menu {\it after} you have added your menu items, or accelerators may not be +registered properly. -\func{void}{Append}{\param{wxMenuItem*}{ menuItem}} +\func{wxMenuItem*}{Append}{\param{wxMenuItem*}{ menuItem}} Adds a menu item object. This is the most generic variant of Append() method because it may be used for both items (including separators) and submenus and @@ -101,10 +154,11 @@ such as bitmaps and fonts. \docparam{menu}{Pull-right submenu.} -\docparam{checkable}{If TRUE, this item is checkable.} +\docparam{kind}{May be {\tt wxITEM\_SEPARATOR}, {\tt wxITEM\_NORMAL}, +{\tt wxITEM\_CHECK} or {\tt wxITEM\_RADIO}} \docparam{helpString}{An optional help string associated with the item. -By default, \helpref{wxFrame::OnMenuHighlight}{wxframeonmenuhighlight} displays +By default, the handler for the wxEVT\_MENU\_HIGHLIGHT event displays this string in the status line.} \docparam{menuItem}{A menuitem object. It will be owned by the wxMenu object after this function @@ -115,31 +169,102 @@ is called, so do not delete it yourself.} This command can be used after the menu has been shown, as well as on initial creation of a menu or menubar. +The {\it item} string for the normal menu items (not submenus or separators) +may include the accelerator which can be used to activate the menu item +from keyboard. The accelerator string follows the item label and is separated +from it by a {\tt TAB} character ({\tt '$\backslash$t'}). Its general syntax is +any combination of {\tt "CTRL"}, {\tt "ALT"} and {\tt "SHIFT"} strings (case +doesn't matter) separated by either {\tt '-'} or {\tt '+'} characters and +followed by the accelerator itself. The accelerator may be any alphanumeric +character, any function key (from {\tt F1} to {\tt F12}) or one of the special +characters listed in the table below (again, case doesn't matter): + +\begin{twocollist}\itemsep=0pt +\twocolitem{{\tt DEL} or {\tt DELETE}}{Delete key} +\twocolitem{{\tt INS} or {\tt INSERT}}{Insert key} +\twocolitem{{\tt ENTER} or {\tt RETURN}}{Enter key} +\twocolitem{{\tt PGUP}}{PageUp key} +\twocolitem{{\tt PGDN}}{PageDown key} +\twocolitem{{\tt LEFT}}{Left cursor arrow key} +\twocolitem{{\tt RIGHT}}{Right cursor arrow key} +\twocolitem{{\tt UP}}{Up cursor arrow key} +\twocolitem{{\tt DOWN}}{Down cursor arrow key} +\twocolitem{{\tt HOME}}{Home key} +\twocolitem{{\tt END}}{End key} +\twocolitem{{\tt SPACE}}{Space} +\twocolitem{{\tt TAB}}{Tab key} +\twocolitem{{\tt ESC} or {\tt ESCAPE}}{Escape key (Windows only)} +\end{twocollist} + \wxheading{See also} \helpref{wxMenu::AppendSeparator}{wxmenuappendseparator},\rtfsp +\helpref{wxMenu::AppendCheckItem}{wxmenuappendcheckitem},\rtfsp +\helpref{wxMenu::AppendRadioItem}{wxmenuappendradioitem},\rtfsp +\helpref{wxMenu::AppendSubMenu}{wxmenuappendsubmenu},\rtfsp \helpref{wxMenu::Insert}{wxmenuinsert},\rtfsp \helpref{wxMenu::SetLabel}{wxmenusetlabel}, \helpref{wxMenu::GetHelpString}{wxmenugethelpstring},\rtfsp \helpref{wxMenu::SetHelpString}{wxmenusethelpstring}, \helpref{wxMenuItem}{wxmenuitem} \pythonnote{In place of a single overloaded method name, wxPython -implements the following methods:\par +implements the following methods: + \indented{2cm}{\begin{twocollist} -\twocolitem{{\bf Append(id, string, helpStr="", checkable=FALSE)}}{} +\twocolitem{{\bf Append(id, string, helpStr="", checkable=false)}}{} \twocolitem{{\bf AppendMenu(id, string, aMenu, helpStr="")}}{} \twocolitem{{\bf AppendItem(aMenuItem)}}{} \end{twocollist}} } + +\membersection{wxMenu::AppendCheckItem}\label{wxmenuappendcheckitem} + +\func{wxMenuItem*}{AppendCheckItem}{\param{int}{ id},\rtfsp +\param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""}} + +Adds a checkable item to the end of the menu. + +\wxheading{See also} + +\helpref{wxMenu::Append}{wxmenuappend},\rtfsp +\helpref{wxMenu::InsertCheckItem}{wxmenuinsertcheckitem} + + +\membersection{wxMenu::AppendRadioItem}\label{wxmenuappendradioitem} + +\func{wxMenuItem*}{AppendRadioItem}{\param{int}{ id},\rtfsp +\param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""}} + +Adds a radio item to the end of the menu. All consequent radio items form a +group and when an item in the group is checked, all the others are +automatically unchecked. + +\wxheading{See also} + +\helpref{wxMenu::Append}{wxmenuappend},\rtfsp +\helpref{wxMenu::InsertRadioItem}{wxmenuinsertradioitem} + + \membersection{wxMenu::AppendSeparator}\label{wxmenuappendseparator} -\func{void}{AppendSeparator}{\void} +\func{wxMenuItem*}{AppendSeparator}{\void} Adds a separator to the end of the menu. \wxheading{See also} -\helpref{wxMenu::Append}{wxmenuappend} +\helpref{wxMenu::Append}{wxmenuappend},\rtfsp +\helpref{wxMenu::InsertSeparator}{wxmenuinsertseparator} + + +\membersection{wxMenu::AppendSubMenu}\label{wxmenuappendsubmenu} + +\func{wxMenuItem *}{AppendSubMenu}{\param{wxMenu *}{submenu}, \param{const wxString\& }{text}, \param{const wxString\& }{help = wxEmptyString}} + +Adds the given \arg{submenu} to this menu. \arg{text} is the text shown in the +menu for it and \arg{help} is the help string shown in the status bar when the +submenu item is selected. + \membersection{wxMenu::Break}\label{wxmenubreak} @@ -147,6 +272,7 @@ Adds a separator to the end of the menu. Inserts a break in a menu, causing the next appended item to appear in a new column. + \membersection{wxMenu::Check}\label{wxmenucheck} \func{void}{Check}{\param{int}{ id}, \param{const bool}{ check}} @@ -157,12 +283,13 @@ Checks or unchecks the menu item. \docparam{id}{The menu item identifier.} -\docparam{check}{If TRUE, the item will be checked, otherwise it will be unchecked.} +\docparam{check}{If true, the item will be checked, otherwise it will be unchecked.} \wxheading{See also} \helpref{wxMenu::IsChecked}{wxmenuischecked} + \membersection{wxMenu::Delete}\label{wxmenudelete} \func{void}{Delete}{\param{int }{id}} @@ -185,6 +312,7 @@ delete a submenu. \helpref{wxMenu::Destroy}{wxmenudestroy},\rtfsp \helpref{wxMenu::Remove}{wxmenuremove} + \membersection{wxMenu::Destroy}\label{wxmenudestroy} \func{void}{Destroy}{\param{int }{id}} @@ -207,6 +335,7 @@ be deleted. Use \helpref{Remove}{wxmenuremove} if you want to keep the submenu \helpref{wxMenu::Deletes}{wxmenudelete},\rtfsp \helpref{wxMenu::Remove}{wxmenuremove} + \membersection{wxMenu::Enable}\label{wxmenuenable} \func{void}{Enable}{\param{int}{ id}, \param{const bool}{ enable}} @@ -217,12 +346,13 @@ Enables or disables (greys out) a menu item. \docparam{id}{The menu item identifier.} -\docparam{enable}{TRUE to enable the menu item, FALSE to disable it.} +\docparam{enable}{true to enable the menu item, false to disable it.} \wxheading{See also} \helpref{wxMenu::IsEnabled}{wxmenuisenabled} + \membersection{wxMenu::FindItem}\label{wxmenufinditem} \constfunc{int}{FindItem}{\param{const wxString\& }{itemString}} @@ -234,18 +364,22 @@ Finds the menu item id for a menu item string. Finds the menu item object associated with the given menu item identifier and, optionally, the (sub)menu it belongs to. +\perlnote{In wxPerl this method takes just the {\tt id} parameter; +in scalar context it returns the associated {\tt Wx::MenuItem}, in list +context it returns a 2-element list {\tt ( item, submenu )}} + \wxheading{Parameters} \docparam{itemString}{Menu item string to find.} \docparam{id}{Menu item identifier.} -\docparam{menu}{If the pointer is not NULL, it will be filled with the items +\docparam{menu}{If the pointer is not NULL, it will be filled with the item's parent menu (if the item was found)} \wxheading{Return value} -First form: menu item identifier, or wxNOT\_FOUND if none is found. +First form: menu item identifier, or {\tt wxNOT\_FOUND} if none is found. Second form: returns the menu item object, or NULL if it is not found. @@ -254,9 +388,17 @@ Second form: returns the menu item object, or NULL if it is not found. Any special menu codes are stripped out of source and target strings before matching. -\pythonnote{The name of this method in wxPython is {\tt FindItemById} +\pythonnote{The name of this method in wxPython is {\tt FindItemById} and it does not support the second parameter.} + +\membersection{wxMenu::FindItemByPosition}\label{wxmenufinditembyposition} + +\constfunc{wxMenuItem*}{FindItemByPosition}{\param{size\_t }{position}} + +Returns the wxMenuItem given a position in the menu. + + \membersection{wxMenu::GetHelpString}\label{wxmenugethelpstring} \constfunc{wxString}{GetHelpString}{\param{int}{ id}} @@ -276,6 +418,7 @@ item was not found. \helpref{wxMenu::SetHelpString}{wxmenusethelpstring}, \helpref{wxMenu::Append}{wxmenuappend} + \membersection{wxMenu::GetLabel}\label{wxmenugetlabel} \constfunc{wxString}{GetLabel}{\param{int}{ id}} @@ -292,7 +435,26 @@ The item label, or the empty string if the item was not found. \wxheading{See also} -\helpref{wxMenu::SetLabel}{wxmenusetlabel} +\helpref{wxMenu::GetLabelText}{wxmenugetlabeltext}, \helpref{wxMenu::SetLabel}{wxmenusetlabel} + + +\membersection{wxMenu::GetLabelText}\label{wxmenugetlabeltext} + +\constfunc{wxString}{GetLabelText}{\param{int}{ id}} + +Returns a menu item label, without any of the original mnemonics and accelerators. + +\wxheading{Parameters} + +\docparam{id}{The menu item identifier.} + +\wxheading{Return value} + +The item label, or the empty string if the item was not found. + +\wxheading{See also} + +\helpref{wxMenu::GetLabel}{wxmenugetlabel}, \helpref{wxMenu::SetLabel}{wxmenusetlabel} \membersection{wxMenu::GetMenuItemCount}\label{wxmenugetmenuitemcount} @@ -300,12 +462,14 @@ The item label, or the empty string if the item was not found. Returns the number of items in the menu. + \membersection{wxMenu::GetMenuItems}\label{wxmenugetmenuitems} \constfunc{wxMenuItemList\&}{GetMenuItems}{\void} Returns the list of items in the menu. wxMenuItemList is a pseudo-template -list class containing wxMenuItem pointers. +list class containing wxMenuItem pointers, see \helpref{wxList}{wxlist}. + \membersection{wxMenu::GetTitle}\label{wxmenugettitle} @@ -315,23 +479,70 @@ Returns the title of the menu. \wxheading{Remarks} -This is relevant only to popup menus. +This is relevant only to popup menus, use +\helpref{wxMenuBar::GetMenuLabel}{wxmenubargetmenulabel} for the menus in the +menubar. \wxheading{See also} \helpref{wxMenu::SetTitle}{wxmenusettitle} + \membersection{wxMenu::Insert}\label{wxmenuinsert} -\func{bool}{Insert}{\param{size\_t }{pos}, \param{wxMenuItem *}{item}} +\func{wxMenuItem*}{Insert}{\param{size\_t }{pos}, \param{wxMenuItem *}{item}} + +\func{wxMenuItem*}{Insert}{\param{size\_t }{pos}, \param{int}{ id},\rtfsp +\param{const wxString\& }{ item = ""}, \param{const wxString\& }{helpString = ""},\rtfsp +\param{wxItemKind}{ kind = wxITEM\_NORMAL}} Inserts the given {\it item} before the position {\it pos}. Inserting the item -at the position \helpref{GetMenuItemCount}{wxmenugetmenuitemcount} is the same +at position \helpref{GetMenuItemCount}{wxmenugetmenuitemcount} is the same as appending it. \wxheading{See also} -\helpref{wxMenu::Append}{wxmenuappend} +\helpref{wxMenu::Append}{wxmenuappend},\rtfsp +\helpref{wxMenu::Prepend}{wxmenuprepend} + + +\membersection{wxMenu::InsertCheckItem}\label{wxmenuinsertcheckitem} + +\func{wxMenuItem*}{InsertCheckItem}{\param{size\_t }{pos}, \param{int}{ id},\rtfsp +\param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""}} + +Inserts a checkable item at the given position. + +\wxheading{See also} + +\helpref{wxMenu::Insert}{wxmenuinsert},\rtfsp +\helpref{wxMenu::AppendCheckItem}{wxmenuappendcheckitem} + + +\membersection{wxMenu::InsertRadioItem}\label{wxmenuinsertradioitem} + +\func{wxMenuItem*}{InsertRadioItem}{\param{size\_t }{pos}, \param{int}{ id},\rtfsp +\param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""}} + +Inserts a radio item at the given position. + +\wxheading{See also} + +\helpref{wxMenu::Insert}{wxmenuinsert},\rtfsp +\helpref{wxMenu::AppendRadioItem}{wxmenuappendradioitem} + + +\membersection{wxMenu::InsertSeparator}\label{wxmenuinsertseparator} + +\func{wxMenuItem*}{InsertSeparator}{\param{size\_t }{pos}} + +Inserts a separator at the given position. + +\wxheading{See also} + +\helpref{wxMenu::Insert}{wxmenuinsert},\rtfsp +\helpref{wxMenu::AppendSeparator}{wxmenuappendseparator} + \membersection{wxMenu::IsChecked}\label{wxmenuischecked} @@ -345,12 +556,13 @@ Determines whether a menu item is checked. \wxheading{Return value} -TRUE if the menu item is checked, FALSE otherwise. +true if the menu item is checked, false otherwise. \wxheading{See also} \helpref{wxMenu::Check}{wxmenucheck} + \membersection{wxMenu::IsEnabled}\label{wxmenuisenabled} \constfunc{bool}{IsEnabled}{\param{int}{ id}} @@ -363,12 +575,68 @@ Determines whether a menu item is enabled. \wxheading{Return value} -TRUE if the menu item is enabled, FALSE otherwise. +true if the menu item is enabled, false otherwise. \wxheading{See also} \helpref{wxMenu::Enable}{wxmenuenable} + +\membersection{wxMenu::Prepend}\label{wxmenuprepend} + +\func{wxMenuItem*}{Prepend}{\param{wxMenuItem *}{item}} + +\func{wxMenuItem*}{Prepend}{\param{int}{ id},\rtfsp +\param{const wxString\& }{ item = ""}, \param{const wxString\& }{helpString = ""},\rtfsp +\param{wxItemKind}{ kind = wxITEM\_NORMAL}} + +Inserts the given {\it item} at position $0$, i.e. before all the other +existing items. + +\wxheading{See also} + +\helpref{wxMenu::Append}{wxmenuappend},\rtfsp +\helpref{wxMenu::Insert}{wxmenuinsert} + + +\membersection{wxMenu::PrependCheckItem}\label{wxmenuprependcheckitem} + +\func{wxMenuItem*}{PrependCheckItem}{\param{int}{ id},\rtfsp +\param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""}} + +Inserts a checkable item at position $0$. + +\wxheading{See also} + +\helpref{wxMenu::Prepend}{wxmenuprepend},\rtfsp +\helpref{wxMenu::AppendCheckItem}{wxmenuappendcheckitem} + + +\membersection{wxMenu::PrependRadioItem}\label{wxmenuprependradioitem} + +\func{wxMenuItem*}{PrependRadioItem}{\param{int}{ id},\rtfsp +\param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""}} + +Inserts a radio item at position $0$. + +\wxheading{See also} + +\helpref{wxMenu::Prepend}{wxmenuprepend},\rtfsp +\helpref{wxMenu::AppendRadioItem}{wxmenuappendradioitem} + + +\membersection{wxMenu::PrependSeparator}\label{wxmenuprependseparator} + +\func{wxMenuItem*}{PrependSeparator}{\void} + +Inserts a separator at position $0$. + +\wxheading{See also} + +\helpref{wxMenu::Prepend}{wxmenuprepend},\rtfsp +\helpref{wxMenu::AppendSeparator}{wxmenuappendseparator} + + \membersection{wxMenu::Remove}\label{wxmenuremove} \func{wxMenuItem *}{Remove}{\param{int }{id}} @@ -389,6 +657,7 @@ object. This allows to reuse the same item later by adding it back to the menu The item which was detached from the menu. + \membersection{wxMenu::SetHelpString}\label{wxmenusethelpstring} \func{void}{SetHelpString}{\param{int}{ id}, \param{const wxString\& }{helpString}} @@ -405,6 +674,7 @@ Sets an item's help string. \helpref{wxMenu::GetHelpString}{wxmenugethelpstring} + \membersection{wxMenu::SetLabel}\label{wxmenusetlabel} \func{void}{SetLabel}{\param{int}{ id}, \param{const wxString\& }{label}} @@ -421,6 +691,7 @@ Sets the label of a menu item. \helpref{wxMenu::Append}{wxmenuappend}, \helpref{wxMenu::GetLabel}{wxmenugetlabel} + \membersection{wxMenu::SetTitle}\label{wxmenusettitle} \func{void}{SetTitle}{\param{const wxString\& }{title}} @@ -433,11 +704,14 @@ Sets the title of the menu. \wxheading{Remarks} -This is relevant only to popup menus. +This is relevant only to popup menus, use +\helpref{wxMenuBar::SetLabelTop}{wxmenubarsetlabeltop} for the menus in the +menubar. \wxheading{See also} -\helpref{wxMenu::SetTitle}{wxmenusettitle} +\helpref{wxMenu::GetTitle}{wxmenugettitle} + \membersection{wxMenu::UpdateUI}\label{wxmenuupdateui} @@ -457,6 +731,7 @@ A menu bar is a series of menus accessible from the top of a frame. \wxheading{Derived from} +\helpref{wxWindow}{wxwindow}\\ \helpref{wxEvtHandler}{wxevthandler}\\ \helpref{wxObject}{wxobject} @@ -464,6 +739,10 @@ A menu bar is a series of menus accessible from the top of a frame. +\wxheading{Library} + +\helpref{wxCore}{librarieslist} + \wxheading{Event handling} To respond to a menu selection, provide a handler for EVT\_MENU, in the frame @@ -471,11 +750,10 @@ that contains the menu bar. If you have a toolbar which uses the same identifier as your EVT\_MENU entries, events from the toolbar will also be processed by your EVT\_MENU event handlers. -Note that menu commands (and UI update events for menus) are first sent to -the focus window within the frame. If no window within the frame has the focus, -then the events are sent directly to the frame. This allows command and UI update -handling to be processed by specific windows and controls, and not necessarily -by the application frame. +{\bf Tip:} under Windows, if you discover that menu shortcuts (for example, Alt-F to show the file menu) +are not working, check any EVT\_CHAR events you are handling in child windows. +If you are not calling {\tt event.Skip()} for events that you don't process in these event handlers, +menu shortcuts may cease to work. \wxheading{See also} @@ -483,13 +761,14 @@ by the application frame. \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxMenuBar::wxMenuBar}\label{wxmenubarconstr} -\func{void}{wxMenuBar}{\void} +\membersection{wxMenuBar::wxMenuBar}\label{wxmenubarctor} + +\func{}{wxMenuBar}{\param{long }{style = 0}} Default constructor. -\func{void}{wxMenuBar}{\param{int}{ n}, \param{wxMenu*}{ menus[]}, \param{const wxString }{titles[]}} +\func{}{wxMenuBar}{\param{size\_t}{ n}, \param{wxMenu*}{ menus[]}, \param{const wxString }{titles[]}, \param{long }{style = 0}} Construct a menu bar from arrays of menus and titles. @@ -502,15 +781,22 @@ menu bar.} \docparam{titles}{An array of title strings. Deallocate this array after creating the menu bar.} +\docparam{style}{If {\tt wxMB\_DOCKABLE} the menu bar can be detached (wxGTK only).} + \pythonnote{Only the default constructor is supported in wxPython. -Use wxMenuBar.Append instead.} +Use \helpref{wxMenuBar::Append}{wxmenubarappend} instead.} -\membersection{wxMenuBar::\destruct{wxMenuBar}} +\perlnote{wxPerl only supports the first constructor: +use \helpref{wxMenuBar::Append}{wxmenubarappend} instead.} + + +\membersection{wxMenuBar::\destruct{wxMenuBar}}\label{wxmenubardtor} \func{void}{\destruct{wxMenuBar}}{\void} Destructor, destroying the menu bar and removing it from the parent frame (if any). + \membersection{wxMenuBar::Append}\label{wxmenubarappend} \func{bool}{Append}{\param{wxMenu *}{menu}, \param{const wxString\& }{title}} @@ -525,12 +811,13 @@ Adds the item to the end of the menu bar. \wxheading{Return value} -TRUE on success, FALSE if an error occured. +true on success, false if an error occurred. \wxheading{See also} \helpref{wxMenuBar::Insert}{wxmenubarinsert} + \membersection{wxMenuBar::Check}\label{wxmenubarcheck} \func{void}{Check}{\param{int}{ id}, \param{const bool}{ check}} @@ -541,13 +828,14 @@ Checks or unchecks a menu item. \docparam{id}{The menu item identifier.} -\docparam{check}{If TRUE, checks the menu item, otherwise the item is unchecked.} +\docparam{check}{If true, checks the menu item, otherwise the item is unchecked.} \wxheading{Remarks} Only use this when the menu bar has been associated with a frame; otherwise, use the wxMenu equivalent call. + \membersection{wxMenuBar::Enable}\label{wxmenubarenable} \func{void}{Enable}{\param{int}{ id}, \param{const bool}{ enable}} @@ -558,13 +846,14 @@ Enables or disables (greys out) a menu item. \docparam{id}{The menu item identifier.} -\docparam{enable}{TRUE to enable the item, FALSE to disable it.} +\docparam{enable}{true to enable the item, false to disable it.} \wxheading{Remarks} Only use this when the menu bar has been associated with a frame; otherwise, use the wxMenu equivalent call. + \membersection{wxMenuBar::EnableTop}\label{wxmenubarenabletop} \func{void}{EnableTop}{\param{int}{ pos}, \param{const bool}{ enable}} @@ -575,13 +864,24 @@ Enables or disables a whole menu. \docparam{pos}{The position of the menu, starting from zero.} -\docparam{enable}{TRUE to enable the menu, FALSE to disable it.} +\docparam{enable}{true to enable the menu, false to disable it.} \wxheading{Remarks} Only use this when the menu bar has been associated with a frame. + +\membersection{wxMenuBar::FindMenu}\label{wxmenubarfindmenu} + +\constfunc{int}{FindMenu}{\param{const wxString\& }{title}} + +Returns the index of the menu with the given {\it title} or {\tt wxNOT\_FOUND} if no +such menu exists in this menubar. The {\it title} parameter may specify either +the menu title (with accelerator characters, i.e. {\tt "\&File"}) or just the +menu label ({\tt "File"}) indifferently. + + \membersection{wxMenuBar::FindMenuItem}\label{wxmenubarfindmenuitem} \constfunc{int}{FindMenuItem}{\param{const wxString\& }{menuString}, \param{const wxString\& }{itemString}} @@ -596,13 +896,14 @@ Finds the menu item id for a menu name/menu item string pair. \wxheading{Return value} -The menu item identifier, or wxNOT\_FOUND if none was found. +The menu item identifier, or {\tt wxNOT\_FOUND} if none was found. \wxheading{Remarks} Any special menu codes are stripped out of source and target strings before matching. + \membersection{wxMenuBar::FindItem}\label{wxmenubarfinditem} \constfunc{wxMenuItem *}{FindItem}{\param{int}{ id}, \param{wxMenu}{ **menu = NULL}} @@ -619,11 +920,12 @@ Finds the menu item object associated with the given menu item identifier. The found menu item object, or NULL if one was not found. + \membersection{wxMenuBar::GetHelpString}\label{wxmenubargethelpstring} \constfunc{wxString}{GetHelpString}{\param{int}{ id}} -Gets the help string associated with the menu item identifer. +Gets the help string associated with the menu item identifier. \wxheading{Parameters} @@ -638,6 +940,7 @@ was not found. \helpref{wxMenuBar::SetHelpString}{wxmenubarsethelpstring} + \membersection{wxMenuBar::GetLabel}\label{wxmenubargetlabel} \constfunc{wxString}{GetLabel}{\param{int}{ id}} @@ -656,11 +959,14 @@ The menu item label, or the empty string if the item was not found. Use only after the menubar has been associated with a frame. + \membersection{wxMenuBar::GetLabelTop}\label{wxmenubargetlabeltop} \constfunc{wxString}{GetLabelTop}{\param{int}{ pos}} -Returns the label of a top-level menu. +Returns the label of a top-level menu. Note that the returned string does not +include the accelerator characters which could have been specified in the menu +title string during its construction. \wxheading{Parameters} @@ -674,29 +980,84 @@ The menu label, or the empty string if the menu was not found. Use only after the menubar has been associated with a frame. +This function is deprecated in favour of \helpref{GetMenuLabel}{wxmenubargetmenulabel} and \helpref{GetMenuLabelText}{wxmenubargetmenulabeltext}. + \wxheading{See also} \helpref{wxMenuBar::SetLabelTop}{wxmenubarsetlabeltop} + \membersection{wxMenuBar::GetMenu}\label{wxmenubargetmenu} \constfunc{wxMenu*}{GetMenu}{\param{int}{ menuIndex}} Returns the menu at {\it menuIndex} (zero-based). + \membersection{wxMenuBar::GetMenuCount}\label{wxmenubargetmenucount} -\constfunc{int}{GetMenuCount}{\void} +\constfunc{size\_t}{GetMenuCount}{\void} Returns the number of menus in this menubar. + +\membersection{wxMenuBar::GetMenuLabel}\label{wxmenubargetmenulabel} + +\constfunc{wxString}{GetMenuLabel}{\param{int}{ pos}} + +Returns the label of a top-level menu. Note that the returned string +includes the accelerator characters that have been specified in the menu +title string during its construction. + +\wxheading{Parameters} + +\docparam{pos}{Position of the menu on the menu bar, starting from zero.} + +\wxheading{Return value} + +The menu label, or the empty string if the menu was not found. + +\wxheading{Remarks} + +Use only after the menubar has been associated with a frame. + +\wxheading{See also} + +\helpref{wxMenuBar::GetMenuLabelText}{wxmenubargetmenulabeltext}, \helpref{wxMenuBar::SetMenuLabel}{wxmenubarsetmenulabel} + + +\membersection{wxMenuBar::GetMenuLabelText}\label{wxmenubargetmenulabeltext} + +\constfunc{wxString}{GetMenuLabelText}{\param{int}{ pos}} + +Returns the label of a top-level menu. Note that the returned string does not +include any accelerator characters that may have been specified in the menu +title string during its construction. + +\wxheading{Parameters} + +\docparam{pos}{Position of the menu on the menu bar, starting from zero.} + +\wxheading{Return value} + +The menu label, or the empty string if the menu was not found. + +\wxheading{Remarks} + +Use only after the menubar has been associated with a frame. + +\wxheading{See also} + +\helpref{wxMenuBar::GetMenuLabel}{wxmenubargetmenulabel}, \helpref{wxMenuBar::SetMenuLabel}{wxmenubarsetmenulabel} + + \membersection{wxMenuBar::Insert}\label{wxmenubarinsert} \func{bool}{Insert}{\param{size\_t }{pos}, \param{wxMenu *}{menu}, \param{const wxString\& }{title}} Inserts the menu at the given position into the menu bar. Inserting menu at -position $0$ will insert it in the very beginning of it, inserting at position -\helpref{GetMenuCount()}{wxmenubargetmenucount} is the same as calling +position $0$ will insert it in the very beginning of it, inserting at position +\helpref{GetMenuCount()}{wxmenubargetmenucount} is the same as calling \helpref{Append()}{wxmenubarappend}. \wxheading{Parameters} @@ -709,12 +1070,13 @@ position $0$ will insert it in the very beginning of it, inserting at position \wxheading{Return value} -TRUE on success, FALSE if an error occured. +true on success, false if an error occurred. \wxheading{See also} \helpref{wxMenuBar::Append}{wxmenubarappend} + \membersection{wxMenuBar::IsChecked}\label{wxmenubarischecked} \constfunc{bool}{IsChecked}{\param{int}{ id}} @@ -727,7 +1089,8 @@ Determines whether an item is checked. \wxheading{Return value} -TRUE if the item was found and is checked, FALSE otherwise. +true if the item was found and is checked, false otherwise. + \membersection{wxMenuBar::IsEnabled}\label{wxmenubarisenabled} @@ -741,7 +1104,8 @@ Determines whether an item is enabled. \wxheading{Return value} -TRUE if the item was found and is enabled, FALSE otherwise. +true if the item was found and is enabled, false otherwise. + \membersection{wxMenuBar::Refresh}\label{wxmenubarrefresh} @@ -749,12 +1113,13 @@ TRUE if the item was found and is enabled, FALSE otherwise. Redraw the menu bar + \membersection{wxMenuBar::Remove}\label{wxmenubarremove} \func{wxMenu *}{Remove}{\param{size\_t }{pos}} Removes the menu from the menu bar and returns the menu object - the caller is -reposnbile for deleting it. This function may be used together with +responsible for deleting it. This function may be used together with \helpref{wxMenuBar::Insert}{wxmenubarinsert} to change the menubar dynamically. @@ -762,11 +1127,12 @@ dynamically. \helpref{wxMenuBar::Replace}{wxmenubarreplace} + \membersection{wxMenuBar::Replace}\label{wxmenubarreplace} \func{wxMenu *}{Replace}{\param{size\_t }{pos}, \param{wxMenu *}{menu}, \param{const wxString\& }{title}} -Replaces the menu at givenm position with another one. +Replaces the menu at the given position with another one. \wxheading{Parameters} @@ -778,7 +1144,7 @@ Replaces the menu at givenm position with another one. \wxheading{Return value} -The menu which was previously at the position {\it pos}. The caller is +The menu which was previously at position {\it pos}. The caller is responsible for deleting it. \wxheading{See also} @@ -786,6 +1152,7 @@ responsible for deleting it. \helpref{wxMenuBar::Insert}{wxmenubarinsert},\rtfsp \helpref{wxMenuBar::Remove}{wxmenubarremove} + \membersection{wxMenuBar::SetHelpString}\label{wxmenubarsethelpstring} \func{void}{SetHelpString}{\param{int}{ id}, \param{const wxString\& }{helpString}} @@ -802,6 +1169,7 @@ Sets the help string associated with a menu item. \helpref{wxMenuBar::GetHelpString}{wxmenubargethelpstring} + \membersection{wxMenuBar::SetLabel}\label{wxmenubarsetlabel} \func{void}{SetLabel}{\param{int}{ id}, \param{const wxString\& }{label}} @@ -822,6 +1190,7 @@ Use only after the menubar has been associated with a frame. \helpref{wxMenuBar::GetLabel}{wxmenubargetlabel} + \membersection{wxMenuBar::SetLabelTop}\label{wxmenubarsetlabeltop} \func{void}{SetLabelTop}{\param{int}{ pos}, \param{const wxString\& }{label}} @@ -838,7 +1207,30 @@ Sets the label of a top-level menu. Use only after the menubar has been associated with a frame. +This function has been deprecated in favour of \helpref{SetMenuLabel}{wxmenubarsetmenulabel}. + \wxheading{See also} \helpref{wxMenuBar::GetLabelTop}{wxmenubargetlabeltop} + +\membersection{wxMenuBar::SetMenuLabel}\label{wxmenubarsetmenulabel} + +\func{void}{SetMenuLabel}{\param{int}{ pos}, \param{const wxString\& }{label}} + +Sets the label of a top-level menu. + +\wxheading{Parameters} + +\docparam{pos}{The position of a menu on the menu bar, starting from zero.} + +\docparam{label}{The menu label.} + +\wxheading{Remarks} + +Use only after the menubar has been associated with a frame. + +\wxheading{See also} + +\helpref{wxMenuBar::GetMenuLabel}{wxmenubargetmenulabel}, \helpref{wxMenuBar::GetMenuLabelText}{wxmenubargetmenulabeltext} +