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}
\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
+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}
\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}}
\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::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.
\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
\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}
\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{AppendMenu(id, string, aMenu, helpStr="")}}{}
-\twocolitem{\bf{AppendItem(aMenuItem)}}{}
+\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{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}
\wxheading{See also}
-\helpref{wxMenu::Append}{wxmenuappend}
+\helpref{wxMenu::Append}{wxmenuappend},\rtfsp
+\helpref{wxMenu::InsertSeparator}{wxmenuinsertseparator}
\membersection{wxMenu::Break}\label{wxmenubreak}
\func{void}{Delete}{\param{wxMenuItem *}{item}}
-Deletes the menu item from the menu. If the item is a submenu, it will
+Deletes the menu item from the menu. If the item is a submenu, it will
{\bf not} be deleted. Use \helpref{Destroy}{wxmenudestroy} if you want to
delete a submenu.
\func{void}{Destroy}{\param{wxMenuItem *}{item}}
-Deletes the menu item from the menu. If the item is a submenu, it will
+Deletes the menu item from the menu. If the item is a submenu, it will
be deleted. Use \helpref{Remove}{wxmenuremove} if you want to keep the submenu
(for example, to reuse it later).
Finds the menu item id for a menu item string.
-\wxheading{Parameters}
-
-\docparam{itemString}{Menu item string to find.}
-
-\wxheading{Return value}
-
-Menu item identifier, or wxNOT\_FOUND if none is found.
-
-\wxheading{Remarks}
-
-Any special menu codes are stripped out of source and target strings
-before matching.
-
-\wxheading{See also}
-
-\helpref{wxMenu::FindItem}{wxmenufinditem}
-
-\membersection{wxMenu::FindItem}\label{wxmenufinditem}
-
\constfunc{wxMenuItem *}{FindItem}{\param{int}{ id}, \param{wxMenu **}{menu = NULL}}
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
\wxheading{Return value}
-Returns the menu item object, or NULL if it is not found.
+First form: menu item identifier, or wxNOT\_FOUND if none is found.
-\wxheading{See also}
+Second form: returns the menu item object, or NULL if it is not found.
+
+\wxheading{Remarks}
+
+Any special menu codes are stripped out of source and target strings
+before matching.
-\helpref{wxMenu::FindItem}{wxmenufinditem}
+\pythonnote{The name of this method in wxPython is {\tt FindItemById}
+and it does not support the second parameter.}
\membersection{wxMenu::GetHelpString}\label{wxmenugethelpstring}
\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}
\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}}
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}
\membersection{wxMenuBar::wxMenuBar}\label{wxmenubarconstr}
-\func{void}{wxMenuBar}{\void}
+\func{void}{wxMenuBar}{\param{long }{style = 0}}
Default constructor.
\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.}
+\perlnote{wxPerl only supports the first contructor:
+use {\tt Append} instead.}
+
\membersection{wxMenuBar::\destruct{wxMenuBar}}
\func{void}{\destruct{wxMenuBar}}{\void}
\wxheading{Return value}
-TRUE on success, FALSE if an error occured.
+TRUE on success, FALSE if an error occurred.
\wxheading{See also}
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}}
Returns the number of menus in this menubar.
-\membersection{wxMenuBar::Insert}{wxmenubarinsert}
+\membersection{wxMenuBar::Insert}\label{wxmenubarinsert}
\func{bool}{Insert}{\param{size\_t }{pos}, \param{wxMenu *}{menu}, \param{const wxString\& }{title}}
\wxheading{Return value}
-TRUE on success, FALSE if an error occured.
+TRUE on success, FALSE if an error occurred.
\wxheading{See also}
\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.
\wxheading{See also}
-\helpref{wxMenuBar::Replace}[wxmenubarreplace}
+\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}
\helpref{wxMenuBar::Insert}{wxmenubarinsert},\rtfsp
\helpref{wxMenuBar::Remove}{wxmenubarremove}
-\membersection{wxMenuBar::IsChecked}\label{wxmenubarischecked}
-
\membersection{wxMenuBar::SetHelpString}\label{wxmenubarsethelpstring}
\func{void}{SetHelpString}{\param{int}{ id}, \param{const wxString\& }{helpString}}
projects / wxWidgets.git / blobdiff