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