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