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 \wxheading{Parameters}
  46
  47 \docparam{parentMenu}{Menu that the menu item belongs to.}
  48
  49 \docparam{id}{Identifier for this menu item, or wxID\_SEPARATOR to indicate a separator.}
  50
  51 \docparam{text}{Text for the menu item, as shown on the menu. An accelerator
  52 key can be specified using the ampersand '\&' character. In order to embed an
  53 ampersand character in the menu item text, the ampersand must be doubled.}
  54
  55 \docparam{helpString}{Optional help string that will be shown on the status bar.}
  56
  57 \docparam{kind}{May be {\tt wxITEM\_SEPARATOR}, {\tt wxITEM\_NORMAL},
  58 {\tt wxITEM\_CHECK} or {\tt wxITEM\_RADIO}}
  59
  60 \docparam{subMenu}{If non-NULL, indicates that the menu item is a submenu.}
  61
  62
  63 \membersection{wxMenuItem::\destruct{wxMenuItem}}\label{wxmenuitemdtor}
  64
  65 \func{}{\destruct{wxMenuItem}}{\void}
  66
  67 Destructor.
  68
  69
  70 \membersection{wxMenuItem::Check}\label{wxmenuitemcheck}
  71
  72 \func{void}{Check}{\param{bool}{ check = true}}
  73
  74 Checks or unchecks the menu item.
  75
  76 Note that this only works when the item is already appended to a menu.
  77
  78
  79 \membersection{wxMenuItem::Enable}\label{wxmenuitemenable}
  80
  81 \func{void}{Enable}{\param{bool}{ enable = true}}
  82
  83 Enables or disables the menu item.
  84
  85
  86 \membersection{wxMenuItem::GetBackgroundColour}\label{wxmenuitemgetbackgroundcolour}
  87
  88 \constfunc{wxColour\&}{GetBackgroundColour}{\void}
  89
  90 Returns the background colour associated with the menu item (Windows only).
  91
  92
  93 \membersection{wxMenuItem::GetBitmap}\label{wxmenuitemgetbitmap}
  94
  95 \constfunc{wxBitmap\&}{GetBitmap}{\param{bool}{ checked = true}}
  96
  97 Returns the checked or unchecked bitmap (Windows only).
  98
  99
 100 \membersection{wxMenuItem::GetFont}\label{wxmenuitemgetfont}
 101
 102 \constfunc{wxFont\&}{GetFont}{\void}
 103
 104 Returns the font associated with the menu item (Windows only).
 105
 106
 107 \membersection{wxMenuItem::GetHelp}\label{wxmenuitemgethelp}
 108
 109 \constfunc{wxString}{GetHelp}{\void}
 110
 111 Returns the help string associated with the menu item.
 112
 113
 114 \membersection{wxMenuItem::GetId}\label{wxmenuitemgetid}
 115
 116 \constfunc{int}{GetId}{\void}
 117
 118 Returns the menu item identifier.
 119
 120
 121 \membersection{wxMenuItem::GetKind}\label{wxmenuitemgetkind}
 122
 123 \constfunc{wxItemKind}{GetKind}{\void}
 124
 125 Returns the item kind, one of {\tt wxITEM\_SEPARATOR}, {\tt wxITEM\_NORMAL},
 126 {\tt wxITEM\_CHECK} or {\tt wxITEM\_RADIO}.
 127
 128
 129 \membersection{wxMenuItem::GetLabel}\label{wxmenuitemgetlabel}
 130
 131 \constfunc{wxString}{GetLabel}{\void}
 132
 133 Returns the text associated with the menu item without any accelerator
 134 characters it might contain.
 135
 136 \wxheading{See also}
 137
 138 \helpref{GetText}{wxmenuitemgettext},
 139 \helpref{GetLabelFromText}{wxmenuitemgetlabelfromtext}
 140
 141
 142 \membersection{wxMenuItem::GetLabelFromText}\label{wxmenuitemgetlabelfromtext}
 143
 144 \func{static wxString}{GetLabelFromText}{\param{const wxString\& }{text}}
 145
 146 Strips all accelerator characters and mnemonics from the given {\it text}.
 147 For example,
 148
 149 \begin{verbatim}
 150 wxMenuItem::GetLabelFromText("&Hello\tCtrl-H");
 151 \end{verbatim}
 152
 153 will return just {\tt "Hello"}.
 154
 155 \wxheading{See also}
 156
 157 \helpref{GetText}{wxmenuitemgettext},
 158 \helpref{GetLabel}{wxmenuitemgetlabel}
 159
 160
 161 \membersection{wxMenuItem::GetMarginWidth}\label{wxmenuitemgetmarginwidth}
 162
 163 \constfunc{int}{GetMarginWidth}{\void}
 164
 165 Gets the width of the menu item checkmark bitmap (Windows only).
 166
 167
 168 \membersection{wxMenuItem::GetMenu}\label{wxmenuitemgetmenu}
 169
 170 \constfunc{wxMenu*}{GetMenu}{\void}
 171
 172 Returns the menu this menu item is in, or NULL if this menu item is not attached.
 173
 174
 175 \membersection{wxMenuItem::GetName}\label{wxmenuitemgetname}
 176
 177 \constfunc{wxString}{GetName}{\void}
 178
 179 Returns the text associated with the menu item.
 180
 181 {\bf NB:} this function is deprecated, please use
 182 \helpref{GetText}{wxmenuitemgettext} or \helpref{GetLabel}{wxmenuitemgetlabel}
 183 instead.
 184
 185
 186 \membersection{wxMenuItem::GetText}\label{wxmenuitemgettext}
 187
 188 \constfunc{wxString}{GetText}{\void}
 189
 190 Returns the text associated with the menu item, such as it was passed to the
 191 wxMenuItem constructor, i.e. with any accelerator characters it may contain.
 192
 193 \wxheading{See also}
 194
 195 \helpref{GetLabel}{wxmenuitemgetlabel},
 196 \helpref{GetLabelFromText}{wxmenuitemgetlabelfromtext}
 197
 198
 199 \membersection{wxMenuItem::GetSubMenu}\label{wxmenuitemgetsubmenu}
 200
 201 \constfunc{wxMenu*}{GetSubMenu}{\void}
 202
 203 Returns the submenu associated with the menu item, or NULL if there isn't one.
 204
 205
 206 \membersection{wxMenuItem::GetTextColour}\label{wxmenuitemgettextcolour}
 207
 208 \constfunc{wxColour\&}{GetTextColour}{\void}
 209
 210 Returns the text colour associated with the menu item (Windows only).
 211
 212
 213 \membersection{wxMenuItem::IsCheckable}\label{wxmenuitemischeckable}
 214
 215 \constfunc{bool}{IsCheckable}{\void}
 216
 217 Returns true if the item is checkable.
 218
 219
 220 \membersection{wxMenuItem::IsChecked}\label{wxmenuitemischecked}
 221
 222 \constfunc{bool}{IsChecked}{\void}
 223
 224 Returns true if the item is checked.
 225
 226
 227 \membersection{wxMenuItem::IsEnabled}\label{wxmenuitemisenabled}
 228
 229 \constfunc{bool}{IsEnabled}{\void}
 230
 231 Returns true if the item is enabled.
 232
 233
 234 \membersection{wxMenuItem::IsSeparator}\label{wxmenuitemisseparator}
 235
 236 \constfunc{bool}{IsSeparator}{\void}
 237
 238 Returns true if the item is a separator.
 239
 240
 241 \membersection{wxMenuItem::IsSubMenu}\label{wxmenuitemissubmenu}
 242
 243 \constfunc{bool}{IsSubMenu}{\void}
 244
 245 Returns true if the item is a submenu.
 246
 247
 248 \membersection{wxMenuItem::SetBackgroundColour}\label{wxmenuitemsetbackgroundcolour}
 249
 250 \constfunc{void}{SetBackgroundColour}{\param{const wxColour\& }{colour}}
 251
 252 Sets the background colour associated with the menu item (Windows only).
 253
 254
 255 \membersection{wxMenuItem::SetBitmap}\label{wxmenuitemsetbitmap}
 256
 257 \func{void}{SetBitmap}{\param{const wxBitmap\& }{bmp}}
 258
 259 Sets the bitmap for the menu item (Windows and GTK+ only). It is
 260 equivalent to \helpref{SetBitmaps}{wxmenuitemsetbitmaps}(bmp, wxNullBitmap).
 261
 262
 263 \membersection{wxMenuItem::SetBitmaps}\label{wxmenuitemsetbitmaps}
 264
 265 \func{void}{SetBitmaps}{\param{const wxBitmap\& }{checked},
 266  \param{const wxBitmap\& }{unchecked = wxNullBitmap}}
 267
 268 Sets the checked/unchecked bitmaps for the menu item (Windows only). The first bitmap
 269 is also used as the single bitmap for uncheckable menu items.
 270
 271
 272 \membersection{wxMenuItem::SetFont}\label{wxmenuitemsetfont}
 273
 274 \func{void}{SetFont}{\param{const wxFont\& }{font}}
 275
 276 Sets the font associated with the menu item (Windows only).
 277
 278
 279 \membersection{wxMenuItem::SetHelp}\label{wxmenuitemsethelp}
 280
 281 \func{void}{SetHelp}{\param{const wxString\& }{helpString}}
 282
 283 Sets the help string.
 284
 285
 286 \membersection{wxMenuItem::SetMarginWidth}\label{wxmenuitemsetmarginwidth}
 287
 288 \constfunc{void}{SetMarginWidth}{\param{int}{ width}}
 289
 290 Sets the width of the menu item checkmark bitmap (Windows only).
 291
 292
 293 \membersection{wxMenuItem::SetMenu}\label{wxmenuitemsetmenu}
 294
 295 \func{void}{SetMenu}{\param{const wxMenu*}{menu}}
 296
 297 Sets the parent menu which will contain this menu item.
 298
 299
 300 \membersection{wxMenuItem::SetSubMenu}\label{wxmenuitemsetsubmenu}
 301
 302 \func{void}{SetSubMenu}{\param{const wxMenu*}{menu}}
 303
 304 Sets the submenu of this menu item.
 305
 306
 307 \membersection{wxMenuItem::SetText}\label{wxmenuitemsettext}
 308
 309 \func{void}{SetText}{\param{const wxString\& }{text}}
 310
 311 Sets the text associated with the menu item.
 312
 313
 314 \membersection{wxMenuItem::SetTextColour}\label{wxmenuitemsettextcolour}
 315
 316 \func{void}{SetTextColour}{\param{const wxColour\& }{colour}}
 317
 318 Sets the text colour associated with the menu item (Windows only).
 319