+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name: menu.tex
+%% Purpose: wxMenu documentation
+%% Author: wxWidgets Team
+%% Modified by:
+%% Created:
+%% RCS-ID: $Id$
+%% Copyright: (c) wxWidgets Team
+%% License: wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
\section{\class{wxMenu}}\label{wxmenu}
A menu is a popup (or pull down) list of items, one of which may be
predefined by wxWidgets and have a special meaning since entries
using these IDs will be taken out of the normal menus under MacOS X
and will be inserted into the system menu (following the appropriate
-MacOS X interface guideline).
+MacOS X interface guideline). On PalmOS {\it wxID\_EXIT} is disabled according
+to Palm OS Companion guidelines.
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
<wx/menu.h>
+\wxheading{Library}
+
+\helpref{wxCore}{librarieslist}
+
\wxheading{Event handling}
If the menu is part of a menubar, then \helpref{wxMenuBar}{wxmenubar} event processing is used.
\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}
\helpref{wxMenuBar}{wxmenubar}, \helpref{wxWindow::PopupMenu}{wxwindowpopupmenu},\rtfsp
-\helpref{Event handling overview}{eventhandlingoverview}
+\helpref{Event handling overview}{eventhandlingoverview},\rtfsp
+\helpref{wxFileHistory (most recently used files menu)}{wxfilehistory}
+
+
\latexignore{\rtfignore{\wxheading{Members}}}
+
\membersection{wxMenu::wxMenu}\label{wxmenuctor}
\func{}{wxMenu}{\param{const wxString\& }{title = ""}, \param{long}{ style = 0}}
\docparam{style}{If set to {\tt wxMENU\_TEAROFF}, the menu will be detachable (wxGTK only).}
+
\membersection{wxMenu::\destruct{wxMenu}}\label{wxmenudtor}
\func{}{\destruct{wxMenu}}{\void}
a different window from last time, which causes an implicit destruction
and recreation of internal data structures.
+
\membersection{wxMenu::Append}\label{wxmenuappend}
-\func{wxMenuItem*}{Append}{\param{int}{ id}, \param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""},\rtfsp
+\func{wxMenuItem*}{Append}{\param{int}{ id}, \param{const wxString\& }{ item = ""}, \param{const wxString\& }{helpString = ""},\rtfsp
\param{wxItemKind}{ kind = wxITEM\_NORMAL}}
Adds a string item to the end of the menu.
\helpref{wxMenu::AppendSeparator}{wxmenuappendseparator},\rtfsp
\helpref{wxMenu::AppendCheckItem}{wxmenuappendcheckitem},\rtfsp
\helpref{wxMenu::AppendRadioItem}{wxmenuappendradioitem},\rtfsp
+\helpref{wxMenu::AppendSubMenu}{wxmenuappendsubmenu},\rtfsp
\helpref{wxMenu::Insert}{wxmenuinsert},\rtfsp
\helpref{wxMenu::SetLabel}{wxmenusetlabel}, \helpref{wxMenu::GetHelpString}{wxmenugethelpstring},\rtfsp
\helpref{wxMenu::SetHelpString}{wxmenusethelpstring}, \helpref{wxMenuItem}{wxmenuitem}
\end{twocollist}}
}
+
\membersection{wxMenu::AppendCheckItem}\label{wxmenuappendcheckitem}
\func{wxMenuItem*}{AppendCheckItem}{\param{int}{ id},\rtfsp
\helpref{wxMenu::Append}{wxmenuappend},\rtfsp
\helpref{wxMenu::InsertCheckItem}{wxmenuinsertcheckitem}
+
\membersection{wxMenu::AppendRadioItem}\label{wxmenuappendradioitem}
\func{wxMenuItem*}{AppendRadioItem}{\param{int}{ id},\rtfsp
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{wxMenuItem*}{AppendSeparator}{\void}
\helpref{wxMenu::Append}{wxmenuappend},\rtfsp
\helpref{wxMenu::InsertSeparator}{wxmenuinsertseparator}
+
+\membersection{wxMenu::AppendSubMenu}\label{wxmenuappendsubmenu}
+
+\func{wxMenuItem *}{AppendSubMenu}{\param{wxMenu *}{submenu}, \param{const wxString\& }{text}, \param{const wxString\& }{help = wxEmptyString}}
+
+Adds the given \arg{submenu} to this menu. \arg{text} is the text shown in the
+menu for it and \arg{help} is the help string shown in the status bar when the
+submenu item is selected.
+
+
\membersection{wxMenu::Break}\label{wxmenubreak}
\func{void}{Break}{\void}
Inserts a break in a menu, causing the next appended item to appear in a new column.
+
\membersection{wxMenu::Check}\label{wxmenucheck}
\func{void}{Check}{\param{int}{ id}, \param{const bool}{ check}}
\helpref{wxMenu::IsChecked}{wxmenuischecked}
+
\membersection{wxMenu::Delete}\label{wxmenudelete}
\func{void}{Delete}{\param{int }{id}}
\helpref{wxMenu::Destroy}{wxmenudestroy},\rtfsp
\helpref{wxMenu::Remove}{wxmenuremove}
+
\membersection{wxMenu::Destroy}\label{wxmenudestroy}
\func{void}{Destroy}{\param{int }{id}}
\helpref{wxMenu::Deletes}{wxmenudelete},\rtfsp
\helpref{wxMenu::Remove}{wxmenuremove}
+
\membersection{wxMenu::Enable}\label{wxmenuenable}
\func{void}{Enable}{\param{int}{ id}, \param{const bool}{ enable}}
\helpref{wxMenu::IsEnabled}{wxmenuisenabled}
+
\membersection{wxMenu::FindItem}\label{wxmenufinditem}
\constfunc{int}{FindItem}{\param{const wxString\& }{itemString}}
\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}}
\helpref{wxMenu::SetHelpString}{wxmenusethelpstring}, \helpref{wxMenu::Append}{wxmenuappend}
+
\membersection{wxMenu::GetLabel}\label{wxmenugetlabel}
\constfunc{wxString}{GetLabel}{\param{int}{ id}}
\wxheading{See also}
-\helpref{wxMenu::SetLabel}{wxmenusetlabel}
+\helpref{wxMenu::GetLabelText}{wxmenugetlabeltext}, \helpref{wxMenu::SetLabel}{wxmenusetlabel}
+
+
+\membersection{wxMenu::GetLabelText}\label{wxmenugetlabeltext}
+
+\constfunc{wxString}{GetLabelText}{\param{int}{ id}}
+
+Returns a menu item label, without any of the original mnemonics and accelerators.
+
+\wxheading{Parameters}
+
+\docparam{id}{The menu item identifier.}
+
+\wxheading{Return value}
+
+The item label, or the empty string if the item was not found.
+
+\wxheading{See also}
+
+\helpref{wxMenu::GetLabel}{wxmenugetlabel}, \helpref{wxMenu::SetLabel}{wxmenusetlabel}
\membersection{wxMenu::GetMenuItemCount}\label{wxmenugetmenuitemcount}
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.
+list class containing wxMenuItem pointers, see \helpref{wxList}{wxlist}.
+
\membersection{wxMenu::GetTitle}\label{wxmenugettitle}
\wxheading{Remarks}
This is relevant only to popup menus, use
-\helpref{wxMenuBar::GetLabelTop}{wxmenubargetlabeltop} for the menus in the
+\helpref{wxMenuBar::GetMenuLabel}{wxmenubargetmenulabel} for the menus in the
menubar.
\wxheading{See also}
\helpref{wxMenu::SetTitle}{wxmenusettitle}
+
\membersection{wxMenu::Insert}\label{wxmenuinsert}
\func{wxMenuItem*}{Insert}{\param{size\_t }{pos}, \param{wxMenuItem *}{item}}
\func{wxMenuItem*}{Insert}{\param{size\_t }{pos}, \param{int}{ id},\rtfsp
-\param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""},\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
\helpref{wxMenu::Append}{wxmenuappend},\rtfsp
\helpref{wxMenu::Prepend}{wxmenuprepend}
+
\membersection{wxMenu::InsertCheckItem}\label{wxmenuinsertcheckitem}
\func{wxMenuItem*}{InsertCheckItem}{\param{size\_t }{pos}, \param{int}{ id},\rtfsp
\helpref{wxMenu::Insert}{wxmenuinsert},\rtfsp
\helpref{wxMenu::AppendCheckItem}{wxmenuappendcheckitem}
+
\membersection{wxMenu::InsertRadioItem}\label{wxmenuinsertradioitem}
\func{wxMenuItem*}{InsertRadioItem}{\param{size\_t }{pos}, \param{int}{ id},\rtfsp
\helpref{wxMenu::Insert}{wxmenuinsert},\rtfsp
\helpref{wxMenu::AppendRadioItem}{wxmenuappendradioitem}
+
\membersection{wxMenu::InsertSeparator}\label{wxmenuinsertseparator}
\func{wxMenuItem*}{InsertSeparator}{\param{size\_t }{pos}}
\helpref{wxMenu::Insert}{wxmenuinsert},\rtfsp
\helpref{wxMenu::AppendSeparator}{wxmenuappendseparator}
+
\membersection{wxMenu::IsChecked}\label{wxmenuischecked}
\constfunc{bool}{IsChecked}{\param{int}{ id}}
\helpref{wxMenu::Check}{wxmenucheck}
+
\membersection{wxMenu::IsEnabled}\label{wxmenuisenabled}
\constfunc{bool}{IsEnabled}{\param{int}{ id}}
\helpref{wxMenu::Enable}{wxmenuenable}
+
\membersection{wxMenu::Prepend}\label{wxmenuprepend}
\func{wxMenuItem*}{Prepend}{\param{wxMenuItem *}{item}}
\func{wxMenuItem*}{Prepend}{\param{int}{ id},\rtfsp
-\param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""},\rtfsp
+\param{const wxString\& }{ item = ""}, \param{const wxString\& }{helpString = ""},\rtfsp
\param{wxItemKind}{ kind = wxITEM\_NORMAL}}
Inserts the given {\it item} at position $0$, i.e. before all the other
\helpref{wxMenu::Append}{wxmenuappend},\rtfsp
\helpref{wxMenu::Insert}{wxmenuinsert}
+
\membersection{wxMenu::PrependCheckItem}\label{wxmenuprependcheckitem}
\func{wxMenuItem*}{PrependCheckItem}{\param{int}{ id},\rtfsp
\helpref{wxMenu::Prepend}{wxmenuprepend},\rtfsp
\helpref{wxMenu::AppendCheckItem}{wxmenuappendcheckitem}
+
\membersection{wxMenu::PrependRadioItem}\label{wxmenuprependradioitem}
\func{wxMenuItem*}{PrependRadioItem}{\param{int}{ id},\rtfsp
\helpref{wxMenu::Prepend}{wxmenuprepend},\rtfsp
\helpref{wxMenu::AppendRadioItem}{wxmenuappendradioitem}
+
\membersection{wxMenu::PrependSeparator}\label{wxmenuprependseparator}
\func{wxMenuItem*}{PrependSeparator}{\void}
\helpref{wxMenu::Prepend}{wxmenuprepend},\rtfsp
\helpref{wxMenu::AppendSeparator}{wxmenuappendseparator}
+
\membersection{wxMenu::Remove}\label{wxmenuremove}
\func{wxMenuItem *}{Remove}{\param{int }{id}}
The item which was detached from the menu.
+
\membersection{wxMenu::SetHelpString}\label{wxmenusethelpstring}
\func{void}{SetHelpString}{\param{int}{ id}, \param{const wxString\& }{helpString}}
\helpref{wxMenu::GetHelpString}{wxmenugethelpstring}
+
\membersection{wxMenu::SetLabel}\label{wxmenusetlabel}
\func{void}{SetLabel}{\param{int}{ id}, \param{const wxString\& }{label}}
\helpref{wxMenu::Append}{wxmenuappend}, \helpref{wxMenu::GetLabel}{wxmenugetlabel}
+
\membersection{wxMenu::SetTitle}\label{wxmenusettitle}
\func{void}{SetTitle}{\param{const wxString\& }{title}}
\helpref{wxMenu::GetTitle}{wxmenugettitle}
+
\membersection{wxMenu::UpdateUI}\label{wxmenuupdateui}
\constfunc{void}{UpdateUI}{\param{wxEvtHandler*}{ source = NULL}}
<wx/menu.h>
+\wxheading{Library}
+
+\helpref{wxCore}{librarieslist}
+
\wxheading{Event handling}
To respond to a menu selection, provide a handler for EVT\_MENU, in the frame
\latexignore{\rtfignore{\wxheading{Members}}}
+
\membersection{wxMenuBar::wxMenuBar}\label{wxmenubarctor}
\func{}{wxMenuBar}{\param{long }{style = 0}}
Default constructor.
-\func{}{wxMenuBar}{\param{int}{ n}, \param{wxMenu*}{ menus[]}, \param{const wxString }{titles[]}}
+\func{}{wxMenuBar}{\param{size\_t}{ n}, \param{wxMenu*}{ menus[]}, \param{const wxString }{titles[]}, \param{long }{style = 0}}
Construct a menu bar from arrays of menus and titles.
\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.}
+Use \helpref{wxMenuBar::Append}{wxmenubarappend} instead.}
\perlnote{wxPerl only supports the first constructor:
-use {\tt Append} instead.}
+use \helpref{wxMenuBar::Append}{wxmenubarappend} instead.}
+
\membersection{wxMenuBar::\destruct{wxMenuBar}}\label{wxmenubardtor}
Destructor, destroying the menu bar and removing it from the parent frame (if any).
+
\membersection{wxMenuBar::Append}\label{wxmenubarappend}
\func{bool}{Append}{\param{wxMenu *}{menu}, \param{const wxString\& }{title}}
\helpref{wxMenuBar::Insert}{wxmenubarinsert}
+
\membersection{wxMenuBar::Check}\label{wxmenubarcheck}
\func{void}{Check}{\param{int}{ id}, \param{const bool}{ check}}
Only use this when the menu bar has been associated
with a frame; otherwise, use the wxMenu equivalent call.
+
\membersection{wxMenuBar::Enable}\label{wxmenubarenable}
\func{void}{Enable}{\param{int}{ id}, \param{const bool}{ enable}}
Only use this when the menu bar has been
associated with a frame; otherwise, use the wxMenu equivalent call.
+
\membersection{wxMenuBar::EnableTop}\label{wxmenubarenabletop}
\func{void}{EnableTop}{\param{int}{ pos}, \param{const bool}{ enable}}
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}}
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}}
Any special menu codes are stripped out of source and target strings
before matching.
+
\membersection{wxMenuBar::FindItem}\label{wxmenubarfinditem}
\constfunc{wxMenuItem *}{FindItem}{\param{int}{ id}, \param{wxMenu}{ **menu = NULL}}
The found menu item object, or NULL if one was not found.
+
\membersection{wxMenuBar::GetHelpString}\label{wxmenubargethelpstring}
\constfunc{wxString}{GetHelpString}{\param{int}{ id}}
\helpref{wxMenuBar::SetHelpString}{wxmenubarsethelpstring}
+
\membersection{wxMenuBar::GetLabel}\label{wxmenubargetlabel}
\constfunc{wxString}{GetLabel}{\param{int}{ id}}
Use only after the menubar has been associated with a frame.
+
\membersection{wxMenuBar::GetLabelTop}\label{wxmenubargetlabeltop}
\constfunc{wxString}{GetLabelTop}{\param{int}{ pos}}
Use only after the menubar has been associated with a frame.
+This function is deprecated in favour of \helpref{GetMenuLabel}{wxmenubargetmenulabel} and \helpref{GetMenuLabelText}{wxmenubargetmenulabeltext}.
+
\wxheading{See also}
\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}
+\constfunc{size\_t}{GetMenuCount}{\void}
Returns the number of menus in this menubar.
+
+\membersection{wxMenuBar::GetMenuLabel}\label{wxmenubargetmenulabel}
+
+\constfunc{wxString}{GetMenuLabel}{\param{int}{ pos}}
+
+Returns the label of a top-level menu. Note that the returned string
+includes the accelerator characters that have been specified in the menu
+title string during its construction.
+
+\wxheading{Parameters}
+
+\docparam{pos}{Position of the menu on the menu bar, starting from zero.}
+
+\wxheading{Return value}
+
+The menu label, or the empty string if the menu was not found.
+
+\wxheading{Remarks}
+
+Use only after the menubar has been associated with a frame.
+
+\wxheading{See also}
+
+\helpref{wxMenuBar::GetMenuLabelText}{wxmenubargetmenulabeltext}, \helpref{wxMenuBar::SetMenuLabel}{wxmenubarsetmenulabel}
+
+
+\membersection{wxMenuBar::GetMenuLabelText}\label{wxmenubargetmenulabeltext}
+
+\constfunc{wxString}{GetMenuLabelText}{\param{int}{ pos}}
+
+Returns the label of a top-level menu. Note that the returned string does not
+include any accelerator characters that may have been specified in the menu
+title string during its construction.
+
+\wxheading{Parameters}
+
+\docparam{pos}{Position of the menu on the menu bar, starting from zero.}
+
+\wxheading{Return value}
+
+The menu label, or the empty string if the menu was not found.
+
+\wxheading{Remarks}
+
+Use only after the menubar has been associated with a frame.
+
+\wxheading{See also}
+
+\helpref{wxMenuBar::GetMenuLabel}{wxmenubargetmenulabel}, \helpref{wxMenuBar::SetMenuLabel}{wxmenubarsetmenulabel}
+
+
\membersection{wxMenuBar::Insert}\label{wxmenubarinsert}
\func{bool}{Insert}{\param{size\_t }{pos}, \param{wxMenu *}{menu}, \param{const wxString\& }{title}}
\helpref{wxMenuBar::Append}{wxmenubarappend}
+
\membersection{wxMenuBar::IsChecked}\label{wxmenubarischecked}
\constfunc{bool}{IsChecked}{\param{int}{ id}}
true if the item was found and is checked, false otherwise.
+
\membersection{wxMenuBar::IsEnabled}\label{wxmenubarisenabled}
\constfunc{bool}{IsEnabled}{\param{int}{ id}}
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}}
\helpref{wxMenuBar::Replace}{wxmenubarreplace}
+
\membersection{wxMenuBar::Replace}\label{wxmenubarreplace}
\func{wxMenu *}{Replace}{\param{size\_t }{pos}, \param{wxMenu *}{menu}, \param{const wxString\& }{title}}
\helpref{wxMenuBar::Insert}{wxmenubarinsert},\rtfsp
\helpref{wxMenuBar::Remove}{wxmenubarremove}
+
\membersection{wxMenuBar::SetHelpString}\label{wxmenubarsethelpstring}
\func{void}{SetHelpString}{\param{int}{ id}, \param{const wxString\& }{helpString}}
\helpref{wxMenuBar::GetHelpString}{wxmenubargethelpstring}
+
\membersection{wxMenuBar::SetLabel}\label{wxmenubarsetlabel}
\func{void}{SetLabel}{\param{int}{ id}, \param{const wxString\& }{label}}
\helpref{wxMenuBar::GetLabel}{wxmenubargetlabel}
+
\membersection{wxMenuBar::SetLabelTop}\label{wxmenubarsetlabeltop}
\func{void}{SetLabelTop}{\param{int}{ pos}, \param{const wxString\& }{label}}
Use only after the menubar has been associated with a frame.
+This function has been deprecated in favour of \helpref{SetMenuLabel}{wxmenubarsetmenulabel}.
+
\wxheading{See also}
\helpref{wxMenuBar::GetLabelTop}{wxmenubargetlabeltop}
+
+\membersection{wxMenuBar::SetMenuLabel}\label{wxmenubarsetmenulabel}
+
+\func{void}{SetMenuLabel}{\param{int}{ pos}, \param{const wxString\& }{label}}
+
+Sets the label of a top-level menu.
+
+\wxheading{Parameters}
+
+\docparam{pos}{The position of a menu on the menu bar, starting from zero.}
+
+\docparam{label}{The menu label.}
+
+\wxheading{Remarks}
+
+Use only after the menubar has been associated with a frame.
+
+\wxheading{See also}
+
+\helpref{wxMenuBar::GetMenuLabel}{wxmenubargetmenulabel}, \helpref{wxMenuBar::GetMenuLabelText}{wxmenubargetmenulabeltext}
+
projects / wxWidgets.git / blobdiff