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::GetKind}\label{wxmenuitemgetkind}
 157
 158 \constfunc{wxItemKind}{GetKind}{\void}
 159
 160 Returns the item kind, one of {\tt wxITEM\_SEPARATOR}, {\tt wxITEM\_NORMAL},
 161 {\tt wxITEM\_CHECK} or {\tt wxITEM\_RADIO}.
 162
 163
 164 \membersection{wxMenuItem::GetLabel}\label{wxmenuitemgetlabel}
 165
 166 \constfunc{wxString}{GetLabel}{\void}
 167
 168 Returns the text associated with the menu item without any accelerator
 169 characters it might contain.
 170
 171 \wxheading{See also}
 172
 173 \helpref{GetText}{wxmenuitemgettext},
 174 \helpref{GetLabelFromText}{wxmenuitemgetlabelfromtext}
 175
 176
 177 \membersection{wxMenuItem::GetLabelFromText}\label{wxmenuitemgetlabelfromtext}
 178
 179 \func{static wxString}{GetLabelFromText}{\param{const wxString\& }{text}}
 180
 181 Strips all accelerator characters and mnemonics from the given {\it text}.
 182 For example,
 183
 184 \begin{verbatim}
 185 wxMenuItem::GetLabelFromText("&Hello\tCtrl-H");
 186 \end{verbatim}
 187
 188 will return just {\tt "Hello"}.
 189
 190 \wxheading{See also}
 191
 192 \helpref{GetText}{wxmenuitemgettext},
 193 \helpref{GetLabel}{wxmenuitemgetlabel}
 194
 195
 196 \membersection{wxMenuItem::GetMarginWidth}\label{wxmenuitemgetmarginwidth}
 197
 198 \constfunc{int}{GetMarginWidth}{\void}
 199
 200 Gets the width of the menu item checkmark bitmap (Windows only).
 201
 202
 203 \membersection{wxMenuItem::GetMenu}\label{wxmenuitemgetmenu}
 204
 205 \constfunc{wxMenu*}{GetMenu}{\void}
 206
 207 Returns the menu this menu item is in, or NULL if this menu item is not attached.
 208
 209
 210 \membersection{wxMenuItem::GetName}\label{wxmenuitemgetname}
 211
 212 \constfunc{wxString}{GetName}{\void}
 213
 214 Returns the text associated with the menu item.
 215
 216 {\bf NB:} this function is deprecated, please use
 217 \helpref{GetText}{wxmenuitemgettext} or \helpref{GetLabel}{wxmenuitemgetlabel}
 218 instead.
 219
 220
 221 \membersection{wxMenuItem::GetText}\label{wxmenuitemgettext}
 222
 223 \constfunc{wxString}{GetText}{\void}
 224
 225 Returns the text associated with the menu item, such as it was passed to the
 226 wxMenuItem constructor, i.e. with any accelerator characters it may contain.
 227
 228 \wxheading{See also}
 229
 230 \helpref{GetLabel}{wxmenuitemgetlabel},
 231 \helpref{GetLabelFromText}{wxmenuitemgetlabelfromtext}
 232
 233
 234 \membersection{wxMenuItem::GetSubMenu}\label{wxmenuitemgetsubmenu}
 235
 236 \constfunc{wxMenu*}{GetSubMenu}{\void}
 237
 238 Returns the submenu associated with the menu item, or NULL if there isn't one.
 239
 240
 241 \membersection{wxMenuItem::GetTextColour}\label{wxmenuitemgettextcolour}
 242
 243 \constfunc{wxColour\&}{GetTextColour}{\void}
 244
 245 Returns the text colour associated with the menu item (Windows only).
 246
 247
 248 \membersection{wxMenuItem::IsCheckable}\label{wxmenuitemischeckable}
 249
 250 \constfunc{bool}{IsCheckable}{\void}
 251
 252 Returns true if the item is checkable.
 253
 254
 255 \membersection{wxMenuItem::IsChecked}\label{wxmenuitemischecked}
 256
 257 \constfunc{bool}{IsChecked}{\void}
 258
 259 Returns true if the item is checked.
 260
 261
 262 \membersection{wxMenuItem::IsEnabled}\label{wxmenuitemisenabled}
 263
 264 \constfunc{bool}{IsEnabled}{\void}
 265
 266 Returns true if the item is enabled.
 267
 268
 269 \membersection{wxMenuItem::IsSeparator}\label{wxmenuitemisseparator}
 270
 271 \constfunc{bool}{IsSeparator}{\void}
 272
 273 Returns true if the item is a separator.
 274
 275
 276 \membersection{wxMenuItem::IsSubMenu}\label{wxmenuitemissubmenu}
 277
 278 \constfunc{bool}{IsSubMenu}{\void}
 279
 280 Returns true if the item is a submenu.
 281
 282
 283 \membersection{wxMenuItem::SetBackgroundColour}\label{wxmenuitemsetbackgroundcolour}
 284
 285 \constfunc{void}{SetBackgroundColour}{\param{const wxColour\& }{colour}}
 286
 287 Sets the background colour associated with the menu item (Windows only).
 288
 289
 290 \membersection{wxMenuItem::SetBitmap}\label{wxmenuitemsetbitmap}
 291
 292 \func{void}{SetBitmap}{\param{const wxBitmap\& }{bmp}}
 293
 294 Sets the bitmap for the menu item (Windows and GTK+ only). It is
 295 equivalent to \helpref{SetBitmaps}{wxmenuitemsetbitmaps}(bmp, wxNullBitmap).
 296
 297
 298 \membersection{wxMenuItem::SetBitmaps}\label{wxmenuitemsetbitmaps}
 299
 300 \func{void}{SetBitmaps}{\param{const wxBitmap\& }{checked},
 301  \param{const wxBitmap\& }{unchecked = wxNullBitmap}}
 302
 303 Sets the checked/unchecked bitmaps for the menu item (Windows only). The first bitmap
 304 is also used as the single bitmap for uncheckable menu items.
 305
 306
 307 \membersection{wxMenuItem::SetFont}\label{wxmenuitemsetfont}
 308
 309 \func{void}{SetFont}{\param{const wxFont\& }{font}}
 310
 311 Sets the font associated with the menu item (Windows only).
 312
 313
 314 \membersection{wxMenuItem::SetHelp}\label{wxmenuitemsethelp}
 315
 316 \func{void}{SetHelp}{\param{const wxString\& }{helpString}}
 317
 318 Sets the help string.
 319
 320
 321 \membersection{wxMenuItem::SetMarginWidth}\label{wxmenuitemsetmarginwidth}
 322
 323 \constfunc{void}{SetMarginWidth}{\param{int}{ width}}
 324
 325 Sets the width of the menu item checkmark bitmap (Windows only).
 326
 327
 328 \membersection{wxMenuItem::SetMenu}\label{wxmenuitemsetmenu}
 329
 330 \func{void}{SetMenu}{\param{const wxMenu*}{menu}}
 331
 332 Sets the parent menu which will contain this menu item.
 333
 334
 335 \membersection{wxMenuItem::SetSubMenu}\label{wxmenuitemsetsubmenu}
 336
 337 \func{void}{SetSubMenu}{\param{const wxMenu*}{menu}}
 338
 339 Sets the submenu of this menu item.
 340
 341
 342 \membersection{wxMenuItem::SetText}\label{wxmenuitemsettext}
 343
 344 \func{void}{SetText}{\param{const wxString\& }{text}}
 345
 346 Sets the text associated with the menu item.
 347
 348
 349 \membersection{wxMenuItem::SetTextColour}\label{wxmenuitemsettextcolour}
 350
 351 \func{void}{SetTextColour}{\param{const wxColour\& }{colour}}
 352
 353 Sets the text colour associated with the menu item (Windows only).
 354