294ea16de3
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@32880 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
1074 lines
32 KiB
TeX
1074 lines
32 KiB
TeX
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%% 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
|
|
selected before the menu goes away (clicking elsewhere dismisses the
|
|
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. 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.
|
|
|
|
{\bf NB:} Please note that {\it wxID\_ABOUT} and {\it wxID\_EXIT} are
|
|
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). 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
|
|
associated to them and they show a checkmark in the menu when the flag is set.
|
|
wxWidgets 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 radio items
|
|
are not supported under Motif.
|
|
|
|
\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}
|
|
|
|
\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.
|
|
|
|
With a popup menu, there is a variety of ways to handle a menu selection event
|
|
(wxEVT\_COMMAND\_MENU\_SELECTED).
|
|
|
|
\begin{enumerate}\itemsep=0pt
|
|
\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}
|
|
|
|
\helpref{wxMenuBar}{wxmenubar}, \helpref{wxWindow::PopupMenu}{wxwindowpopupmenu},\rtfsp
|
|
\helpref{Event handling overview}{eventhandlingoverview}
|
|
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
\membersection{wxMenu::wxMenu}\label{wxmenuctor}
|
|
|
|
\func{}{wxMenu}{\param{const wxString\& }{title = ""}, \param{long}{ style = 0}}
|
|
|
|
Constructs a wxMenu object.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\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 (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}}\label{wxmenudtor}
|
|
|
|
\func{}{\destruct{wxMenu}}{\void}
|
|
|
|
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{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.
|
|
|
|
\func{wxMenuItem*}{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. Append the submenu to the parent
|
|
menu {\it after} you have added your menu items, or accelerators may not be
|
|
registered properly.
|
|
|
|
\func{wxMenuItem*}{Append}{\param{wxMenuItem*}{ menuItem}}
|
|
|
|
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}
|
|
|
|
\docparam{id}{The menu command identifier.}
|
|
|
|
\docparam{item}{The string to appear on the menu item.}
|
|
|
|
\docparam{menu}{Pull-right submenu.}
|
|
|
|
\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, the handler for the wxEVT\_MENU\_HIGHLIGHT event displays
|
|
this string in the status line.}
|
|
|
|
\docparam{menuItem}{A menuitem object. It will be owned by the wxMenu object after this function
|
|
is called, so do not delete it yourself.}
|
|
|
|
\wxheading{Remarks}
|
|
|
|
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
|
|
\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:
|
|
|
|
\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::AppendCheckItem}\label{wxmenuappendcheckitem}
|
|
|
|
\func{wxMenuItem*}{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{wxMenuItem*}{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{wxMenuItem*}{AppendSeparator}{\void}
|
|
|
|
Adds a separator to the end of the menu.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxMenu::Append}{wxmenuappend},\rtfsp
|
|
\helpref{wxMenu::InsertSeparator}{wxmenuinsertseparator}
|
|
|
|
\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}}
|
|
|
|
Checks or unchecks the menu item.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{id}{The menu item identifier.}
|
|
|
|
\docparam{check}{If true, the item will be checked, otherwise it will be unchecked.}
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxMenu::IsChecked}{wxmenuischecked}
|
|
|
|
\membersection{wxMenu::Delete}\label{wxmenudelete}
|
|
|
|
\func{void}{Delete}{\param{int }{id}}
|
|
|
|
\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}{Id of the menu item to be deleted.}
|
|
|
|
\docparam{item}{Menu item to be deleted.}
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxMenu::FindItem}{wxmenufinditem},\rtfsp
|
|
\helpref{wxMenu::Destroy}{wxmenudestroy},\rtfsp
|
|
\helpref{wxMenu::Remove}{wxmenuremove}
|
|
|
|
\membersection{wxMenu::Destroy}\label{wxmenudestroy}
|
|
|
|
\func{void}{Destroy}{\param{int }{id}}
|
|
|
|
\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{id}{Id of the menu item to be deleted.}
|
|
|
|
\docparam{item}{Menu item to be deleted.}
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxMenu::FindItem}{wxmenufinditem},\rtfsp
|
|
\helpref{wxMenu::Deletes}{wxmenudelete},\rtfsp
|
|
\helpref{wxMenu::Remove}{wxmenuremove}
|
|
|
|
\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::IsEnabled}{wxmenuisenabled}
|
|
|
|
\membersection{wxMenu::FindItem}\label{wxmenufinditem}
|
|
|
|
\constfunc{int}{FindItem}{\param{const wxString\& }{itemString}}
|
|
|
|
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 {\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 item's
|
|
parent menu (if the item was found)}
|
|
|
|
\wxheading{Return value}
|
|
|
|
First form: menu item identifier, or {\tt wxNOT\_FOUND} if none is found.
|
|
|
|
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.
|
|
|
|
\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}}
|
|
|
|
Returns the help string associated with a menu item.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{id}{The menu item identifier.}
|
|
|
|
\wxheading{Return value}
|
|
|
|
The help string, or the empty string if there is no help string or the
|
|
item was not found.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxMenu::SetHelpString}{wxmenusethelpstring}, \helpref{wxMenu::Append}{wxmenuappend}
|
|
|
|
\membersection{wxMenu::GetLabel}\label{wxmenugetlabel}
|
|
|
|
\constfunc{wxString}{GetLabel}{\param{int}{ id}}
|
|
|
|
Returns a menu item label.
|
|
|
|
\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::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}
|
|
|
|
Returns the title of the menu.
|
|
|
|
\wxheading{Remarks}
|
|
|
|
This is relevant only to popup menus, use
|
|
\helpref{wxMenuBar::GetLabelTop}{wxmenubargetlabeltop} 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{wxItemKind}{ kind = wxITEM\_NORMAL}}
|
|
|
|
Inserts the given {\it item} before the position {\it pos}. Inserting the item
|
|
at position \helpref{GetMenuItemCount}{wxmenugetmenuitemcount} is the same
|
|
as appending it.
|
|
|
|
\wxheading{See also}
|
|
|
|
\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
|
|
\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{wxMenuItem*}{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{wxMenuItem*}{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}
|
|
|
|
\constfunc{bool}{IsChecked}{\param{int}{ id}}
|
|
|
|
Determines whether a menu item is checked.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{id}{The menu item identifier.}
|
|
|
|
\wxheading{Return value}
|
|
|
|
true if the menu item is checked, false otherwise.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxMenu::Check}{wxmenucheck}
|
|
|
|
\membersection{wxMenu::IsEnabled}\label{wxmenuisenabled}
|
|
|
|
\constfunc{bool}{IsEnabled}{\param{int}{ id}}
|
|
|
|
Determines whether a menu item is enabled.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{id}{The menu item identifier.}
|
|
|
|
\wxheading{Return value}
|
|
|
|
true if the menu item is enabled, false otherwise.
|
|
|
|
\wxheading{See also}
|
|
|
|
\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{wxItemKind}{ kind = wxITEM\_NORMAL}}
|
|
|
|
Inserts the given {\it item} at position $0$, i.e. before all the other
|
|
existing items.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxMenu::Append}{wxmenuappend},\rtfsp
|
|
\helpref{wxMenu::Insert}{wxmenuinsert}
|
|
|
|
\membersection{wxMenu::PrependCheckItem}\label{wxmenuprependcheckitem}
|
|
|
|
\func{wxMenuItem*}{PrependCheckItem}{\param{int}{ id},\rtfsp
|
|
\param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""}}
|
|
|
|
Inserts a checkable item at position $0$.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxMenu::Prepend}{wxmenuprepend},\rtfsp
|
|
\helpref{wxMenu::AppendCheckItem}{wxmenuappendcheckitem}
|
|
|
|
\membersection{wxMenu::PrependRadioItem}\label{wxmenuprependradioitem}
|
|
|
|
\func{wxMenuItem*}{PrependRadioItem}{\param{int}{ id},\rtfsp
|
|
\param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""}}
|
|
|
|
Inserts a radio item at position $0$.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxMenu::Prepend}{wxmenuprepend},\rtfsp
|
|
\helpref{wxMenu::AppendRadioItem}{wxmenuappendradioitem}
|
|
|
|
\membersection{wxMenu::PrependSeparator}\label{wxmenuprependseparator}
|
|
|
|
\func{wxMenuItem*}{PrependSeparator}{\void}
|
|
|
|
Inserts a separator at 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}}
|
|
|
|
\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{int}{ id}, \param{const wxString\& }{helpString}}
|
|
|
|
Sets an item's help string.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{id}{The menu item identifier.}
|
|
|
|
\docparam{helpString}{The help string to set.}
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxMenu::GetHelpString}{wxmenugethelpstring}
|
|
|
|
\membersection{wxMenu::SetLabel}\label{wxmenusetlabel}
|
|
|
|
\func{void}{SetLabel}{\param{int}{ id}, \param{const wxString\& }{label}}
|
|
|
|
Sets the label of a menu item.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{id}{The menu item identifier.}
|
|
|
|
\docparam{label}{The menu item label to set.}
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxMenu::Append}{wxmenuappend}, \helpref{wxMenu::GetLabel}{wxmenugetlabel}
|
|
|
|
\membersection{wxMenu::SetTitle}\label{wxmenusettitle}
|
|
|
|
\func{void}{SetTitle}{\param{const wxString\& }{title}}
|
|
|
|
Sets the title of the menu.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{title}{The title to set.}
|
|
|
|
\wxheading{Remarks}
|
|
|
|
This is relevant only to popup menus, use
|
|
\helpref{wxMenuBar::SetLabelTop}{wxmenubarsetlabeltop} for the menus in the
|
|
menubar.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxMenu::GetTitle}{wxmenugettitle}
|
|
|
|
\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.
|
|
|
|
\wxheading{Derived from}
|
|
|
|
\helpref{wxWindow}{wxwindow}\\
|
|
\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. 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.
|
|
|
|
{\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}
|
|
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
\membersection{wxMenuBar::wxMenuBar}\label{wxmenubarctor}
|
|
|
|
\func{}{wxMenuBar}{\param{long }{style = 0}}
|
|
|
|
Default constructor.
|
|
|
|
\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.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{n}{The number of menus.}
|
|
|
|
\docparam{menus}{An array of menus. Do not use this array again - it now belongs to the
|
|
menu bar.}
|
|
|
|
\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 \helpref{wxMenuBar::Append}{wxmenubarappend} instead.}
|
|
|
|
\perlnote{wxPerl only supports the first constructor:
|
|
use \helpref{wxMenuBar::Append}{wxmenubarappend} instead.}
|
|
|
|
\membersection{wxMenuBar::\destruct{wxMenuBar}}\label{wxmenubardtor}
|
|
|
|
\func{void}{\destruct{wxMenuBar}}{\void}
|
|
|
|
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}}
|
|
|
|
Adds the item to the end of the menu bar.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{menu}{The menu to add. Do not deallocate this menu after calling {\bf Append}.}
|
|
|
|
\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{int}{ id}, \param{const bool}{ check}}
|
|
|
|
Checks or unchecks a menu item.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{id}{The menu item identifier.}
|
|
|
|
\docparam{check}{If true, checks the menu item, otherwise the item is unchecked.}
|
|
|
|
\wxheading{Remarks}
|
|
|
|
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}}
|
|
|
|
Enables or disables (greys out) a menu item.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{id}{The menu item identifier.}
|
|
|
|
\docparam{enable}{true to enable the item, false to disable it.}
|
|
|
|
\wxheading{Remarks}
|
|
|
|
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}}
|
|
|
|
Enables or disables a whole menu.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{pos}{The position of the menu, starting from zero.}
|
|
|
|
\docparam{enable}{true to enable the menu, false to disable it.}
|
|
|
|
\wxheading{Remarks}
|
|
|
|
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 {\tt 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}}
|
|
|
|
Finds the menu item id for a menu name/menu item string pair.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{menuString}{Menu title to find.}
|
|
|
|
\docparam{itemString}{Item to find.}
|
|
|
|
\wxheading{Return value}
|
|
|
|
The menu item identifier, or {\tt wxNOT\_FOUND} if none was found.
|
|
|
|
\wxheading{Remarks}
|
|
|
|
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}}
|
|
|
|
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{int}{ id}}
|
|
|
|
Gets the help string associated with the menu item identifier.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{id}{The menu item identifier.}
|
|
|
|
\wxheading{Return value}
|
|
|
|
The help string, or the empty string if there was no help string or the menu item
|
|
was not found.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxMenuBar::SetHelpString}{wxmenubarsethelpstring}
|
|
|
|
\membersection{wxMenuBar::GetLabel}\label{wxmenubargetlabel}
|
|
|
|
\constfunc{wxString}{GetLabel}{\param{int}{ id}}
|
|
|
|
Gets the label associated with a menu item.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{id}{The menu item identifier.}
|
|
|
|
\wxheading{Return value}
|
|
|
|
The menu item label, or the empty string if the item was not found.
|
|
|
|
\wxheading{Remarks}
|
|
|
|
Use only after the menubar has been associated with a frame.
|
|
|
|
\membersection{wxMenuBar::GetLabelTop}\label{wxmenubargetlabeltop}
|
|
|
|
\constfunc{wxString}{GetLabelTop}{\param{int}{ pos}}
|
|
|
|
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}
|
|
|
|
\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::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{int}{ id}}
|
|
|
|
Determines whether an item is checked.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{id}{The menu item identifier.}
|
|
|
|
\wxheading{Return value}
|
|
|
|
true if the item was found and is checked, false otherwise.
|
|
|
|
\membersection{wxMenuBar::IsEnabled}\label{wxmenubarisenabled}
|
|
|
|
\constfunc{bool}{IsEnabled}{\param{int}{ id}}
|
|
|
|
Determines whether an item is enabled.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{id}{The menu item identifier.}
|
|
|
|
\wxheading{Return value}
|
|
|
|
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 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{int}{ id}, \param{const wxString\& }{helpString}}
|
|
|
|
Sets the help string associated with a menu item.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{id}{Menu item identifier.}
|
|
|
|
\docparam{helpString}{Help string to associate with the menu item.}
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxMenuBar::GetHelpString}{wxmenubargethelpstring}
|
|
|
|
\membersection{wxMenuBar::SetLabel}\label{wxmenubarsetlabel}
|
|
|
|
\func{void}{SetLabel}{\param{int}{ id}, \param{const wxString\& }{label}}
|
|
|
|
Sets the label of a menu item.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{id}{Menu item identifier.}
|
|
|
|
\docparam{label}{Menu item label.}
|
|
|
|
\wxheading{Remarks}
|
|
|
|
Use only after the menubar has been associated with a frame.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxMenuBar::GetLabel}{wxmenubargetlabel}
|
|
|
|
\membersection{wxMenuBar::SetLabelTop}\label{wxmenubarsetlabeltop}
|
|
|
|
\func{void}{SetLabelTop}{\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::GetLabelTop}{wxmenubargetlabeltop}
|
|
|