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{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
  43 Constructs a wxMenuItem object.
  44
  45 Menu items can be standard, or ``stock menu items'', or custom. For the
  46 standard menu items (such as commands to open a file, exit the program and so
  47 on, see \helpref{stock items}{stockitems} for the full list) it is enough to
  48 specify just the stock ID and leave \arg{text} and \arg{helpString} empty. In
  49 fact, leaving at least \arg{text} empty for the stock menu items is strongly
  50 recommended as they will have appearance and keyboard interface (including
  51 standard accelerators) familiar to the user.
  52
  53 For 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
  55 description (which is automatically shown by the library in the status bar when
  56 the menu item is selected) in this parameter.
  57
  58 Finally note that you can e.g. use a stock menu label without using its stock
  59 help string:
  60
  61 \begin{verbatim}
  62 // use all stock properties:
  63 helpMenu->Append(wxID_ABOUT);
  64
  65 // use the stock label and the stock accelerator but not the stock help string:
  66 helpMenu->Append(wxID_ABOUT, wxEmptyString, wxT("My custom help string"));
  67
  68 // use all stock properties except for the bitmap:
  69 wxMenuItem *mymenu = new wxMenuItem(helpMenu, wxID_ABOUT);
  70 mymenu->SetBitmap(wxArtProvider::GetBitmap(wxART_WARNING));
  71 helpMenu->Append(mymenu);
  72 \end{verbatim}
  73
  74 that 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
  83 key can be specified using the ampersand '\&' character. In order to embed an
  84 ampersand 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
  98 Destructor.
  99
 100
 101 \membersection{wxMenuItem::Check}\label{wxmenuitemcheck}
 102
 103 \func{void}{Check}{\param{bool}{ check = true}}
 104
 105 Checks or unchecks the menu item.
 106
 107 Note 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
 114 Enables or disables the menu item.
 115
 116
 117 \membersection{wxMenuItem::GetBackgroundColour}\label{wxmenuitemgetbackgroundcolour}
 118
 119 \constfunc{wxColour\&}{GetBackgroundColour}{\void}
 120
 121 Returns 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
 128 Returns the checked or unchecked bitmap (Windows only).
 129
 130
 131 \membersection{wxMenuItem::GetFont}\label{wxmenuitemgetfont}
 132
 133 \constfunc{wxFont\&}{GetFont}{\void}
 134
 135 Returns the font associated with the menu item (Windows only).
 136
 137
 138 \membersection{wxMenuItem::GetHelp}\label{wxmenuitemgethelp}
 139
 140 \constfunc{wxString}{GetHelp}{\void}
 141
 142 Returns the help string associated with the menu item.
 143
 144
 145 \membersection{wxMenuItem::GetId}\label{wxmenuitemgetid}
 146
 147 \constfunc{int}{GetId}{\void}
 148
 149 Returns the menu item identifier.
 150
 151
 152 \membersection{wxMenuItem::GetKind}\label{wxmenuitemgetkind}
 153
 154 \constfunc{wxItemKind}{GetKind}{\void}
 155
 156 Returns the item kind, one of {\tt wxITEM\_SEPARATOR}, {\tt wxITEM\_NORMAL},
 157 {\tt wxITEM\_CHECK} or {\tt wxITEM\_RADIO}.
 158
 159
 160 \membersection{wxMenuItem::GetLabel}\label{wxmenuitemgetlabel}
 161
 162 \constfunc{wxString}{GetLabel}{\void}
 163
 164 Returns the text associated with the menu item without any accelerator
 165 characters it might contain.
 166
 167 \wxheading{See also}
 168
 169 \helpref{GetText}{wxmenuitemgettext},
 170 \helpref{GetLabelFromText}{wxmenuitemgetlabelfromtext}
 171
 172
 173 \membersection{wxMenuItem::GetLabelFromText}\label{wxmenuitemgetlabelfromtext}
 174
 175 \func{static wxString}{GetLabelFromText}{\param{const wxString\& }{text}}
 176
 177 Strips all accelerator characters and mnemonics from the given {\it text}.
 178 For example,
 179
 180 \begin{verbatim}
 181 wxMenuItem::GetLabelFromText("&Hello\tCtrl-H");
 182 \end{verbatim}
 183
 184 will return just {\tt "Hello"}.
 185
 186 \wxheading{See also}
 187
 188 \helpref{GetText}{wxmenuitemgettext},
 189 \helpref{GetLabel}{wxmenuitemgetlabel}
 190
 191
 192 \membersection{wxMenuItem::GetMarginWidth}\label{wxmenuitemgetmarginwidth}
 193
 194 \constfunc{int}{GetMarginWidth}{\void}
 195
 196 Gets the width of the menu item checkmark bitmap (Windows only).
 197
 198
 199 \membersection{wxMenuItem::GetMenu}\label{wxmenuitemgetmenu}
 200
 201 \constfunc{wxMenu*}{GetMenu}{\void}
 202
 203 Returns the menu this menu item is in, or NULL if this menu item is not attached.
 204
 205
 206 \membersection{wxMenuItem::GetName}\label{wxmenuitemgetname}
 207
 208 \constfunc{wxString}{GetName}{\void}
 209
 210 Returns the text associated with the menu item.
 211
 212 {\bf NB:} this function is deprecated, please use
 213 \helpref{GetText}{wxmenuitemgettext} or \helpref{GetLabel}{wxmenuitemgetlabel}
 214 instead.
 215
 216
 217 \membersection{wxMenuItem::GetText}\label{wxmenuitemgettext}
 218
 219 \constfunc{wxString}{GetText}{\void}
 220
 221 Returns the text associated with the menu item, such as it was passed to the
 222 wxMenuItem constructor, i.e. with any accelerator characters it may contain.
 223
 224 \wxheading{See also}
 225
 226 \helpref{GetLabel}{wxmenuitemgetlabel},
 227 \helpref{GetLabelFromText}{wxmenuitemgetlabelfromtext}
 228
 229
 230 \membersection{wxMenuItem::GetSubMenu}\label{wxmenuitemgetsubmenu}
 231
 232 \constfunc{wxMenu*}{GetSubMenu}{\void}
 233
 234 Returns the submenu associated with the menu item, or NULL if there isn't one.
 235
 236
 237 \membersection{wxMenuItem::GetTextColour}\label{wxmenuitemgettextcolour}
 238
 239 \constfunc{wxColour\&}{GetTextColour}{\void}
 240
 241 Returns the text colour associated with the menu item (Windows only).
 242
 243
 244 \membersection{wxMenuItem::IsCheckable}\label{wxmenuitemischeckable}
 245
 246 \constfunc{bool}{IsCheckable}{\void}
 247
 248 Returns true if the item is checkable.
 249
 250
 251 \membersection{wxMenuItem::IsChecked}\label{wxmenuitemischecked}
 252
 253 \constfunc{bool}{IsChecked}{\void}
 254
 255 Returns true if the item is checked.
 256
 257
 258 \membersection{wxMenuItem::IsEnabled}\label{wxmenuitemisenabled}
 259
 260 \constfunc{bool}{IsEnabled}{\void}
 261
 262 Returns true if the item is enabled.
 263
 264
 265 \membersection{wxMenuItem::IsSeparator}\label{wxmenuitemisseparator}
 266
 267 \constfunc{bool}{IsSeparator}{\void}
 268
 269 Returns true if the item is a separator.
 270
 271
 272 \membersection{wxMenuItem::IsSubMenu}\label{wxmenuitemissubmenu}
 273
 274 \constfunc{bool}{IsSubMenu}{\void}
 275
 276 Returns true if the item is a submenu.
 277
 278
 279 \membersection{wxMenuItem::SetBackgroundColour}\label{wxmenuitemsetbackgroundcolour}
 280
 281 \constfunc{void}{SetBackgroundColour}{\param{const wxColour\& }{colour}}
 282
 283 Sets the background colour associated with the menu item (Windows only).
 284
 285
 286 \membersection{wxMenuItem::SetBitmap}\label{wxmenuitemsetbitmap}
 287
 288 \func{void}{SetBitmap}{\param{const wxBitmap\& }{bmp}}
 289
 290 Sets the bitmap for the menu item (Windows and GTK+ only). It is
 291 equivalent to \helpref{SetBitmaps}{wxmenuitemsetbitmaps}(bmp, wxNullBitmap).
 292
 293
 294 \membersection{wxMenuItem::SetBitmaps}\label{wxmenuitemsetbitmaps}
 295
 296 \func{void}{SetBitmaps}{\param{const wxBitmap\& }{checked},
 297  \param{const wxBitmap\& }{unchecked = wxNullBitmap}}
 298
 299 Sets the checked/unchecked bitmaps for the menu item (Windows only). The first bitmap
 300 is also used as the single bitmap for uncheckable menu items.
 301
 302
 303 \membersection{wxMenuItem::SetFont}\label{wxmenuitemsetfont}
 304
 305 \func{void}{SetFont}{\param{const wxFont\& }{font}}
 306
 307 Sets the font associated with the menu item (Windows only).
 308
 309
 310 \membersection{wxMenuItem::SetHelp}\label{wxmenuitemsethelp}
 311
 312 \func{void}{SetHelp}{\param{const wxString\& }{helpString}}
 313
 314 Sets the help string.
 315
 316
 317 \membersection{wxMenuItem::SetMarginWidth}\label{wxmenuitemsetmarginwidth}
 318
 319 \constfunc{void}{SetMarginWidth}{\param{int}{ width}}
 320
 321 Sets the width of the menu item checkmark bitmap (Windows only).
 322
 323
 324 \membersection{wxMenuItem::SetMenu}\label{wxmenuitemsetmenu}
 325
 326 \func{void}{SetMenu}{\param{const wxMenu*}{menu}}
 327
 328 Sets the parent menu which will contain this menu item.
 329
 330
 331 \membersection{wxMenuItem::SetSubMenu}\label{wxmenuitemsetsubmenu}
 332
 333 \func{void}{SetSubMenu}{\param{const wxMenu*}{menu}}
 334
 335 Sets the submenu of this menu item.
 336
 337
 338 \membersection{wxMenuItem::SetText}\label{wxmenuitemsettext}
 339
 340 \func{void}{SetText}{\param{const wxString\& }{text}}
 341
 342 Sets the text associated with the menu item.
 343
 344
 345 \membersection{wxMenuItem::SetTextColour}\label{wxmenuitemsettextcolour}
 346
 347 \func{void}{SetTextColour}{\param{const wxColour\& }{colour}}
 348
 349 Sets the text colour associated with the menu item (Windows only).
 350