\helpref{wxEvtHandler}{wxevthandler}\\
\helpref{wxObject}{wxobject}
+\wxheading{Include files}
+
+<wx/menu.h>
+
\wxheading{Event handling}
If the menu is part of a menubar, then \helpref{wxMenuBar}{wxmenubar} event processing is used.
(wxEVT\_COMMAND\_MENU\_SELECTED).
\begin{enumerate}\itemsep=0pt
-\item Define a callback of type wxFunction, which you pass to the wxMenu constructor.
-The callback takes a reference to a window, and a reference to a \helpref{wxCommandEvent}{wxcommandevent}.
\item Derive a new class from wxMenu and define event table entries using the EVT\_MENU macro.
\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}
\membersection{wxMenu::wxMenu}\label{wxmenuconstr}
-\func{}{wxMenu}{\param{const wxString\& }{title = ""}, \param{const wxFunction}{ func = NULL}}
+\func{}{wxMenu}{\param{const wxString\& }{title = ""}, \param{long}{ style = 0}}
Constructs a wxMenu object.
\docparam{title}{A title for the popup menu: the empty string denotes no title.}
-\docparam{func}{A callback function if the menu is used as a popup using \helpref{wxWindow::PopupMenu}{wxwindowpopupmenu}.}
+\docparam{style}{If set to {\tt wxMENU\_TEAROFF}, the menu will be detachable (wxGTK only).}
+
+\func{}{wxMenu}{\param{long}{ style}}
+
+Constructs a wxMenu object.
+
+\wxheading{Parameters}
+
+\docparam{style}{If set to {\tt wxMENU\_TEAROFF}, the menu will be detachable (wxGTK only).}
\membersection{wxMenu::\destruct{wxMenu}}
Destructor, destroying the menu.
+Note: under Motif, a popup menu must have a valid parent (the window
+it was last popped up on) when being destroyed. Therefore, make sure
+you delete or re-use the popup menu {\it before} destroying the
+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{const int}{ id}, \param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""},\rtfsp
+\func{void}{Append}{\param{int}{ id}, \param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""},\rtfsp
\param{const bool}{ checkable = FALSE}}
Adds a string item to the end of the menu.
-\func{void}{Append}{\param{const int}{ id}, \param{const wxString\& }{ item}, \param{wxMenu *}{subMenu},\rtfsp
+\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.
\func{void}{Append}{\param{wxMenuItem*}{ menuItem}}
-Adds a menu item object. You can specify various extra properties of a menu item this way,
+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
+because you can also specify various extra properties of a menu item this way,
such as bitmaps and fonts.
\wxheading{Parameters}
\wxheading{See also}
-\helpref{wxMenu::AppendSeparator}{wxmenuappendseparator}, \helpref{wxMenu::SetLabel}{wxmenusetlabel}, \helpref{wxMenu::GetHelpString}{wxmenugethelpstring},\rtfsp
+\helpref{wxMenu::AppendSeparator}{wxmenuappendseparator},\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)}}{}
+\end{twocollist}}
+}
+
\membersection{wxMenu::AppendSeparator}\label{wxmenuappendseparator}
\func{void}{AppendSeparator}{\void}
\membersection{wxMenu::Check}\label{wxmenucheck}
-\func{void}{Check}{\param{const int}{ id}, \param{const bool}{ check}}
+\func{void}{Check}{\param{int}{ id}, \param{const bool}{ check}}
Checks or unchecks the menu item.
\helpref{wxMenu::IsChecked}{wxmenuischecked}
-\membersection{wxMenu::Enable}\label{wxmenuenable}
+\membersection{wxMenu::Delete}\label{wxmenudelete}
-\func{void}{Enable}{\param{const int}{ id}, \param{const bool}{ enable}}
+\func{void}{Delete}{\param{int }{id}}
-Enables or disables (greys out) a menu item.
+\func{void}{Delete}{\param{wxMenuItem *}{item}}
+
+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.
\wxheading{Parameters}
-\docparam{id}{The menu item identifier.}
+\docparam{id}{Id of the menu item to be deleted.}
-\docparam{enable}{TRUE to enable the menu item, FALSE to disable it.}
+\docparam{item}{Menu item to be deleted.}
\wxheading{See also}
-\helpref{wxMenu::IsEnabled}{wxmenuisenabled}
+\helpref{wxMenu::FindItem}{wxmenufinditem},\rtfsp
+\helpref{wxMenu::Destroy}{wxmenudestroy},\rtfsp
+\helpref{wxMenu::Remove}{wxmenuremove}
-\membersection{wxMenu::FindItem}\label{wxmenufinditem}
+\membersection{wxMenu::Destroy}\label{wxmenudestroy}
-\constfunc{int}{FindItem}{\param{const wxString\& }{itemString}}
+\func{void}{Destroy}{\param{int }{id}}
-Finds the menu item id for a menu item string.
+\func{void}{Destroy}{\param{wxMenuItem *}{item}}
+
+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).
\wxheading{Parameters}
-\docparam{itemString}{Menu item string to find.}
+\docparam{id}{Id of the menu item to be deleted.}
-\wxheading{Return value}
+\docparam{item}{Menu item to be deleted.}
-Menu item identifier, or -1 if none is found.
+\wxheading{See also}
-\wxheading{Remarks}
+\helpref{wxMenu::FindItem}{wxmenufinditem},\rtfsp
+\helpref{wxMenu::Deletes}{wxmenudelete},\rtfsp
+\helpref{wxMenu::Remove}{wxmenuremove}
-Any special menu codes are stripped out of source and target strings
-before matching.
+\membersection{wxMenu::Enable}\label{wxmenuenable}
+
+\func{void}{Enable}{\param{int}{ id}, \param{const bool}{ enable}}
+
+Enables or disables (greys out) a menu item.
+
+\wxheading{Parameters}
+
+\docparam{id}{The menu item identifier.}
+
+\docparam{enable}{TRUE to enable the menu item, FALSE to disable it.}
\wxheading{See also}
-\helpref{wxMenu::FindItemForId}{wxmenufinditemforid}
+\helpref{wxMenu::IsEnabled}{wxmenuisenabled}
-\membersection{wxMenu::FindItemForId}\label{wxmenufinditemforid}
+\membersection{wxMenu::FindItem}\label{wxmenufinditem}
-\constfunc{wxMenuItem*}{FindItemForId}{\param{const int}{ id}}
+\constfunc{int}{FindItem}{\param{const wxString\& }{itemString}}
-Finds the menu item object associated with the given menu item identifier.
+Finds the menu item id for a menu item string.
+
+\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 ( 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
+parent menu (if the item was found)}
+
\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.
-\helpref{wxMenu::FindItem}{wxmenufinditem}
+\wxheading{Remarks}
+
+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}
+and it does not support the second parameter.}
\membersection{wxMenu::GetHelpString}\label{wxmenugethelpstring}
-\constfunc{wxString}{GetHelpString}{\param{const int}{ id}}
+\constfunc{wxString}{GetHelpString}{\param{int}{ id}}
Returns the help string associated with a menu item.
\membersection{wxMenu::GetLabel}\label{wxmenugetlabel}
-\constfunc{wxString}{GetLabel}{\param{const int}{ id}}
+\constfunc{wxString}{GetLabel}{\param{int}{ id}}
Returns a menu item label.
\helpref{wxMenu::SetLabel}{wxmenusetlabel}
+\membersection{wxMenu::GetMenuItemCount}\label{wxmenugetmenuitemcount}
+
+\constfunc{size\_t}{GetMenuItemCount}{\void}
+
+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.
+
\membersection{wxMenu::GetTitle}\label{wxmenugettitle}
\constfunc{wxString}{GetTitle}{\void}
\helpref{wxMenu::SetTitle}{wxmenusettitle}
+\membersection{wxMenu::Insert}\label{wxmenuinsert}
+
+\func{bool}{Insert}{\param{size\_t }{pos}, \param{wxMenuItem *}{item}}
+
+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}
+
\membersection{wxMenu::IsChecked}\label{wxmenuischecked}
-\constfunc{bool}{IsChecked}{\param{const int}{ id}}
+\constfunc{bool}{IsChecked}{\param{int}{ id}}
Determines whether a menu item is checked.
\membersection{wxMenu::IsEnabled}\label{wxmenuisenabled}
-\constfunc{bool}{IsEnabled}{\param{const int}{ id}}
+\constfunc{bool}{IsEnabled}{\param{int}{ id}}
Determines whether a menu item is enabled.
\helpref{wxMenu::Enable}{wxmenuenable}
+\membersection{wxMenu::Remove}\label{wxmenuremove}
+
+\func{wxMenuItem *}{Remove}{\param{int }{id}}
+
+\func{wxMenuItem *}{Remove}{\param{wxMenuItem *}{item}}
+
+Removes the menu item from the menu but doesn't delete the associated C++
+object. This allows to reuse the same item later by adding it back to the menu
+(especially useful with submenus).
+
+\wxheading{Parameters}
+
+\docparam{id}{The identifier of the menu item to remove.}
+
+\docparam{item}{The menu item to remove.}
+
+\wxheading{Return value}
+
+The item which was detached from the menu.
+
\membersection{wxMenu::SetHelpString}\label{wxmenusethelpstring}
-\func{void}{SetHelpString}{\param{const int}{ id}, \param{const wxString\& }{helpString}}
+\func{void}{SetHelpString}{\param{int}{ id}, \param{const wxString\& }{helpString}}
Sets an item's help string.
\membersection{wxMenu::SetLabel}\label{wxmenusetlabel}
-\func{void}{SetLabel}{\param{const int}{ id}, \param{const wxString\& }{label}}
+\func{void}{SetLabel}{\param{int}{ id}, \param{const wxString\& }{label}}
Sets the label of a menu item.
\helpref{wxMenu::SetTitle}{wxmenusettitle}
+\membersection{wxMenu::UpdateUI}\label{wxmenuupdateui}
+
+\constfunc{void}{UpdateUI}{\param{wxEvtHandler*}{ source = NULL}}
+
+Sends events to {\it source} (or owning window if NULL) to update the
+menu UI. This is called just before the menu is popped up with \helpref{wxWindow::PopupMenu}{wxwindowpopupmenu}, but
+the application may call it at other times if required.
+
+\wxheading{See also}
+
+\helpref{wxUpdateUIEvent}{wxupdateuievent}
+
\section{\class{wxMenuBar}}\label{wxmenubar}
A menu bar is a series of menus accessible from the top of a frame.
\helpref{wxEvtHandler}{wxevthandler}\\
\helpref{wxObject}{wxobject}
+\wxheading{Include files}
+
+<wx/menu.h>
+
\wxheading{Event handling}
To respond to a menu selection, provide a handler for EVT\_MENU, in the frame
-that contains the menu bar.
+that contains the menu bar. If you have a toolbar which uses the same identifiers
+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}
\membersection{wxMenuBar::wxMenuBar}\label{wxmenubarconstr}
-\func{void}{wxMenuBar}{\void}
+\func{void}{wxMenuBar}{\param{long }{style = 0}}
Default constructor.
-\func{void}{wxMenuBar}{\param{const int}{ n}, \param{wxMenu*}{ menus[]}, \param{const wxString }{titles[]}}
+\func{void}{wxMenuBar}{\param{int}{ n}, \param{wxMenu*}{ menus[]}, \param{const wxString }{titles[]}}
Construct a menu bar from arrays of menus and titles.
\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}
\membersection{wxMenuBar::Append}\label{wxmenubarappend}
-\func{void}{Append}{\param{wxMenu *}{menu}, \param{const wxString\& }{title}}
+\func{bool}{Append}{\param{wxMenu *}{menu}, \param{const wxString\& }{title}}
Adds the item to the end of the menu bar.
\docparam{title}{The title of the menu.}
+\wxheading{Return value}
+
+TRUE on success, FALSE if an error occurred.
+
+\wxheading{See also}
+
+\helpref{wxMenuBar::Insert}{wxmenubarinsert}
+
\membersection{wxMenuBar::Check}\label{wxmenubarcheck}
-\func{void}{Check}{\param{const int}{ id}, \param{const bool}{ check}}
+\func{void}{Check}{\param{int}{ id}, \param{const bool}{ check}}
Checks or unchecks a menu item.
\membersection{wxMenuBar::Enable}\label{wxmenubarenable}
-\func{void}{Enable}{\param{const int}{ id}, \param{const bool}{ enable}}
+\func{void}{Enable}{\param{int}{ id}, \param{const bool}{ enable}}
Enables or disables (greys out) a menu item.
\membersection{wxMenuBar::EnableTop}\label{wxmenubarenabletop}
-\func{void}{EnableTop}{\param{const int}{ pos}, \param{const bool}{ enable}}
+\func{void}{EnableTop}{\param{int}{ pos}, \param{const bool}{ enable}}
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}}
\wxheading{Return value}
-The menu item identifier, or -1 if none was found.
+The menu item identifier, or wxNOT\_FOUND if none was found.
\wxheading{Remarks}
Any special menu codes are stripped out of source and target strings
before matching.
-\membersection{wxMenuBar::FindItemById}\label{wxmenubarfinditembyid}
+\membersection{wxMenuBar::FindItem}\label{wxmenubarfinditem}
-\constfunc{wxMenuItem *}{FindItemById}{\param{const int}{ id}}
+\constfunc{wxMenuItem *}{FindItem}{\param{int}{ id}, \param{wxMenu}{ **menu = NULL}}
-Finds the menu item object associated with the given menu item identifier,
+Finds the menu item object associated with the given menu item identifier.
\wxheading{Parameters}
\docparam{id}{Menu item identifier.}
+\docparam{menu}{If not NULL, menu will get set to the associated menu.}
+
\wxheading{Return value}
The found menu item object, or NULL if one was not found.
\membersection{wxMenuBar::GetHelpString}\label{wxmenubargethelpstring}
-\constfunc{wxString}{GetHelpString}{\param{const int}{ id}}
+\constfunc{wxString}{GetHelpString}{\param{int}{ id}}
Gets the help string associated with the menu item identifer.
\membersection{wxMenuBar::GetLabel}\label{wxmenubargetlabel}
-\constfunc{wxString}{GetLabel}{\param{const int}{ id}}
+\constfunc{wxString}{GetLabel}{\param{int}{ id}}
Gets the label associated with a menu item.
\membersection{wxMenuBar::GetLabelTop}\label{wxmenubargetlabeltop}
-\constfunc{wxString}{GetLabelTop}{\param{const int}{ pos}}
+\constfunc{wxString}{GetLabelTop}{\param{int}{ pos}}
Returns the label of a top-level menu.
\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}
+
+Returns the number of menus in this menubar.
+
+\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
+\helpref{Append()}{wxmenubarappend}.
+
+\wxheading{Parameters}
+
+\docparam{pos}{The position of the new menu in the menu bar}
+
+\docparam{menu}{The menu to add. wxMenuBar owns the menu and will free it.}
+
+\docparam{title}{The title of the menu.}
+
+\wxheading{Return value}
+
+TRUE on success, FALSE if an error occurred.
+
+\wxheading{See also}
+
+\helpref{wxMenuBar::Append}{wxmenubarappend}
+
\membersection{wxMenuBar::IsChecked}\label{wxmenubarischecked}
-\constfunc{bool}{IsChecked}{\param{const int}{ id}}
+\constfunc{bool}{IsChecked}{\param{int}{ id}}
Determines whether an item is checked.
\membersection{wxMenuBar::IsEnabled}\label{wxmenubarisenabled}
-\constfunc{bool}{IsEnabled}{\param{const int}{ id}}
+\constfunc{bool}{IsEnabled}{\param{int}{ id}}
Determines whether an item is enabled.
TRUE if the item was found and is enabled, FALSE otherwise.
+\membersection{wxMenuBar::Refresh}\label{wxmenubarrefresh}
+
+\func{void}{Refresh}{\void}
+
+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
+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}
+
+\membersection{wxMenuBar::Replace}\label{wxmenubarreplace}
+
+\func{wxMenu *}{Replace}{\param{size\_t }{pos}, \param{wxMenu *}{menu}, \param{const wxString\& }{title}}
+
+Replaces the menu at the given position with another one.
+
+\wxheading{Parameters}
+
+\docparam{pos}{The position of the new menu in the menu bar}
+
+\docparam{menu}{The menu to add.}
+
+\docparam{title}{The title of the menu.}
+
+\wxheading{Return value}
+
+The menu which was previously at the position {\it pos}. The caller is
+responsible for deleting it.
+
+\wxheading{See also}
+
+\helpref{wxMenuBar::Insert}{wxmenubarinsert},\rtfsp
+\helpref{wxMenuBar::Remove}{wxmenubarremove}
+
\membersection{wxMenuBar::SetHelpString}\label{wxmenubarsethelpstring}
-\func{void}{SetHelpString}{\param{const int}{ id}, \param{const wxString\& }{helpString}}
+\func{void}{SetHelpString}{\param{int}{ id}, \param{const wxString\& }{helpString}}
Sets the help string associated with a menu item.
\membersection{wxMenuBar::SetLabel}\label{wxmenubarsetlabel}
-\func{void}{SetLabel}{\param{const int}{ id}, \param{const wxString\& }{label}}
+\func{void}{SetLabel}{\param{int}{ id}, \param{const wxString\& }{label}}
Sets the label of a menu item.
\membersection{wxMenuBar::SetLabelTop}\label{wxmenubarsetlabeltop}
-\func{void}{SetLabelTop}{\param{const int}{ pos}, \param{const wxString\& }{label}}
+\func{void}{SetLabelTop}{\param{int}{ pos}, \param{const wxString\& }{label}}
Sets the label of a top-level menu.
projects / wxWidgets.git / blobdiff