1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 2%% Name: menuitem.tex 3%% Purpose: wxMenuItem documentation 4%% Author: wxWidgets Team 5%% Modified by: 6%% Created: 7%% RCS-ID: $Id: menuitem.tex 48054 2007-08-13 17:18:08Z JS $ 8%% Copyright: (c) wxWidgets Team 9%% License: wxWindows license 10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 11 12\section{\class{wxMenuItem}}\label{wxmenuitem} 13 14A menu item represents an item in a menu. Note that you usually don't have to 15deal with it directly as \helpref{wxMenu}{wxmenu} methods usually construct an 16object of this class for you. 17 18Also please note that the methods related to fonts and bitmaps are currently 19only implemented for Windows and GTK+. 20 21\wxheading{Derived from} 22 23% add wxOwnerDrawn once it is documented 24\helpref{wxObject}{wxobject} 25 26\wxheading{Include files} 27 28<wx/menuitem.h> 29 30\wxheading{See also} 31 32\helpref{wxMenuBar}{wxmenubar}, \helpref{wxMenu}{wxmenu} 33 34\latexignore{\rtfignore{\wxheading{Members}}} 35 36 37\membersection{wxMenuItem::wxMenuItem}\label{wxmenuitemctor} 38 39\func{}{wxMenuItem}{\param{wxMenu*}{ parentMenu = NULL}, \param{int}{ id = wxID\_SEPARATOR}, 40 \param{const wxString\& }{text = ""}, \param{const wxString\& }{helpString = ""}, 41 \param{wxItemKind }{kind = wxITEM\_NORMAL}, \param{wxMenu*}{ subMenu = NULL}} 42 43Constructs a wxMenuItem object. 44 45Menu items can be standard, or ``stock menu items'', or custom. For the 46standard menu items (such as commands to open a file, exit the program and so 47on, see \helpref{stock items}{stockitems} for the full list) it is enough to 48specify just the stock ID and leave \arg{text} and \arg{helpString} empty. In 49fact, leaving at least \arg{text} empty for the stock menu items is strongly 50recommended as they will have appearance and keyboard interface (including 51standard accelerators) familiar to the user. 52 53For the custom (non-stock) menu items, \arg{text} must be specified and while 54\arg{helpString} may be left empty, it's recommended to pass the item 55description (which is automatically shown by the library in the status bar when 56the menu item is selected) in this parameter. 57 58Finally note that you can e.g. use a stock menu label without using its stock 59help string: 60 61\begin{verbatim} 62// use all stock properties: 63helpMenu->Append(wxID_ABOUT); 64 65// use the stock label and the stock accelerator but not the stock help string: 66helpMenu->Append(wxID_ABOUT, wxEmptyString, wxT("My custom help string")); 67 68// use all stock properties except for the bitmap: 69wxMenuItem *mymenu = new wxMenuItem(helpMenu, wxID_ABOUT); 70mymenu->SetBitmap(wxArtProvider::GetBitmap(wxART_WARNING)); 71helpMenu->Append(mymenu); 72\end{verbatim} 73 74that is, stock properties are set independently one from the other. 75 76\wxheading{Parameters} 77 78\docparam{parentMenu}{Menu that the menu item belongs to.} 79 80\docparam{id}{Identifier for this menu item, or wxID\_SEPARATOR to indicate a separator.} 81 82\docparam{text}{Text for the menu item, as shown on the menu. An accelerator 83key can be specified using the ampersand '\&' character. In order to embed an 84ampersand character in the menu item text, the ampersand must be doubled.} 85 86\docparam{helpString}{Optional help string that will be shown on the status bar.} 87 88\docparam{kind}{May be {\tt wxITEM\_SEPARATOR}, {\tt wxITEM\_NORMAL}, 89{\tt wxITEM\_CHECK} or {\tt wxITEM\_RADIO}} 90 91\docparam{subMenu}{If non-NULL, indicates that the menu item is a submenu.} 92 93 94\membersection{wxMenuItem::\destruct{wxMenuItem}}\label{wxmenuitemdtor} 95 96\func{}{\destruct{wxMenuItem}}{\void} 97 98Destructor. 99 100 101\membersection{wxMenuItem::Check}\label{wxmenuitemcheck} 102 103\func{void}{Check}{\param{bool}{ check = true}} 104 105Checks or unchecks the menu item. 106 107Note that this only works when the item is already appended to a menu. 108 109 110\membersection{wxMenuItem::Enable}\label{wxmenuitemenable} 111 112\func{void}{Enable}{\param{bool}{ enable = true}} 113 114Enables or disables the menu item. 115 116 117\membersection{wxMenuItem::GetBackgroundColour}\label{wxmenuitemgetbackgroundcolour} 118 119\constfunc{wxColour\&}{GetBackgroundColour}{\void} 120 121Returns the background colour associated with the menu item (Windows only). 122 123 124\membersection{wxMenuItem::GetBitmap}\label{wxmenuitemgetbitmap} 125 126\constfunc{wxBitmap\&}{GetBitmap}{\param{bool}{ checked = true}} 127 128Returns the checked or unchecked bitmap (Windows only). 129 130 131\membersection{wxMenuItem::GetFont}\label{wxmenuitemgetfont} 132 133\constfunc{wxFont\&}{GetFont}{\void} 134 135Returns the font associated with the menu item (Windows only). 136 137 138\membersection{wxMenuItem::GetHelp}\label{wxmenuitemgethelp} 139 140\constfunc{wxString}{GetHelp}{\void} 141 142Returns the help string associated with the menu item. 143 144 145\membersection{wxMenuItem::GetId}\label{wxmenuitemgetid} 146 147\constfunc{int}{GetId}{\void} 148 149Returns the menu item identifier. 150 151\membersection{wxMenuItem::GetItemLabel}\label{wxmenuitemgetitemlabel} 152 153\constfunc{wxString}{GetItemLabel}{\void} 154 155Returns the text associated with the menu item including any accelerator 156characters that were passed to the constructor or SetItemLabel. 157 158\wxheading{See also} 159 160\helpref{GetItemLabelText}{wxmenuitemgetitemlabeltext}, 161\helpref{GetLabelText}{wxmenuitemgetlabeltext} 162 163 164\membersection{wxMenuItem::GetItemLabelText}\label{wxmenuitemgetitemlabeltext} 165 166\constfunc{wxString}{GetItemLabelText}{\void} 167 168Returns the text associated with the menu item, without any accelerator 169characters. 170 171\wxheading{See also} 172 173\helpref{GetItemLabel}{wxmenuitemgetitemlabel}, 174\helpref{GetLabelText}{wxmenuitemgetlabeltext} 175 176 177\membersection{wxMenuItem::GetKind}\label{wxmenuitemgetkind} 178 179\constfunc{wxItemKind}{GetKind}{\void} 180 181Returns the item kind, one of {\tt wxITEM\_SEPARATOR}, {\tt wxITEM\_NORMAL}, 182{\tt wxITEM\_CHECK} or {\tt wxITEM\_RADIO}. 183 184 185\membersection{wxMenuItem::GetLabel}\label{wxmenuitemgetlabel} 186 187\constfunc{wxString}{GetLabel}{\void} 188 189Returns the text associated with the menu item without any accelerator 190characters it might contain. 191 192This function is deprecated in favour of \helpref{GetItemLabelText}{wxmenuitemgetitemlabeltext}. 193 194\wxheading{See also} 195 196\helpref{GetText}{wxmenuitemgettext}, 197\helpref{GetLabelFromText}{wxmenuitemgetlabelfromtext} 198 199 200\membersection{wxMenuItem::GetLabelText}\label{wxmenuitemgetlabeltext} 201 202\func{static wxString}{GetLabelText}{\param{const wxString\& }{text}} 203 204Strips all accelerator characters and mnemonics from the given {\it text}. 205For example, 206 207\begin{verbatim} 208wxMenuItem::GetLabelFromText("&Hello\tCtrl-H"); 209\end{verbatim} 210 211will return just {\tt "Hello"}. 212 213\wxheading{See also} 214 215\helpref{GetItemLabelText}{wxmenuitemgetitemlabeltext}, 216\helpref{GetItemLabel}{wxmenuitemgetitemlabel} 217 218 219\membersection{wxMenuItem::GetLabelFromText}\label{wxmenuitemgetlabelfromtext} 220 221\func{static wxString}{GetLabelFromText}{\param{const wxString\& }{text}} 222 223Strips all accelerator characters and mnemonics from the given {\it text}. 224For example, 225 226\begin{verbatim} 227wxMenuItem::GetLabelFromText("&Hello\tCtrl-H"); 228\end{verbatim} 229 230will return just {\tt "Hello"}. 231 232This function is deprecated; please use \helpref{wxMenuItem::GetLabelText}{wxmenuitemgetlabeltext} instead. 233 234\wxheading{See also} 235 236\helpref{GetText}{wxmenuitemgettext}, 237\helpref{GetLabel}{wxmenuitemgetlabel} 238 239\membersection{wxMenuItem::GetMarginWidth}\label{wxmenuitemgetmarginwidth} 240 241\constfunc{int}{GetMarginWidth}{\void} 242 243Gets the width of the menu item checkmark bitmap (Windows only). 244 245 246\membersection{wxMenuItem::GetMenu}\label{wxmenuitemgetmenu} 247 248\constfunc{wxMenu*}{GetMenu}{\void} 249 250Returns the menu this menu item is in, or NULL if this menu item is not attached. 251 252 253\membersection{wxMenuItem::GetName}\label{wxmenuitemgetname} 254 255\constfunc{wxString}{GetName}{\void} 256 257Returns the text associated with the menu item. 258 259{\bf NB:} this function is deprecated, please use 260\helpref{GetItemLabel}{wxmenuitemgetitemlabel} or \helpref{GetItemLabelText}{wxmenuitemgetitemlabeltext} 261instead. 262 263 264\membersection{wxMenuItem::GetText}\label{wxmenuitemgettext} 265 266\constfunc{wxString}{GetText}{\void} 267 268Returns the text associated with the menu item, such as it was passed to the 269wxMenuItem constructor, i.e. with any accelerator characters it may contain. 270 271This function is deprecated in favour of \helpref{GetItemLabel}{wxmenuitemgetitemlabel}. 272 273\wxheading{See also} 274 275\helpref{GetLabel}{wxmenuitemgetlabel}, 276\helpref{GetLabelFromText}{wxmenuitemgetlabelfromtext} 277 278 279\membersection{wxMenuItem::GetSubMenu}\label{wxmenuitemgetsubmenu} 280 281\constfunc{wxMenu*}{GetSubMenu}{\void} 282 283Returns the submenu associated with the menu item, or NULL if there isn't one. 284 285 286\membersection{wxMenuItem::GetTextColour}\label{wxmenuitemgettextcolour} 287 288\constfunc{wxColour\&}{GetTextColour}{\void} 289 290Returns the text colour associated with the menu item (Windows only). 291 292 293\membersection{wxMenuItem::IsCheckable}\label{wxmenuitemischeckable} 294 295\constfunc{bool}{IsCheckable}{\void} 296 297Returns true if the item is checkable. 298 299 300\membersection{wxMenuItem::IsChecked}\label{wxmenuitemischecked} 301 302\constfunc{bool}{IsChecked}{\void} 303 304Returns true if the item is checked. 305 306 307\membersection{wxMenuItem::IsEnabled}\label{wxmenuitemisenabled} 308 309\constfunc{bool}{IsEnabled}{\void} 310 311Returns true if the item is enabled. 312 313 314\membersection{wxMenuItem::IsSeparator}\label{wxmenuitemisseparator} 315 316\constfunc{bool}{IsSeparator}{\void} 317 318Returns true if the item is a separator. 319 320 321\membersection{wxMenuItem::IsSubMenu}\label{wxmenuitemissubmenu} 322 323\constfunc{bool}{IsSubMenu}{\void} 324 325Returns true if the item is a submenu. 326 327 328\membersection{wxMenuItem::SetBackgroundColour}\label{wxmenuitemsetbackgroundcolour} 329 330\constfunc{void}{SetBackgroundColour}{\param{const wxColour\& }{colour}} 331 332Sets the background colour associated with the menu item (Windows only). 333 334 335\membersection{wxMenuItem::SetBitmap}\label{wxmenuitemsetbitmap} 336 337\func{void}{SetBitmap}{\param{const wxBitmap\& }{bmp}} 338 339Sets the bitmap for the menu item (Windows and GTK+ only). It is 340equivalent to \helpref{SetBitmaps}{wxmenuitemsetbitmaps}(bmp, wxNullBitmap). 341 342 343\membersection{wxMenuItem::SetBitmaps}\label{wxmenuitemsetbitmaps} 344 345\func{void}{SetBitmaps}{\param{const wxBitmap\& }{checked}, 346 \param{const wxBitmap\& }{unchecked = wxNullBitmap}} 347 348Sets the checked/unchecked bitmaps for the menu item (Windows only). The first bitmap 349is also used as the single bitmap for uncheckable menu items. 350 351 352\membersection{wxMenuItem::SetFont}\label{wxmenuitemsetfont} 353 354\func{void}{SetFont}{\param{const wxFont\& }{font}} 355 356Sets the font associated with the menu item (Windows only). 357 358 359\membersection{wxMenuItem::SetHelp}\label{wxmenuitemsethelp} 360 361\func{void}{SetHelp}{\param{const wxString\& }{helpString}} 362 363Sets the help string. 364 365 366\membersection{wxMenuItem::SetItemLabel}\label{wxmenuitemsetitemlabel} 367 368\func{void}{SetItemLabel}{\param{const wxString\& }{label}} 369 370Sets the label associated with the menu item. 371 372 373\membersection{wxMenuItem::SetMarginWidth}\label{wxmenuitemsetmarginwidth} 374 375\constfunc{void}{SetMarginWidth}{\param{int}{ width}} 376 377Sets the width of the menu item checkmark bitmap (Windows only). 378 379 380\membersection{wxMenuItem::SetMenu}\label{wxmenuitemsetmenu} 381 382\func{void}{SetMenu}{\param{const wxMenu*}{menu}} 383 384Sets the parent menu which will contain this menu item. 385 386 387\membersection{wxMenuItem::SetSubMenu}\label{wxmenuitemsetsubmenu} 388 389\func{void}{SetSubMenu}{\param{const wxMenu*}{menu}} 390 391Sets the submenu of this menu item. 392 393 394\membersection{wxMenuItem::SetText}\label{wxmenuitemsettext} 395 396\func{void}{SetText}{\param{const wxString\& }{text}} 397 398Sets the text associated with the menu item. 399 400This function is deprecated in favour of \helpref{SetItemLabel}{wxmenuitemsetitemlabel}. 401 402 403\membersection{wxMenuItem::SetTextColour}\label{wxmenuitemsettextcolour} 404 405\func{void}{SetTextColour}{\param{const wxColour\& }{colour}} 406 407Sets the text colour associated with the menu item (Windows only). 408 409