]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/menuitem.tex
interface headers reviewed
[wxWidgets.git] / 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