X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/d65c269b3f665e15a8ae1b8fff063b2ec0ef19a7..4a6e4a46a356e9abf0760e2d481bbec321cc3adf:/docs/latex/wx/menu.tex?ds=sidebyside

diff --git a/docs/latex/wx/menu.tex b/docs/latex/wx/menu.tex
index e53ab4519e..c18f5e60b0 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}
 
@@ -352,7 +407,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 +421,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 +479,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 +497,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 +505,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 +618,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 +699,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 +722,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 +738,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 +755,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 +772,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 +829,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 +866,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 +917,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 +935,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 +949,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}