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