]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/menu.tex
test indeterminate wxGauge mode (part of patch 1551409)
[wxWidgets.git] / docs / latex / wx / menu.tex
CommitLineData
66760199
WS
1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2%% Name: menu.tex
3%% Purpose: wxMenu 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
a660d684
KB
12\section{\class{wxMenu}}\label{wxmenu}
13
14A menu is a popup (or pull down) list of items, one of which may be
15selected before the menu goes away (clicking elsewhere dismisses the
0472ece7 16menu). Menus may be used to construct either menu bars or popup menus.
a660d684
KB
17
18A menu item has an integer ID associated with it which can be used to
0472ece7
VZ
19identify the selection, or to change the menu item in some way. A menu item
20with a special identifier $-1$ is a separator item and doesn't have an
21associated command but just makes a separator line appear in the menu.
22
bb772a8e 23{\bf NB:} Please note that {\it wxID\_ABOUT} and {\it wxID\_EXIT} are
c436b310
RR
24predefined by wxWidgets and have a special meaning since entries
25using these IDs will be taken out of the normal menus under MacOS X
26and will be inserted into the system menu (following the appropriate
66760199
WS
27MacOS X interface guideline). On PalmOS {\it wxID\_EXIT} is disabled according
28to Palm OS Companion guidelines.
c436b310 29
0472ece7
VZ
30Menu items may be either normal items, check items or radio items. Normal items
31don't have any special properties while the check items have a boolean flag
32associated to them and they show a checkmark in the menu when the flag is set.
fc2171bd 33wxWidgets automatically toggles the flag value when the item is clicked and its
0472ece7
VZ
34value may be retrieved using either \helpref{IsChecked}{wxmenuischecked} method
35of wxMenu or wxMenuBar itself or by using
36\helpref{wxEvent::IsChecked}{wxcommandeventischecked} when you get the menu
37notification for the item in question.
38
39The radio items are similar to the check items except that all the other items
40in the same radio group are unchecked when a radio item is checked. The radio
41group is formed by a contiguous range of radio items, i.e. it starts at the
42first item of this kind and ends with the first item of a different kind (or
43the end of the menu). Notice that because the radio groups are defined in terms
44of the item positions inserting or removing the items in the menu containing
25057aba
JS
45the radio items risks to not work correctly. Finally note that radio items
46are not supported under Motif.
a660d684 47
2b5f62a0
VZ
48\wxheading{Allocation strategy}
49
50All menus except the popup ones must be created on the heap. All menus
51attached to a menubar or to another menu will be deleted by their parent when
52it is deleted. As the frame menubar is deleted by the frame itself, it means
53that normally all menus used are deleted automatically.
54
a660d684
KB
55\wxheading{Derived from}
56
57\helpref{wxEvtHandler}{wxevthandler}\\
58\helpref{wxObject}{wxobject}
59
954b8ae6
JS
60\wxheading{Include files}
61
62<wx/menu.h>
63
a660d684
KB
64\wxheading{Event handling}
65
66If the menu is part of a menubar, then \helpref{wxMenuBar}{wxmenubar} event processing is used.
67
68With a popup menu, there is a variety of ways to handle a menu selection event
69(wxEVT\_COMMAND\_MENU\_SELECTED).
70
71\begin{enumerate}\itemsep=0pt
a660d684
KB
72\item Derive a new class from wxMenu and define event table entries using the EVT\_MENU macro.
73\item Set a new event handler for wxMenu, using an object whose class has EVT\_MENU entries.
74\item Provide EVT\_MENU handlers in the window which pops up the menu, or in an ancestor of
75this window.
1aaef614 76\item Define a callback of type wxFunction, which you pass to the wxMenu constructor.
874a1686 77The callback takes a reference to the menu, and a reference to a
1aaef614
VZ
78\helpref{wxCommandEvent}{wxcommandevent}. This method is deprecated and should
79not be used in the new code, it is provided for backwards compatibility only.
a660d684
KB
80\end{enumerate}
81
82\wxheading{See also}
83
84\helpref{wxMenuBar}{wxmenubar}, \helpref{wxWindow::PopupMenu}{wxwindowpopupmenu},\rtfsp
484bdc6a
VZ
85\helpref{Event handling overview}{eventhandlingoverview},\rtfsp
86\helpref{wxFileHistory (most recently used files menu)}{wxfilehistory}
87
88
a660d684
KB
89
90\latexignore{\rtfignore{\wxheading{Members}}}
91
3786c8b5 92
dcbd177f 93\membersection{wxMenu::wxMenu}\label{wxmenuctor}
a660d684 94
b1462dfa 95\func{}{wxMenu}{\param{const wxString\& }{title = ""}, \param{long}{ style = 0}}
a660d684
KB
96
97Constructs a wxMenu object.
98
99\wxheading{Parameters}
100
101\docparam{title}{A title for the popup menu: the empty string denotes no title.}
102
809f39fe 103\docparam{style}{If set to {\tt wxMENU\_TEAROFF}, the menu will be detachable (wxGTK only).}
06d20283 104
407f3681 105\func{}{wxMenu}{\param{long}{ style}}
4e986502
KB
106
107Constructs a wxMenu object.
108
109\wxheading{Parameters}
407f3681 110
809f39fe 111\docparam{style}{If set to {\tt wxMENU\_TEAROFF}, the menu will be detachable (wxGTK only).}
4e986502 112
3786c8b5 113
dcbd177f 114\membersection{wxMenu::\destruct{wxMenu}}\label{wxmenudtor}
a660d684
KB
115
116\func{}{\destruct{wxMenu}}{\void}
117
118Destructor, destroying the menu.
119
b412f9be
JS
120Note: under Motif, a popup menu must have a valid parent (the window
121it was last popped up on) when being destroyed. Therefore, make sure
122you delete or re-use the popup menu {\it before} destroying the
123parent window. Re-use in this context means popping up the menu on
124a different window from last time, which causes an implicit destruction
125and recreation of internal data structures.
126
3786c8b5 127
a660d684
KB
128\membersection{wxMenu::Append}\label{wxmenuappend}
129
ee0a94cf 130\func{wxMenuItem*}{Append}{\param{int}{ id}, \param{const wxString\& }{ item = ""}, \param{const wxString\& }{helpString = ""},\rtfsp
98322660 131\param{wxItemKind}{ kind = wxITEM\_NORMAL}}
a660d684
KB
132
133Adds a string item to the end of the menu.
134
9add9367 135\func{wxMenuItem*}{Append}{\param{int}{ id}, \param{const wxString\& }{ item}, \param{wxMenu *}{subMenu},\rtfsp
a660d684
KB
136\param{const wxString\& }{helpString = ""}}
137
2b5f62a0
VZ
138Adds a pull-right submenu to the end of the menu. Append the submenu to the parent
139menu {\it after} you have added your menu items, or accelerators may not be
140registered properly.
a660d684 141
9add9367 142\func{wxMenuItem*}{Append}{\param{wxMenuItem*}{ menuItem}}
a660d684 143
1aaef614
VZ
144Adds a menu item object. This is the most generic variant of Append() method
145because it may be used for both items (including separators) and submenus and
146because you can also specify various extra properties of a menu item this way,
a660d684
KB
147such as bitmaps and fonts.
148
149\wxheading{Parameters}
150
151\docparam{id}{The menu command identifier.}
152
153\docparam{item}{The string to appear on the menu item.}
154
155\docparam{menu}{Pull-right submenu.}
156
98322660
JS
157\docparam{kind}{May be {\tt wxITEM\_SEPARATOR}, {\tt wxITEM\_NORMAL},
158{\tt wxITEM\_CHECK} or {\tt wxITEM\_RADIO}}
a660d684
KB
159
160\docparam{helpString}{An optional help string associated with the item.
684761db 161By default, the handler for the wxEVT\_MENU\_HIGHLIGHT event displays
a660d684
KB
162this string in the status line.}
163
164\docparam{menuItem}{A menuitem object. It will be owned by the wxMenu object after this function
165is called, so do not delete it yourself.}
166
167\wxheading{Remarks}
168
169This command can be used after the menu has been shown, as well as on initial
170creation of a menu or menubar.
171
69440cd2
VZ
172The {\it item} string for the normal menu items (not submenus or separators)
173may include the accelerator which can be used to activate the menu item
174from keyboard. The accelerator string follows the item label and is separated
175from it by a {\tt TAB} character ({\tt '$\backslash$t'}). Its general syntax is
176any combination of {\tt "CTRL"}, {\tt "ALT"} and {\tt "SHIFT"} strings (case
177doesn't matter) separated by either {\tt '-'} or {\tt '+'} characters and
178followed by the accelerator itself. The accelerator may be any alphanumeric
179character, any function key (from {\tt F1} to {\tt F12}) or one of the special
180characters listed in the table below (again, case doesn't matter):
d2c2afc9 181
69440cd2
VZ
182\begin{twocollist}\itemsep=0pt
183\twocolitem{{\tt DEL} or {\tt DELETE}}{Delete key}
184\twocolitem{{\tt INS} or {\tt INSERT}}{Insert key}
185\twocolitem{{\tt ENTER} or {\tt RETURN}}{Enter key}
186\twocolitem{{\tt PGUP}}{PageUp key}
187\twocolitem{{\tt PGDN}}{PageDown key}
188\twocolitem{{\tt LEFT}}{Left cursor arrow key}
189\twocolitem{{\tt RIGHT}}{Right cursor arrow key}
190\twocolitem{{\tt UP}}{Up cursor arrow key}
191\twocolitem{{\tt DOWN}}{Down cursor arrow key}
192\twocolitem{{\tt HOME}}{Home key}
193\twocolitem{{\tt END}}{End key}
194\twocolitem{{\tt SPACE}}{Space}
195\twocolitem{{\tt TAB}}{Tab key}
41b78190 196\twocolitem{{\tt ESC} or {\tt ESCAPE}}{Escape key (Windows only)}
69440cd2
VZ
197\end{twocollist}
198
a660d684
KB
199\wxheading{See also}
200
1aaef614 201\helpref{wxMenu::AppendSeparator}{wxmenuappendseparator},\rtfsp
d65c269b
VZ
202\helpref{wxMenu::AppendCheckItem}{wxmenuappendcheckitem},\rtfsp
203\helpref{wxMenu::AppendRadioItem}{wxmenuappendradioitem},\rtfsp
3786c8b5 204\helpref{wxMenu::AppendSubMenu}{wxmenuappendsubmenu},\rtfsp
1aaef614
VZ
205\helpref{wxMenu::Insert}{wxmenuinsert},\rtfsp
206\helpref{wxMenu::SetLabel}{wxmenusetlabel}, \helpref{wxMenu::GetHelpString}{wxmenugethelpstring},\rtfsp
a660d684
KB
207\helpref{wxMenu::SetHelpString}{wxmenusethelpstring}, \helpref{wxMenuItem}{wxmenuitem}
208
06d20283 209\pythonnote{In place of a single overloaded method name, wxPython
d2c2afc9
JS
210implements the following methods:
211
06d20283 212\indented{2cm}{\begin{twocollist}
cc81d32f 213\twocolitem{{\bf Append(id, string, helpStr="", checkable=false)}}{}
c9110876
VS
214\twocolitem{{\bf AppendMenu(id, string, aMenu, helpStr="")}}{}
215\twocolitem{{\bf AppendItem(aMenuItem)}}{}
06d20283
RD
216\end{twocollist}}
217}
218
3786c8b5 219
d65c269b
VZ
220\membersection{wxMenu::AppendCheckItem}\label{wxmenuappendcheckitem}
221
9add9367 222\func{wxMenuItem*}{AppendCheckItem}{\param{int}{ id},\rtfsp
d65c269b
VZ
223\param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""}}
224
225Adds a checkable item to the end of the menu.
226
227\wxheading{See also}
228
229\helpref{wxMenu::Append}{wxmenuappend},\rtfsp
230\helpref{wxMenu::InsertCheckItem}{wxmenuinsertcheckitem}
231
3786c8b5 232
d65c269b
VZ
233\membersection{wxMenu::AppendRadioItem}\label{wxmenuappendradioitem}
234
9add9367 235\func{wxMenuItem*}{AppendRadioItem}{\param{int}{ id},\rtfsp
d65c269b
VZ
236\param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""}}
237
238Adds a radio item to the end of the menu. All consequent radio items form a
239group and when an item in the group is checked, all the others are
240automatically unchecked.
241
d65c269b
VZ
242\wxheading{See also}
243
244\helpref{wxMenu::Append}{wxmenuappend},\rtfsp
245\helpref{wxMenu::InsertRadioItem}{wxmenuinsertradioitem}
246
3786c8b5 247
a660d684
KB
248\membersection{wxMenu::AppendSeparator}\label{wxmenuappendseparator}
249
9add9367 250\func{wxMenuItem*}{AppendSeparator}{\void}
a660d684
KB
251
252Adds a separator to the end of the menu.
253
254\wxheading{See also}
255
d65c269b
VZ
256\helpref{wxMenu::Append}{wxmenuappend},\rtfsp
257\helpref{wxMenu::InsertSeparator}{wxmenuinsertseparator}
a660d684 258
3786c8b5
VZ
259
260\membersection{wxMenu::AppendSubMenu}\label{wxmenuappendsubmenu}
261
262\func{wxMenuItem *}{AppendSubMenu}{\param{wxMenu *}{submenu}, \param{const wxString\& }{text}, \param{const wxString\& }{help = wxEmptyString}}
263
264Adds the given \arg{submenu} to this menu. \arg{text} is the text shown in the
265menu for it and \arg{help} is the help string shown in the status bar when the
266submenu item is selected.
267
268
a660d684
KB
269\membersection{wxMenu::Break}\label{wxmenubreak}
270
271\func{void}{Break}{\void}
272
273Inserts a break in a menu, causing the next appended item to appear in a new column.
274
3786c8b5 275
a660d684
KB
276\membersection{wxMenu::Check}\label{wxmenucheck}
277
eaaa6a06 278\func{void}{Check}{\param{int}{ id}, \param{const bool}{ check}}
a660d684
KB
279
280Checks or unchecks the menu item.
281
282\wxheading{Parameters}
283
284\docparam{id}{The menu item identifier.}
285
cc81d32f 286\docparam{check}{If true, the item will be checked, otherwise it will be unchecked.}
a660d684
KB
287
288\wxheading{See also}
289
290\helpref{wxMenu::IsChecked}{wxmenuischecked}
291
3786c8b5 292
fc9c7c09
RR
293\membersection{wxMenu::Delete}\label{wxmenudelete}
294
295\func{void}{Delete}{\param{int }{id}}
296
1aaef614
VZ
297\func{void}{Delete}{\param{wxMenuItem *}{item}}
298
874a1686 299Deletes the menu item from the menu. If the item is a submenu, it will
1aaef614
VZ
300{\bf not} be deleted. Use \helpref{Destroy}{wxmenudestroy} if you want to
301delete a submenu.
fc9c7c09
RR
302
303\wxheading{Parameters}
304
1aaef614 305\docparam{id}{Id of the menu item to be deleted.}
fc9c7c09 306
1aaef614
VZ
307\docparam{item}{Menu item to be deleted.}
308
309\wxheading{See also}
310
311\helpref{wxMenu::FindItem}{wxmenufinditem},\rtfsp
312\helpref{wxMenu::Destroy}{wxmenudestroy},\rtfsp
313\helpref{wxMenu::Remove}{wxmenuremove}
314
3786c8b5 315
1aaef614
VZ
316\membersection{wxMenu::Destroy}\label{wxmenudestroy}
317
318\func{void}{Destroy}{\param{int }{id}}
319
320\func{void}{Destroy}{\param{wxMenuItem *}{item}}
321
874a1686 322Deletes the menu item from the menu. If the item is a submenu, it will
1aaef614
VZ
323be deleted. Use \helpref{Remove}{wxmenuremove} if you want to keep the submenu
324(for example, to reuse it later).
fc9c7c09 325
1aaef614
VZ
326\wxheading{Parameters}
327
328\docparam{id}{Id of the menu item to be deleted.}
329
330\docparam{item}{Menu item to be deleted.}
fc9c7c09
RR
331
332\wxheading{See also}
333
1aaef614
VZ
334\helpref{wxMenu::FindItem}{wxmenufinditem},\rtfsp
335\helpref{wxMenu::Deletes}{wxmenudelete},\rtfsp
336\helpref{wxMenu::Remove}{wxmenuremove}
fc9c7c09 337
3786c8b5 338
a660d684
KB
339\membersection{wxMenu::Enable}\label{wxmenuenable}
340
eaaa6a06 341\func{void}{Enable}{\param{int}{ id}, \param{const bool}{ enable}}
a660d684
KB
342
343Enables or disables (greys out) a menu item.
344
345\wxheading{Parameters}
346
347\docparam{id}{The menu item identifier.}
348
cc81d32f 349\docparam{enable}{true to enable the menu item, false to disable it.}
a660d684
KB
350
351\wxheading{See also}
352
353\helpref{wxMenu::IsEnabled}{wxmenuisenabled}
354
3786c8b5 355
a660d684
KB
356\membersection{wxMenu::FindItem}\label{wxmenufinditem}
357
358\constfunc{int}{FindItem}{\param{const wxString\& }{itemString}}
359
360Finds the menu item id for a menu item string.
361
1aaef614 362\constfunc{wxMenuItem *}{FindItem}{\param{int}{ id}, \param{wxMenu **}{menu = NULL}}
407f3681 363
1aaef614
VZ
364Finds the menu item object associated with the given menu item identifier and,
365optionally, the (sub)menu it belongs to.
a660d684 366
5873607e
VZ
367\perlnote{In wxPerl this method takes just the {\tt id} parameter;
368in scalar context it returns the associated {\tt Wx::MenuItem}, in list
9722642d 369context it returns a 2-element list {\tt ( item, submenu )}}
5873607e 370
a660d684
KB
371\wxheading{Parameters}
372
e12be2f7
JS
373\docparam{itemString}{Menu item string to find.}
374
a660d684
KB
375\docparam{id}{Menu item identifier.}
376
3980000c 377\docparam{menu}{If the pointer is not NULL, it will be filled with the item's
1aaef614
VZ
378parent menu (if the item was found)}
379
a660d684
KB
380\wxheading{Return value}
381
a8d08dbd 382First form: menu item identifier, or {\tt wxNOT\_FOUND} if none is found.
a660d684 383
e12be2f7 384Second form: returns the menu item object, or NULL if it is not found.
a660d684 385
e12be2f7
JS
386\wxheading{Remarks}
387
388Any special menu codes are stripped out of source and target strings
389before matching.
a660d684 390
fa482912 391\pythonnote{The name of this method in wxPython is {\tt FindItemById}
874a1686
RD
392and it does not support the second parameter.}
393
3786c8b5 394
bd582574
JS
395\membersection{wxMenu::FindItemByPosition}\label{wxmenufinditembyposition}
396
62313dec 397\constfunc{wxMenuItem*}{FindItemByPosition}{\param{size\_t }{position}}
bd582574
JS
398
399Returns the wxMenuItem given a position in the menu.
400
3786c8b5 401
a660d684
KB
402\membersection{wxMenu::GetHelpString}\label{wxmenugethelpstring}
403
eaaa6a06 404\constfunc{wxString}{GetHelpString}{\param{int}{ id}}
a660d684
KB
405
406Returns the help string associated with a menu item.
407
408\wxheading{Parameters}
409
410\docparam{id}{The menu item identifier.}
411
412\wxheading{Return value}
413
414The help string, or the empty string if there is no help string or the
415item was not found.
416
417\wxheading{See also}
418
419\helpref{wxMenu::SetHelpString}{wxmenusethelpstring}, \helpref{wxMenu::Append}{wxmenuappend}
420
3786c8b5 421
a660d684
KB
422\membersection{wxMenu::GetLabel}\label{wxmenugetlabel}
423
eaaa6a06 424\constfunc{wxString}{GetLabel}{\param{int}{ id}}
a660d684
KB
425
426Returns a menu item label.
427
428\wxheading{Parameters}
429
430\docparam{id}{The menu item identifier.}
431
432\wxheading{Return value}
433
434The item label, or the empty string if the item was not found.
435
436\wxheading{See also}
437
438\helpref{wxMenu::SetLabel}{wxmenusetlabel}
439
3786c8b5 440
1aaef614
VZ
441\membersection{wxMenu::GetMenuItemCount}\label{wxmenugetmenuitemcount}
442
443\constfunc{size\_t}{GetMenuItemCount}{\void}
444
445Returns the number of items in the menu.
446
3786c8b5 447
1aaef614
VZ
448\membersection{wxMenu::GetMenuItems}\label{wxmenugetmenuitems}
449
450\constfunc{wxMenuItemList\&}{GetMenuItems}{\void}
451
452Returns the list of items in the menu. wxMenuItemList is a pseudo-template
453list class containing wxMenuItem pointers.
454
3786c8b5 455
a660d684
KB
456\membersection{wxMenu::GetTitle}\label{wxmenugettitle}
457
458\constfunc{wxString}{GetTitle}{\void}
459
460Returns the title of the menu.
461
462\wxheading{Remarks}
463
706f30f8
VZ
464This is relevant only to popup menus, use
465\helpref{wxMenuBar::GetLabelTop}{wxmenubargetlabeltop} for the menus in the
466menubar.
a660d684
KB
467
468\wxheading{See also}
469
470\helpref{wxMenu::SetTitle}{wxmenusettitle}
471
3786c8b5 472
1aaef614
VZ
473\membersection{wxMenu::Insert}\label{wxmenuinsert}
474
9add9367 475\func{wxMenuItem*}{Insert}{\param{size\_t }{pos}, \param{wxMenuItem *}{item}}
1aaef614 476
9add9367 477\func{wxMenuItem*}{Insert}{\param{size\_t }{pos}, \param{int}{ id},\rtfsp
ee0a94cf 478\param{const wxString\& }{ item = ""}, \param{const wxString\& }{helpString = ""},\rtfsp
98322660 479\param{wxItemKind}{ kind = wxITEM\_NORMAL}}
d65c269b 480
1aaef614 481Inserts the given {\it item} before the position {\it pos}. Inserting the item
3980000c 482at position \helpref{GetMenuItemCount}{wxmenugetmenuitemcount} is the same
1aaef614
VZ
483as appending it.
484
485\wxheading{See also}
486
d65c269b
VZ
487\helpref{wxMenu::Append}{wxmenuappend},\rtfsp
488\helpref{wxMenu::Prepend}{wxmenuprepend}
489
3786c8b5 490
d65c269b
VZ
491\membersection{wxMenu::InsertCheckItem}\label{wxmenuinsertcheckitem}
492
9add9367 493\func{wxMenuItem*}{InsertCheckItem}{\param{size\_t }{pos}, \param{int}{ id},\rtfsp
d65c269b
VZ
494\param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""}}
495
496Inserts a checkable item at the given position.
497
498\wxheading{See also}
499
500\helpref{wxMenu::Insert}{wxmenuinsert},\rtfsp
501\helpref{wxMenu::AppendCheckItem}{wxmenuappendcheckitem}
502
3786c8b5 503
d65c269b
VZ
504\membersection{wxMenu::InsertRadioItem}\label{wxmenuinsertradioitem}
505
9add9367 506\func{wxMenuItem*}{InsertRadioItem}{\param{size\_t }{pos}, \param{int}{ id},\rtfsp
d65c269b
VZ
507\param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""}}
508
509Inserts a radio item at the given position.
510
511\wxheading{See also}
512
513\helpref{wxMenu::Insert}{wxmenuinsert},\rtfsp
514\helpref{wxMenu::AppendRadioItem}{wxmenuappendradioitem}
515
3786c8b5 516
d65c269b
VZ
517\membersection{wxMenu::InsertSeparator}\label{wxmenuinsertseparator}
518
9add9367 519\func{wxMenuItem*}{InsertSeparator}{\param{size\_t }{pos}}
d65c269b
VZ
520
521Inserts a separator at the given position.
522
523\wxheading{See also}
524
525\helpref{wxMenu::Insert}{wxmenuinsert},\rtfsp
526\helpref{wxMenu::AppendSeparator}{wxmenuappendseparator}
1aaef614 527
3786c8b5 528
a660d684
KB
529\membersection{wxMenu::IsChecked}\label{wxmenuischecked}
530
eaaa6a06 531\constfunc{bool}{IsChecked}{\param{int}{ id}}
a660d684
KB
532
533Determines whether a menu item is checked.
534
535\wxheading{Parameters}
536
537\docparam{id}{The menu item identifier.}
538
539\wxheading{Return value}
540
cc81d32f 541true if the menu item is checked, false otherwise.
a660d684
KB
542
543\wxheading{See also}
544
545\helpref{wxMenu::Check}{wxmenucheck}
546
3786c8b5 547
a660d684
KB
548\membersection{wxMenu::IsEnabled}\label{wxmenuisenabled}
549
eaaa6a06 550\constfunc{bool}{IsEnabled}{\param{int}{ id}}
a660d684
KB
551
552Determines whether a menu item is enabled.
553
554\wxheading{Parameters}
555
556\docparam{id}{The menu item identifier.}
557
558\wxheading{Return value}
559
cc81d32f 560true if the menu item is enabled, false otherwise.
a660d684
KB
561
562\wxheading{See also}
563
564\helpref{wxMenu::Enable}{wxmenuenable}
565
3786c8b5 566
d65c269b
VZ
567\membersection{wxMenu::Prepend}\label{wxmenuprepend}
568
9add9367 569\func{wxMenuItem*}{Prepend}{\param{wxMenuItem *}{item}}
d65c269b 570
9add9367 571\func{wxMenuItem*}{Prepend}{\param{int}{ id},\rtfsp
ee0a94cf 572\param{const wxString\& }{ item = ""}, \param{const wxString\& }{helpString = ""},\rtfsp
98322660 573\param{wxItemKind}{ kind = wxITEM\_NORMAL}}
d65c269b 574
3980000c 575Inserts the given {\it item} at position $0$, i.e. before all the other
0cde01ae 576existing items.
d65c269b
VZ
577
578\wxheading{See also}
579
580\helpref{wxMenu::Append}{wxmenuappend},\rtfsp
3980000c 581\helpref{wxMenu::Insert}{wxmenuinsert}
d65c269b 582
3786c8b5 583
d65c269b
VZ
584\membersection{wxMenu::PrependCheckItem}\label{wxmenuprependcheckitem}
585
9add9367 586\func{wxMenuItem*}{PrependCheckItem}{\param{int}{ id},\rtfsp
d65c269b
VZ
587\param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""}}
588
3980000c 589Inserts a checkable item at position $0$.
d65c269b
VZ
590
591\wxheading{See also}
592
593\helpref{wxMenu::Prepend}{wxmenuprepend},\rtfsp
594\helpref{wxMenu::AppendCheckItem}{wxmenuappendcheckitem}
595
3786c8b5 596
d65c269b
VZ
597\membersection{wxMenu::PrependRadioItem}\label{wxmenuprependradioitem}
598
9add9367 599\func{wxMenuItem*}{PrependRadioItem}{\param{int}{ id},\rtfsp
d65c269b
VZ
600\param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""}}
601
3980000c 602Inserts a radio item at position $0$.
d65c269b
VZ
603
604\wxheading{See also}
605
606\helpref{wxMenu::Prepend}{wxmenuprepend},\rtfsp
607\helpref{wxMenu::AppendRadioItem}{wxmenuappendradioitem}
608
3786c8b5 609
d65c269b
VZ
610\membersection{wxMenu::PrependSeparator}\label{wxmenuprependseparator}
611
f6e9a818 612\func{wxMenuItem*}{PrependSeparator}{\void}
d65c269b 613
3980000c 614Inserts a separator at position $0$.
d65c269b
VZ
615
616\wxheading{See also}
617
618\helpref{wxMenu::Prepend}{wxmenuprepend},\rtfsp
619\helpref{wxMenu::AppendSeparator}{wxmenuappendseparator}
620
3786c8b5 621
1aaef614
VZ
622\membersection{wxMenu::Remove}\label{wxmenuremove}
623
624\func{wxMenuItem *}{Remove}{\param{int }{id}}
625
626\func{wxMenuItem *}{Remove}{\param{wxMenuItem *}{item}}
627
628Removes the menu item from the menu but doesn't delete the associated C++
629object. This allows to reuse the same item later by adding it back to the menu
630(especially useful with submenus).
631
632\wxheading{Parameters}
633
634\docparam{id}{The identifier of the menu item to remove.}
635
636\docparam{item}{The menu item to remove.}
637
638\wxheading{Return value}
639
640The item which was detached from the menu.
641
3786c8b5 642
a660d684
KB
643\membersection{wxMenu::SetHelpString}\label{wxmenusethelpstring}
644
eaaa6a06 645\func{void}{SetHelpString}{\param{int}{ id}, \param{const wxString\& }{helpString}}
a660d684
KB
646
647Sets an item's help string.
648
649\wxheading{Parameters}
650
651\docparam{id}{The menu item identifier.}
652
653\docparam{helpString}{The help string to set.}
654
655\wxheading{See also}
656
657\helpref{wxMenu::GetHelpString}{wxmenugethelpstring}
658
3786c8b5 659
a660d684
KB
660\membersection{wxMenu::SetLabel}\label{wxmenusetlabel}
661
eaaa6a06 662\func{void}{SetLabel}{\param{int}{ id}, \param{const wxString\& }{label}}
a660d684
KB
663
664Sets the label of a menu item.
665
666\wxheading{Parameters}
667
668\docparam{id}{The menu item identifier.}
669
670\docparam{label}{The menu item label to set.}
671
672\wxheading{See also}
673
674\helpref{wxMenu::Append}{wxmenuappend}, \helpref{wxMenu::GetLabel}{wxmenugetlabel}
675
3786c8b5 676
a660d684
KB
677\membersection{wxMenu::SetTitle}\label{wxmenusettitle}
678
679\func{void}{SetTitle}{\param{const wxString\& }{title}}
680
681Sets the title of the menu.
682
683\wxheading{Parameters}
684
685\docparam{title}{The title to set.}
686
687\wxheading{Remarks}
688
706f30f8
VZ
689This is relevant only to popup menus, use
690\helpref{wxMenuBar::SetLabelTop}{wxmenubarsetlabeltop} for the menus in the
691menubar.
a660d684
KB
692
693\wxheading{See also}
694
706f30f8 695\helpref{wxMenu::GetTitle}{wxmenugettitle}
a660d684 696
3786c8b5 697
631f1bfe
JS
698\membersection{wxMenu::UpdateUI}\label{wxmenuupdateui}
699
700\constfunc{void}{UpdateUI}{\param{wxEvtHandler*}{ source = NULL}}
701
702Sends events to {\it source} (or owning window if NULL) to update the
703menu UI. This is called just before the menu is popped up with \helpref{wxWindow::PopupMenu}{wxwindowpopupmenu}, but
704the application may call it at other times if required.
705
706\wxheading{See also}
707
708\helpref{wxUpdateUIEvent}{wxupdateuievent}
709
a660d684
KB
710\section{\class{wxMenuBar}}\label{wxmenubar}
711
712A menu bar is a series of menus accessible from the top of a frame.
713
714\wxheading{Derived from}
715
2138129e 716\helpref{wxWindow}{wxwindow}\\
a660d684
KB
717\helpref{wxEvtHandler}{wxevthandler}\\
718\helpref{wxObject}{wxobject}
719
954b8ae6
JS
720\wxheading{Include files}
721
722<wx/menu.h>
723
a660d684
KB
724\wxheading{Event handling}
725
726To respond to a menu selection, provide a handler for EVT\_MENU, in the frame
e702ff0f
JS
727that contains the menu bar. If you have a toolbar which uses the same identifiers
728as your EVT\_MENU entries, events from the toolbar will also be processed by your
729EVT\_MENU event handlers.
730
0ddef74d
JS
731{\bf Tip:} under Windows, if you discover that menu shortcuts (for example, Alt-F to show the file menu)
732are not working, check any EVT\_CHAR events you are handling in child windows.
733If you are not calling {\tt event.Skip()} for events that you don't process in these event handlers,
734menu shortcuts may cease to work.
735
a660d684
KB
736\wxheading{See also}
737
738\helpref{wxMenu}{wxmenu}, \helpref{Event handling overview}{eventhandlingoverview}
739
740\latexignore{\rtfignore{\wxheading{Members}}}
741
3786c8b5 742
dcbd177f 743\membersection{wxMenuBar::wxMenuBar}\label{wxmenubarctor}
a660d684 744
f6e9a818 745\func{}{wxMenuBar}{\param{long }{style = 0}}
a660d684
KB
746
747Default constructor.
748
294ea16d 749\func{}{wxMenuBar}{\param{size\_t}{ n}, \param{wxMenu*}{ menus[]}, \param{const wxString }{titles[]}, \param{long }{style = 0}}
a660d684
KB
750
751Construct a menu bar from arrays of menus and titles.
752
753\wxheading{Parameters}
754
755\docparam{n}{The number of menus.}
756
757\docparam{menus}{An array of menus. Do not use this array again - it now belongs to the
758menu bar.}
759
760\docparam{titles}{An array of title strings. Deallocate this array after creating the menu bar.}
761
d17f05af 762\docparam{style}{If {\tt wxMB\_DOCKABLE} the menu bar can be detached (wxGTK only).}
17e79918 763
06d20283 764\pythonnote{Only the default constructor is supported in wxPython.
294ea16d 765Use \helpref{wxMenuBar::Append}{wxmenubarappend} instead.}
06d20283 766
2edb0bde 767\perlnote{wxPerl only supports the first constructor:
294ea16d 768use \helpref{wxMenuBar::Append}{wxmenubarappend} instead.}
5873607e 769
3786c8b5 770
dcbd177f 771\membersection{wxMenuBar::\destruct{wxMenuBar}}\label{wxmenubardtor}
a660d684
KB
772
773\func{void}{\destruct{wxMenuBar}}{\void}
774
775Destructor, destroying the menu bar and removing it from the parent frame (if any).
776
3786c8b5 777
a660d684
KB
778\membersection{wxMenuBar::Append}\label{wxmenubarappend}
779
1aaef614 780\func{bool}{Append}{\param{wxMenu *}{menu}, \param{const wxString\& }{title}}
a660d684
KB
781
782Adds the item to the end of the menu bar.
783
784\wxheading{Parameters}
785
786\docparam{menu}{The menu to add. Do not deallocate this menu after calling {\bf Append}.}
787
788\docparam{title}{The title of the menu.}
789
1aaef614
VZ
790\wxheading{Return value}
791
cc81d32f 792true on success, false if an error occurred.
1aaef614
VZ
793
794\wxheading{See also}
795
796\helpref{wxMenuBar::Insert}{wxmenubarinsert}
797
3786c8b5 798
a660d684
KB
799\membersection{wxMenuBar::Check}\label{wxmenubarcheck}
800
eaaa6a06 801\func{void}{Check}{\param{int}{ id}, \param{const bool}{ check}}
a660d684
KB
802
803Checks or unchecks a menu item.
804
805\wxheading{Parameters}
806
807\docparam{id}{The menu item identifier.}
808
cc81d32f 809\docparam{check}{If true, checks the menu item, otherwise the item is unchecked.}
a660d684
KB
810
811\wxheading{Remarks}
812
813Only use this when the menu bar has been associated
814with a frame; otherwise, use the wxMenu equivalent call.
815
3786c8b5 816
a660d684
KB
817\membersection{wxMenuBar::Enable}\label{wxmenubarenable}
818
eaaa6a06 819\func{void}{Enable}{\param{int}{ id}, \param{const bool}{ enable}}
a660d684
KB
820
821Enables or disables (greys out) a menu item.
822
823\wxheading{Parameters}
824
825\docparam{id}{The menu item identifier.}
826
cc81d32f 827\docparam{enable}{true to enable the item, false to disable it.}
a660d684
KB
828
829\wxheading{Remarks}
830
831Only use this when the menu bar has been
832associated with a frame; otherwise, use the wxMenu equivalent call.
833
3786c8b5 834
a660d684
KB
835\membersection{wxMenuBar::EnableTop}\label{wxmenubarenabletop}
836
eaaa6a06 837\func{void}{EnableTop}{\param{int}{ pos}, \param{const bool}{ enable}}
a660d684
KB
838
839Enables or disables a whole menu.
840
841\wxheading{Parameters}
842
843\docparam{pos}{The position of the menu, starting from zero.}
844
cc81d32f 845\docparam{enable}{true to enable the menu, false to disable it.}
a660d684
KB
846
847\wxheading{Remarks}
848
849Only use this when the menu bar has been
850associated with a frame.
851
3786c8b5 852
270e8b6a
VZ
853\membersection{wxMenuBar::FindMenu}\label{wxmenubarfindmenu}
854
855\constfunc{int}{FindMenu}{\param{const wxString\& }{title}}
856
a8d08dbd 857Returns the index of the menu with the given {\it title} or {\tt wxNOT\_FOUND} if no
270e8b6a
VZ
858such menu exists in this menubar. The {\it title} parameter may specify either
859the menu title (with accelerator characters, i.e. {\tt "\&File"}) or just the
860menu label ({\tt "File"}) indifferently.
861
3786c8b5 862
a660d684
KB
863\membersection{wxMenuBar::FindMenuItem}\label{wxmenubarfindmenuitem}
864
865\constfunc{int}{FindMenuItem}{\param{const wxString\& }{menuString}, \param{const wxString\& }{itemString}}
866
867Finds the menu item id for a menu name/menu item string pair.
868
869\wxheading{Parameters}
870
871\docparam{menuString}{Menu title to find.}
872
873\docparam{itemString}{Item to find.}
874
875\wxheading{Return value}
876
a8d08dbd 877The menu item identifier, or {\tt wxNOT\_FOUND} if none was found.
a660d684
KB
878
879\wxheading{Remarks}
880
881Any special menu codes are stripped out of source and target strings
882before matching.
883
3786c8b5 884
fc9c7c09 885\membersection{wxMenuBar::FindItem}\label{wxmenubarfinditem}
a660d684 886
407f3681 887\constfunc{wxMenuItem *}{FindItem}{\param{int}{ id}, \param{wxMenu}{ **menu = NULL}}
a660d684 888
fc9c7c09 889Finds the menu item object associated with the given menu item identifier.
a660d684
KB
890
891\wxheading{Parameters}
892
893\docparam{id}{Menu item identifier.}
407f3681 894
fc9c7c09 895\docparam{menu}{If not NULL, menu will get set to the associated menu.}
a660d684
KB
896
897\wxheading{Return value}
898
899The found menu item object, or NULL if one was not found.
900
3786c8b5 901
a660d684
KB
902\membersection{wxMenuBar::GetHelpString}\label{wxmenubargethelpstring}
903
eaaa6a06 904\constfunc{wxString}{GetHelpString}{\param{int}{ id}}
a660d684 905
2edb0bde 906Gets the help string associated with the menu item identifier.
a660d684
KB
907
908\wxheading{Parameters}
909
910\docparam{id}{The menu item identifier.}
911
912\wxheading{Return value}
913
914The help string, or the empty string if there was no help string or the menu item
915was not found.
916
917\wxheading{See also}
918
919\helpref{wxMenuBar::SetHelpString}{wxmenubarsethelpstring}
920
3786c8b5 921
a660d684
KB
922\membersection{wxMenuBar::GetLabel}\label{wxmenubargetlabel}
923
eaaa6a06 924\constfunc{wxString}{GetLabel}{\param{int}{ id}}
a660d684
KB
925
926Gets the label associated with a menu item.
927
928\wxheading{Parameters}
929
930\docparam{id}{The menu item identifier.}
931
932\wxheading{Return value}
933
934The menu item label, or the empty string if the item was not found.
935
936\wxheading{Remarks}
937
938Use only after the menubar has been associated with a frame.
939
3786c8b5 940
a660d684
KB
941\membersection{wxMenuBar::GetLabelTop}\label{wxmenubargetlabeltop}
942
eaaa6a06 943\constfunc{wxString}{GetLabelTop}{\param{int}{ pos}}
a660d684 944
706f30f8
VZ
945Returns the label of a top-level menu. Note that the returned string does not
946include the accelerator characters which could have been specified in the menu
947title string during its construction.
a660d684
KB
948
949\wxheading{Parameters}
950
951\docparam{pos}{Position of the menu on the menu bar, starting from zero.}
952
953\wxheading{Return value}
954
955The menu label, or the empty string if the menu was not found.
956
957\wxheading{Remarks}
958
959Use only after the menubar has been associated with a frame.
960
961\wxheading{See also}
962
963\helpref{wxMenuBar::SetLabelTop}{wxmenubarsetlabeltop}
964
3786c8b5 965
7f555861
JS
966\membersection{wxMenuBar::GetMenu}\label{wxmenubargetmenu}
967
968\constfunc{wxMenu*}{GetMenu}{\param{int}{ menuIndex}}
969
970Returns the menu at {\it menuIndex} (zero-based).
971
3786c8b5 972
7f555861
JS
973\membersection{wxMenuBar::GetMenuCount}\label{wxmenubargetmenucount}
974
975\constfunc{int}{GetMenuCount}{\void}
976
977Returns the number of menus in this menubar.
978
3786c8b5 979
e12be2f7 980\membersection{wxMenuBar::Insert}\label{wxmenubarinsert}
1aaef614
VZ
981
982\func{bool}{Insert}{\param{size\_t }{pos}, \param{wxMenu *}{menu}, \param{const wxString\& }{title}}
983
984Inserts the menu at the given position into the menu bar. Inserting menu at
fa482912
JS
985position $0$ will insert it in the very beginning of it, inserting at position
986\helpref{GetMenuCount()}{wxmenubargetmenucount} is the same as calling
1aaef614
VZ
987\helpref{Append()}{wxmenubarappend}.
988
989\wxheading{Parameters}
990
991\docparam{pos}{The position of the new menu in the menu bar}
992
993\docparam{menu}{The menu to add. wxMenuBar owns the menu and will free it.}
994
995\docparam{title}{The title of the menu.}
996
997\wxheading{Return value}
998
cc81d32f 999true on success, false if an error occurred.
1aaef614
VZ
1000
1001\wxheading{See also}
1002
1003\helpref{wxMenuBar::Append}{wxmenubarappend}
1004
3786c8b5 1005
a660d684
KB
1006\membersection{wxMenuBar::IsChecked}\label{wxmenubarischecked}
1007
eaaa6a06 1008\constfunc{bool}{IsChecked}{\param{int}{ id}}
a660d684
KB
1009
1010Determines whether an item is checked.
1011
1012\wxheading{Parameters}
1013
1014\docparam{id}{The menu item identifier.}
1015
1016\wxheading{Return value}
1017
cc81d32f 1018true if the item was found and is checked, false otherwise.
a660d684 1019
3786c8b5 1020
a660d684
KB
1021\membersection{wxMenuBar::IsEnabled}\label{wxmenubarisenabled}
1022
eaaa6a06 1023\constfunc{bool}{IsEnabled}{\param{int}{ id}}
a660d684
KB
1024
1025Determines whether an item is enabled.
1026
1027\wxheading{Parameters}
1028
1029\docparam{id}{The menu item identifier.}
1030
1031\wxheading{Return value}
1032
cc81d32f 1033true if the item was found and is enabled, false otherwise.
a660d684 1034
3786c8b5 1035
63dcfc15
PA
1036\membersection{wxMenuBar::Refresh}\label{wxmenubarrefresh}
1037
1038\func{void}{Refresh}{\void}
1039
1040Redraw the menu bar
1041
3786c8b5 1042
1aaef614
VZ
1043\membersection{wxMenuBar::Remove}\label{wxmenubarremove}
1044
1045\func{wxMenu *}{Remove}{\param{size\_t }{pos}}
1046
1047Removes the menu from the menu bar and returns the menu object - the caller is
d7d17624 1048responsible for deleting it. This function may be used together with
1aaef614
VZ
1049\helpref{wxMenuBar::Insert}{wxmenubarinsert} to change the menubar
1050dynamically.
1051
1052\wxheading{See also}
1053
2182e26f 1054\helpref{wxMenuBar::Replace}{wxmenubarreplace}
1aaef614 1055
3786c8b5 1056
1aaef614
VZ
1057\membersection{wxMenuBar::Replace}\label{wxmenubarreplace}
1058
1059\func{wxMenu *}{Replace}{\param{size\_t }{pos}, \param{wxMenu *}{menu}, \param{const wxString\& }{title}}
1060
fa482912 1061Replaces the menu at the given position with another one.
1aaef614
VZ
1062
1063\wxheading{Parameters}
1064
1065\docparam{pos}{The position of the new menu in the menu bar}
1066
1067\docparam{menu}{The menu to add.}
1068
1069\docparam{title}{The title of the menu.}
1070
1071\wxheading{Return value}
1072
3980000c 1073The menu which was previously at position {\it pos}. The caller is
1aaef614
VZ
1074responsible for deleting it.
1075
1076\wxheading{See also}
1077
1078\helpref{wxMenuBar::Insert}{wxmenubarinsert},\rtfsp
1079\helpref{wxMenuBar::Remove}{wxmenubarremove}
1080
3786c8b5 1081
a660d684
KB
1082\membersection{wxMenuBar::SetHelpString}\label{wxmenubarsethelpstring}
1083
eaaa6a06 1084\func{void}{SetHelpString}{\param{int}{ id}, \param{const wxString\& }{helpString}}
a660d684
KB
1085
1086Sets the help string associated with a menu item.
1087
1088\wxheading{Parameters}
1089
1090\docparam{id}{Menu item identifier.}
1091
1092\docparam{helpString}{Help string to associate with the menu item.}
1093
1094\wxheading{See also}
1095
1096\helpref{wxMenuBar::GetHelpString}{wxmenubargethelpstring}
1097
3786c8b5 1098
a660d684
KB
1099\membersection{wxMenuBar::SetLabel}\label{wxmenubarsetlabel}
1100
eaaa6a06 1101\func{void}{SetLabel}{\param{int}{ id}, \param{const wxString\& }{label}}
a660d684
KB
1102
1103Sets the label of a menu item.
1104
1105\wxheading{Parameters}
1106
1107\docparam{id}{Menu item identifier.}
1108
1109\docparam{label}{Menu item label.}
1110
1111\wxheading{Remarks}
1112
1113Use only after the menubar has been associated with a frame.
1114
1115\wxheading{See also}
1116
1117\helpref{wxMenuBar::GetLabel}{wxmenubargetlabel}
1118
3786c8b5 1119
a660d684
KB
1120\membersection{wxMenuBar::SetLabelTop}\label{wxmenubarsetlabeltop}
1121
eaaa6a06 1122\func{void}{SetLabelTop}{\param{int}{ pos}, \param{const wxString\& }{label}}
a660d684
KB
1123
1124Sets the label of a top-level menu.
1125
1126\wxheading{Parameters}
1127
1128\docparam{pos}{The position of a menu on the menu bar, starting from zero.}
1129
1130\docparam{label}{The menu label.}
1131
1132\wxheading{Remarks}
1133
1134Use only after the menubar has been associated with a frame.
1135
1136\wxheading{See also}
1137
1138\helpref{wxMenuBar::GetLabelTop}{wxmenubargetlabeltop}
1139