docs/latex/wx/menuitem.tex

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