X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/d17f05afeb41c64fab410cd3178a78596da55e38..2245b2b2c3339ecf023e5880caa803610a5d1907:/docs/latex/wx/menu.tex

diff --git a/docs/latex/wx/menu.tex b/docs/latex/wx/menu.tex
index 4f8faa2abb..4f04df6731 100644
--- a/docs/latex/wx/menu.tex
+++ b/docs/latex/wx/menu.tex
@@ -2,10 +2,30 @@
 
 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 togles 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{Derived from}
 
@@ -51,7 +71,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,7 +79,7 @@ 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}}
 
@@ -77,7 +97,7 @@ 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}}
+\param{wxItemKind}{ kind = wxItem\_Normal}}
 
 Adds a string item to the end of the menu.
 
@@ -101,7 +121,8 @@ 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
@@ -118,6 +139,8 @@ creation of a menu or menubar.
 \wxheading{See also}
 
 \helpref{wxMenu::AppendSeparator}{wxmenuappendseparator},\rtfsp
+\helpref{wxMenu::AppendCheckItem}{wxmenuappendcheckitem},\rtfsp
+\helpref{wxMenu::AppendRadioItem}{wxmenuappendradioitem},\rtfsp
 \helpref{wxMenu::Insert}{wxmenuinsert},\rtfsp
 \helpref{wxMenu::SetLabel}{wxmenusetlabel}, \helpref{wxMenu::GetHelpString}{wxmenugethelpstring},\rtfsp
 \helpref{wxMenu::SetHelpString}{wxmenusethelpstring}, \helpref{wxMenuItem}{wxmenuitem}
@@ -131,6 +154,35 @@ implements the following methods:\par
 \end{twocollist}}
 }
 
+\membersection{wxMenu::AppendCheckItem}\label{wxmenuappendcheckitem}
+
+\func{void}{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{void}{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.
+
+{\bf NB:} Currently only implemented under Windows and GTK, use
+{\tt #if wxHAS\_RADIO\_MENU\_ITEMS} to test for availability of this feature.
+
+\wxheading{See also}
+
+\helpref{wxMenu::Append}{wxmenuappend},\rtfsp
+\helpref{wxMenu::InsertRadioItem}{wxmenuinsertradioitem}
+
 \membersection{wxMenu::AppendSeparator}\label{wxmenuappendseparator}
 
 \func{void}{AppendSeparator}{\void}
@@ -139,7 +191,8 @@ 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::Break}\label{wxmenubreak}
 
@@ -234,6 +287,10 @@ 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.}
@@ -254,7 +311,7 @@ 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::GetHelpString}\label{wxmenugethelpstring}
@@ -325,13 +382,53 @@ This is relevant only to popup menus.
 
 \func{bool}{Insert}{\param{size\_t }{pos}, \param{wxMenuItem *}{item}}
 
+\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}}
+
 Inserts the given {\it item} before the position {\it pos}. Inserting the item
 at the 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{void}{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{void}{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{void}{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}
 
@@ -369,6 +466,56 @@ TRUE if the menu item is enabled, FALSE otherwise.
 
 \helpref{wxMenu::Enable}{wxmenuenable}
 
+\membersection{wxMenu::Prepend}\label{wxmenuprepend}
+
+\func{bool}{Prepend}{\param{size\_t }{pos}, \param{wxMenuItem *}{item}}
+
+\func{void}{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 the position $0$.
+
+\wxheading{See also}
+
+\helpref{wxMenu::Append}{wxmenuappend},\rtfsp
+\helpref{wxMenu::Inserts}{wxmenuinsert}
+
+\membersection{wxMenu::PrependCheckItem}\label{wxmenuprependcheckitem}
+
+\func{void}{PrependCheckItem}{\param{int}{ id},\rtfsp
+\param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""}}
+
+Inserts a checkable item at the position $0$.
+
+\wxheading{See also}
+
+\helpref{wxMenu::Prepend}{wxmenuprepend},\rtfsp
+\helpref{wxMenu::AppendCheckItem}{wxmenuappendcheckitem}
+
+\membersection{wxMenu::PrependRadioItem}\label{wxmenuprependradioitem}
+
+\func{void}{PrependRadioItem}{\param{int}{ id},\rtfsp
+\param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""}}
+
+Inserts a radio item at the position $0$.
+
+\wxheading{See also}
+
+\helpref{wxMenu::Prepend}{wxmenuprepend},\rtfsp
+\helpref{wxMenu::AppendRadioItem}{wxmenuappendradioitem}
+
+\membersection{wxMenu::PrependSeparator}\label{wxmenuprependseparator}
+
+\func{void}{PrependSeparator}{\param{size\_t }{pos}}
+
+Inserts a separator at the 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}}
@@ -477,6 +624,11 @@ then the events are sent directly to the frame. This allows command and UI updat
 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}
 
 \helpref{wxMenu}{wxmenu}, \helpref{Event handling overview}{eventhandlingoverview}
@@ -507,6 +659,9 @@ menu bar.}
 \pythonnote{Only the default constructor is supported in wxPython.
 Use wxMenuBar.Append instead.}
 
+\perlnote{wxPerl only supports the first contructor: 
+use {\tt Append} instead.}
+
 \membersection{wxMenuBar::\destruct{wxMenuBar}}
 
 \func{void}{\destruct{wxMenuBar}}{\void}
@@ -527,7 +682,7 @@ 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}
 
@@ -584,6 +739,15 @@ Enables or disables a whole menu.
 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 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}}
@@ -697,8 +861,8 @@ Returns the number of menus in this menubar.
 \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}
@@ -711,7 +875,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 occured.
+TRUE on success, FALSE if an error occurred.
 
 \wxheading{See also}
 
@@ -756,7 +920,7 @@ Redraw the menu bar
 \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.
 
@@ -768,7 +932,7 @@ dynamically.
 
 \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}