X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/d65c269b3f665e15a8ae1b8fff063b2ec0ef19a7..e00a5d3ca15eec8db3e231d79d82ff6965e3466b:/docs/latex/wx/menu.tex diff --git a/docs/latex/wx/menu.tex b/docs/latex/wx/menu.tex index e53ab4519e..219b7bcbba 100644 --- a/docs/latex/wx/menu.tex +++ b/docs/latex/wx/menu.tex @@ -2,10 +2,37 @@ 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. + +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. +wxWindows 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 the radio items +are only supported under Windows and GTK+ currently. + +\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} @@ -77,14 +104,16 @@ 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{wxItemKind}{ kind = wxItem\_Normal}} +\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 \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}} @@ -101,8 +130,8 @@ such as bitmaps and fonts. \docparam{menu}{Pull-right submenu.} -\docparam{kind}{May be {\tt wxItem\_Separator}, {\tt wxItem\_Normal}, -{\tt wxItem\_Check} or {\tt wxItem\_Radio}} +\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 @@ -116,6 +145,32 @@ 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 @@ -128,7 +183,7 @@ creation of a menu or menubar. \pythonnote{In place of a single overloaded method name, wxPython implements the following methods:\par \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}} @@ -156,7 +211,7 @@ group and when an item in the group is checked, all the others are automatically unchecked. {\bf NB:} Currently only implemented under Windows and GTK, use -{\tt #if wxHAS\_RADIO\_MENU\_ITEMS} to test for availability of this feature. +{\tt\#if wxHAS\_RADIO\_MENU\_ITEMS} to test for availability of this feature. \wxheading{See also} @@ -190,7 +245,7 @@ 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} @@ -250,7 +305,7 @@ 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} @@ -294,6 +349,12 @@ before matching. \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}} @@ -352,7 +413,9 @@ 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::GetLabelTop}{wxmenubargetlabeltop} for the menus in the +menubar. \wxheading{See also} @@ -364,7 +427,7 @@ This is relevant only to popup menus. \func{void}{Insert}{\param{size\_t }{pos}, \param{int}{ id},\rtfsp \param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""},\rtfsp -\param{wxItemKind}{ kind = wxItem\_Normal}} +\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 @@ -422,7 +485,7 @@ 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} @@ -440,7 +503,7 @@ 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} @@ -448,13 +511,14 @@ TRUE if the menu item is enabled, FALSE otherwise. \membersection{wxMenu::Prepend}\label{wxmenuprepend} -\func{bool}{Prepend}{\param{size\_t }{pos}, \param{wxMenuItem *}{item}} +\func{bool}{Prepend}{\param{wxMenuItem *}{item}} \func{void}{Prepend}{\param{int}{ id},\rtfsp \param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""},\rtfsp -\param{wxItemKind}{ kind = wxItem\_Normal}} +\param{wxItemKind}{ kind = wxITEM\_NORMAL}} -Inserts the given {\it item} at the position $0$. +Inserts the given {\it item} at the position $0$, i.e. before all the other +existing items. \wxheading{See also} @@ -560,11 +624,13 @@ 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} @@ -639,7 +705,7 @@ menu bar.} \pythonnote{Only the default constructor is supported in wxPython. Use wxMenuBar.Append instead.} -\perlnote{wxPerl only supports the first contructor: +\perlnote{wxPerl only supports the first constructor: use {\tt Append} instead.} \membersection{wxMenuBar::\destruct{wxMenuBar}} @@ -662,7 +728,7 @@ Adds the item to the end of the menu bar. \wxheading{Return value} -TRUE on success, FALSE if an error occurred. +true on success, false if an error occurred. \wxheading{See also} @@ -678,7 +744,7 @@ 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} @@ -695,7 +761,7 @@ 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} @@ -712,7 +778,7 @@ 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} @@ -769,7 +835,7 @@ The found menu item object, or NULL if one was not found. \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} @@ -806,7 +872,9 @@ Use only after the menubar has been associated with a frame. \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} @@ -855,7 +923,7 @@ position $0$ will insert it in the very beginning of it, inserting at position \wxheading{Return value} -TRUE on success, FALSE if an error occurred. +true on success, false if an error occurred. \wxheading{See also} @@ -873,7 +941,7 @@ 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} @@ -887,7 +955,7 @@ 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}