]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/menu.tex
documented wxCONFIG_USE_RELATIVE_PATH
[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.
9
10 \wxheading{Derived from}
11
12 \helpref{wxEvtHandler}{wxevthandler}\\
13 \helpref{wxObject}{wxobject}
14
15 \wxheading{Include files}
16
17 <wx/menu.h>
18
19 \wxheading{Event handling}
20
21 If the menu is part of a menubar, then \helpref{wxMenuBar}{wxmenubar} event processing is used.
22
23 With a popup menu, there is a variety of ways to handle a menu selection event
24 (wxEVT\_COMMAND\_MENU\_SELECTED).
25
26 \begin{enumerate}\itemsep=0pt
27 \item Define a callback of type wxFunction, which you pass to the wxMenu constructor.
28 The callback takes a reference to the menu, and a reference to a \helpref{wxCommandEvent}{wxcommandevent}.
29 \item Derive a new class from wxMenu and define event table entries using the EVT\_MENU macro.
30 \item Set a new event handler for wxMenu, using an object whose class has EVT\_MENU entries.
31 \item Provide EVT\_MENU handlers in the window which pops up the menu, or in an ancestor of
32 this window.
33 \end{enumerate}
34
35 \wxheading{See also}
36
37 \helpref{wxMenuBar}{wxmenubar}, \helpref{wxWindow::PopupMenu}{wxwindowpopupmenu},\rtfsp
38 \helpref{Event handling overview}{eventhandlingoverview}
39
40 \latexignore{\rtfignore{\wxheading{Members}}}
41
42 \membersection{wxMenu::wxMenu}\label{wxmenuconstr}
43
44 \func{}{wxMenu}{\param{const wxString\& }{title = ""}, \param{const wxFunction}{ func = NULL}}
45
46 Constructs a wxMenu object.
47
48 \wxheading{Parameters}
49
50 \docparam{title}{A title for the popup menu: the empty string denotes no title.}
51
52 \docparam{func}{A callback function if the menu is used as a popup using \helpref{wxWindow::PopupMenu}{wxwindowpopupmenu}.}
53
54 \pythonnote{The wxPython version of the \tt{wxMenu} constructor
55 doesn't accept the callback argument because of reference counting
56 issues. There is a specialized wxMenu constructor called
57 \tt{wxPyMenu} which does and can be used for PopupMenus when callbacks
58 are needed. You must retain a reference to the menu while useing it
59 otherwise your callback function will get dereferenced when the menu
60 does.
61 }
62
63 \membersection{wxMenu::\destruct{wxMenu}}
64
65 \func{}{\destruct{wxMenu}}{\void}
66
67 Destructor, destroying the menu.
68
69 Note: under Motif, a popup menu must have a valid parent (the window
70 it was last popped up on) when being destroyed. Therefore, make sure
71 you delete or re-use the popup menu {\it before} destroying the
72 parent window. Re-use in this context means popping up the menu on
73 a different window from last time, which causes an implicit destruction
74 and recreation of internal data structures.
75
76 \membersection{wxMenu::Append}\label{wxmenuappend}
77
78 \func{void}{Append}{\param{int}{ id}, \param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""},\rtfsp
79 \param{const bool}{ checkable = FALSE}}
80
81 Adds a string item to the end of the menu.
82
83 \func{void}{Append}{\param{int}{ id}, \param{const wxString\& }{ item}, \param{wxMenu *}{subMenu},\rtfsp
84 \param{const wxString\& }{helpString = ""}}
85
86 Adds a pull-right submenu to the end of the menu.
87
88 \func{void}{Append}{\param{wxMenuItem*}{ menuItem}}
89
90 Adds a menu item object. You can specify various extra properties of a menu item this way,
91 such as bitmaps and fonts.
92
93 \wxheading{Parameters}
94
95 \docparam{id}{The menu command identifier.}
96
97 \docparam{item}{The string to appear on the menu item.}
98
99 \docparam{menu}{Pull-right submenu.}
100
101 \docparam{checkable}{If TRUE, this item is checkable.}
102
103 \docparam{helpString}{An optional help string associated with the item.
104 By default, \helpref{wxFrame::OnMenuHighlight}{wxframeonmenuhighlight} displays
105 this string in the status line.}
106
107 \docparam{menuItem}{A menuitem object. It will be owned by the wxMenu object after this function
108 is called, so do not delete it yourself.}
109
110 \wxheading{Remarks}
111
112 This command can be used after the menu has been shown, as well as on initial
113 creation of a menu or menubar.
114
115 \wxheading{See also}
116
117 \helpref{wxMenu::AppendSeparator}{wxmenuappendseparator}, \helpref{wxMenu::SetLabel}{wxmenusetlabel}, \helpref{wxMenu::GetHelpString}{wxmenugethelpstring},\rtfsp
118 \helpref{wxMenu::SetHelpString}{wxmenusethelpstring}, \helpref{wxMenuItem}{wxmenuitem}
119
120
121 \pythonnote{In place of a single overloaded method name, wxPython
122 implements the following methods:\par
123 \indented{2cm}{\begin{twocollist}
124 \twocolitem{\bf{Append(id, string, helpStr="", checkable=FALSE)}}{}
125 \twocolitem{\bf{AppendMenu(id, string, aMenu, helpStr="")}}{}
126 \twocolitem{\bf{AppendItem(aMenuItem)}}{}
127 \end{twocollist}}
128 }
129
130
131 \membersection{wxMenu::AppendSeparator}\label{wxmenuappendseparator}
132
133 \func{void}{AppendSeparator}{\void}
134
135 Adds a separator to the end of the menu.
136
137 \wxheading{See also}
138
139 \helpref{wxMenu::Append}{wxmenuappend}
140
141 \membersection{wxMenu::Break}\label{wxmenubreak}
142
143 \func{void}{Break}{\void}
144
145 Inserts a break in a menu, causing the next appended item to appear in a new column.
146
147 \membersection{wxMenu::Check}\label{wxmenucheck}
148
149 \func{void}{Check}{\param{int}{ id}, \param{const bool}{ check}}
150
151 Checks or unchecks the menu item.
152
153 \wxheading{Parameters}
154
155 \docparam{id}{The menu item identifier.}
156
157 \docparam{check}{If TRUE, the item will be checked, otherwise it will be unchecked.}
158
159 \wxheading{See also}
160
161 \helpref{wxMenu::IsChecked}{wxmenuischecked}
162
163 \membersection{wxMenu::Enable}\label{wxmenuenable}
164
165 \func{void}{Enable}{\param{int}{ id}, \param{const bool}{ enable}}
166
167 Enables or disables (greys out) a menu item.
168
169 \wxheading{Parameters}
170
171 \docparam{id}{The menu item identifier.}
172
173 \docparam{enable}{TRUE to enable the menu item, FALSE to disable it.}
174
175 \wxheading{See also}
176
177 \helpref{wxMenu::IsEnabled}{wxmenuisenabled}
178
179 \membersection{wxMenu::FindItem}\label{wxmenufinditem}
180
181 \constfunc{int}{FindItem}{\param{const wxString\& }{itemString}}
182
183 Finds the menu item id for a menu item string.
184
185 \wxheading{Parameters}
186
187 \docparam{itemString}{Menu item string to find.}
188
189 \wxheading{Return value}
190
191 Menu item identifier, or -1 if none is found.
192
193 \wxheading{Remarks}
194
195 Any special menu codes are stripped out of source and target strings
196 before matching.
197
198 \wxheading{See also}
199
200 \helpref{wxMenu::FindItemForId}{wxmenufinditemforid}
201
202 \membersection{wxMenu::FindItemForId}\label{wxmenufinditemforid}
203
204 \constfunc{wxMenuItem*}{FindItemForId}{\param{int}{ id}, \param{wxMenu **}{ menuForItem = NULL}}
205
206 Finds the menu item object associated with the given menu item identifier.
207
208 \wxheading{Parameters}
209
210 \docparam{id}{Menu item identifier.}
211 \docparam{menuForItem}{will be filled with the menu for this item if not NULL.}
212
213 \wxheading{Return value}
214
215 Returns the menu item object, or NULL if it is not found.
216
217 \wxheading{See also}
218
219 \helpref{wxMenu::FindItem}{wxmenufinditem}
220
221 \membersection{wxMenu::GetHelpString}\label{wxmenugethelpstring}
222
223 \constfunc{wxString}{GetHelpString}{\param{int}{ id}}
224
225 Returns the help string associated with a menu item.
226
227 \wxheading{Parameters}
228
229 \docparam{id}{The menu item identifier.}
230
231 \wxheading{Return value}
232
233 The help string, or the empty string if there is no help string or the
234 item was not found.
235
236 \wxheading{See also}
237
238 \helpref{wxMenu::SetHelpString}{wxmenusethelpstring}, \helpref{wxMenu::Append}{wxmenuappend}
239
240 \membersection{wxMenu::GetLabel}\label{wxmenugetlabel}
241
242 \constfunc{wxString}{GetLabel}{\param{int}{ id}}
243
244 Returns a menu item label.
245
246 \wxheading{Parameters}
247
248 \docparam{id}{The menu item identifier.}
249
250 \wxheading{Return value}
251
252 The item label, or the empty string if the item was not found.
253
254 \wxheading{See also}
255
256 \helpref{wxMenu::SetLabel}{wxmenusetlabel}
257
258 \membersection{wxMenu::GetTitle}\label{wxmenugettitle}
259
260 \constfunc{wxString}{GetTitle}{\void}
261
262 Returns the title of the menu.
263
264 \wxheading{Remarks}
265
266 This is relevant only to popup menus.
267
268 \wxheading{See also}
269
270 \helpref{wxMenu::SetTitle}{wxmenusettitle}
271
272 \membersection{wxMenu::IsChecked}\label{wxmenuischecked}
273
274 \constfunc{bool}{IsChecked}{\param{int}{ id}}
275
276 Determines whether a menu item is checked.
277
278 \wxheading{Parameters}
279
280 \docparam{id}{The menu item identifier.}
281
282 \wxheading{Return value}
283
284 TRUE if the menu item is checked, FALSE otherwise.
285
286 \wxheading{See also}
287
288 \helpref{wxMenu::Check}{wxmenucheck}
289
290 \membersection{wxMenu::IsEnabled}\label{wxmenuisenabled}
291
292 \constfunc{bool}{IsEnabled}{\param{int}{ id}}
293
294 Determines whether a menu item is enabled.
295
296 \wxheading{Parameters}
297
298 \docparam{id}{The menu item identifier.}
299
300 \wxheading{Return value}
301
302 TRUE if the menu item is enabled, FALSE otherwise.
303
304 \wxheading{See also}
305
306 \helpref{wxMenu::Enable}{wxmenuenable}
307
308 \membersection{wxMenu::SetHelpString}\label{wxmenusethelpstring}
309
310 \func{void}{SetHelpString}{\param{int}{ id}, \param{const wxString\& }{helpString}}
311
312 Sets an item's help string.
313
314 \wxheading{Parameters}
315
316 \docparam{id}{The menu item identifier.}
317
318 \docparam{helpString}{The help string to set.}
319
320 \wxheading{See also}
321
322 \helpref{wxMenu::GetHelpString}{wxmenugethelpstring}
323
324 \membersection{wxMenu::SetLabel}\label{wxmenusetlabel}
325
326 \func{void}{SetLabel}{\param{int}{ id}, \param{const wxString\& }{label}}
327
328 Sets the label of a menu item.
329
330 \wxheading{Parameters}
331
332 \docparam{id}{The menu item identifier.}
333
334 \docparam{label}{The menu item label to set.}
335
336 \wxheading{See also}
337
338 \helpref{wxMenu::Append}{wxmenuappend}, \helpref{wxMenu::GetLabel}{wxmenugetlabel}
339
340 \membersection{wxMenu::SetTitle}\label{wxmenusettitle}
341
342 \func{void}{SetTitle}{\param{const wxString\& }{title}}
343
344 Sets the title of the menu.
345
346 \wxheading{Parameters}
347
348 \docparam{title}{The title to set.}
349
350 \wxheading{Remarks}
351
352 This is relevant only to popup menus.
353
354 \wxheading{See also}
355
356 \helpref{wxMenu::SetTitle}{wxmenusettitle}
357
358 \membersection{wxMenu::UpdateUI}\label{wxmenuupdateui}
359
360 \constfunc{void}{UpdateUI}{\param{wxEvtHandler*}{ source = NULL}}
361
362 Sends events to {\it source} (or owning window if NULL) to update the
363 menu UI. This is called just before the menu is popped up with \helpref{wxWindow::PopupMenu}{wxwindowpopupmenu}, but
364 the application may call it at other times if required.
365
366 \wxheading{See also}
367
368 \helpref{wxUpdateUIEvent}{wxupdateuievent}
369
370 \section{\class{wxMenuBar}}\label{wxmenubar}
371
372 A menu bar is a series of menus accessible from the top of a frame.
373
374 \wxheading{Derived from}
375
376 \helpref{wxEvtHandler}{wxevthandler}\\
377 \helpref{wxObject}{wxobject}
378
379 \wxheading{Include files}
380
381 <wx/menu.h>
382
383 \wxheading{Event handling}
384
385 To respond to a menu selection, provide a handler for EVT\_MENU, in the frame
386 that contains the menu bar. If you have a toolbar which uses the same identifiers
387 as your EVT\_MENU entries, events from the toolbar will also be processed by your
388 EVT\_MENU event handlers.
389
390 Note that menu commands (and UI update events for menus) are first sent to
391 the focus window within the frame. If no window within the frame has the focus,
392 then the events are sent directly to the frame. This allows command and UI update
393 handling to be processed by specific windows and controls, and not necessarily
394 by the application frame.
395
396 \wxheading{See also}
397
398 \helpref{wxMenu}{wxmenu}, \helpref{Event handling overview}{eventhandlingoverview}
399
400 \latexignore{\rtfignore{\wxheading{Members}}}
401
402 \membersection{wxMenuBar::wxMenuBar}\label{wxmenubarconstr}
403
404 \func{void}{wxMenuBar}{\void}
405
406 Default constructor.
407
408 \func{void}{wxMenuBar}{\param{int}{ n}, \param{wxMenu*}{ menus[]}, \param{const wxString }{titles[]}}
409
410 Construct a menu bar from arrays of menus and titles.
411
412 \wxheading{Parameters}
413
414 \docparam{n}{The number of menus.}
415
416 \docparam{menus}{An array of menus. Do not use this array again - it now belongs to the
417 menu bar.}
418
419 \docparam{titles}{An array of title strings. Deallocate this array after creating the menu bar.}
420
421 \pythonnote{Only the default constructor is supported in wxPython.
422 Use wxMenuBar.Append instead.}
423
424
425 \membersection{wxMenuBar::\destruct{wxMenuBar}}
426
427 \func{void}{\destruct{wxMenuBar}}{\void}
428
429 Destructor, destroying the menu bar and removing it from the parent frame (if any).
430
431 \membersection{wxMenuBar::Append}\label{wxmenubarappend}
432
433 \func{void}{Append}{\param{wxMenu *}{menu}, \param{const wxString\& }{title}}
434
435 Adds the item to the end of the menu bar.
436
437 \wxheading{Parameters}
438
439 \docparam{menu}{The menu to add. Do not deallocate this menu after calling {\bf Append}.}
440
441 \docparam{title}{The title of the menu.}
442
443 \membersection{wxMenuBar::Check}\label{wxmenubarcheck}
444
445 \func{void}{Check}{\param{int}{ id}, \param{const bool}{ check}}
446
447 Checks or unchecks a menu item.
448
449 \wxheading{Parameters}
450
451 \docparam{id}{The menu item identifier.}
452
453 \docparam{check}{If TRUE, checks the menu item, otherwise the item is unchecked.}
454
455 \wxheading{Remarks}
456
457 Only use this when the menu bar has been associated
458 with a frame; otherwise, use the wxMenu equivalent call.
459
460 \membersection{wxMenuBar::Enable}\label{wxmenubarenable}
461
462 \func{void}{Enable}{\param{int}{ id}, \param{const bool}{ enable}}
463
464 Enables or disables (greys out) a menu item.
465
466 \wxheading{Parameters}
467
468 \docparam{id}{The menu item identifier.}
469
470 \docparam{enable}{TRUE to enable the item, FALSE to disable it.}
471
472 \wxheading{Remarks}
473
474 Only use this when the menu bar has been
475 associated with a frame; otherwise, use the wxMenu equivalent call.
476
477 \membersection{wxMenuBar::EnableTop}\label{wxmenubarenabletop}
478
479 \func{void}{EnableTop}{\param{int}{ pos}, \param{const bool}{ enable}}
480
481 Enables or disables a whole menu.
482
483 \wxheading{Parameters}
484
485 \docparam{pos}{The position of the menu, starting from zero.}
486
487 \docparam{enable}{TRUE to enable the menu, FALSE to disable it.}
488
489 \wxheading{Remarks}
490
491 Only use this when the menu bar has been
492 associated with a frame.
493
494 \membersection{wxMenuBar::FindMenuItem}\label{wxmenubarfindmenuitem}
495
496 \constfunc{int}{FindMenuItem}{\param{const wxString\& }{menuString}, \param{const wxString\& }{itemString}}
497
498 Finds the menu item id for a menu name/menu item string pair.
499
500 \wxheading{Parameters}
501
502 \docparam{menuString}{Menu title to find.}
503
504 \docparam{itemString}{Item to find.}
505
506 \wxheading{Return value}
507
508 The menu item identifier, or -1 if none was found.
509
510 \wxheading{Remarks}
511
512 Any special menu codes are stripped out of source and target strings
513 before matching.
514
515 \membersection{wxMenuBar::FindItemForId}\label{wxmenubarfinditemforid}
516
517 \constfunc{wxMenuItem *}{FindItemForId}{\param{int}{ id}}
518
519 Finds the menu item object associated with the given menu item identifier,
520
521 \wxheading{Parameters}
522
523 \docparam{id}{Menu item identifier.}
524
525 \wxheading{Return value}
526
527 The found menu item object, or NULL if one was not found.
528
529 \membersection{wxMenuBar::GetHelpString}\label{wxmenubargethelpstring}
530
531 \constfunc{wxString}{GetHelpString}{\param{int}{ id}}
532
533 Gets the help string associated with the menu item identifer.
534
535 \wxheading{Parameters}
536
537 \docparam{id}{The menu item identifier.}
538
539 \wxheading{Return value}
540
541 The help string, or the empty string if there was no help string or the menu item
542 was not found.
543
544 \wxheading{See also}
545
546 \helpref{wxMenuBar::SetHelpString}{wxmenubarsethelpstring}
547
548 \membersection{wxMenuBar::GetLabel}\label{wxmenubargetlabel}
549
550 \constfunc{wxString}{GetLabel}{\param{int}{ id}}
551
552 Gets the label associated with a menu item.
553
554 \wxheading{Parameters}
555
556 \docparam{id}{The menu item identifier.}
557
558 \wxheading{Return value}
559
560 The menu item label, or the empty string if the item was not found.
561
562 \wxheading{Remarks}
563
564 Use only after the menubar has been associated with a frame.
565
566 \membersection{wxMenuBar::GetLabelTop}\label{wxmenubargetlabeltop}
567
568 \constfunc{wxString}{GetLabelTop}{\param{int}{ pos}}
569
570 Returns the label of a top-level menu.
571
572 \wxheading{Parameters}
573
574 \docparam{pos}{Position of the menu on the menu bar, starting from zero.}
575
576 \wxheading{Return value}
577
578 The menu label, or the empty string if the menu was not found.
579
580 \wxheading{Remarks}
581
582 Use only after the menubar has been associated with a frame.
583
584 \wxheading{See also}
585
586 \helpref{wxMenuBar::SetLabelTop}{wxmenubarsetlabeltop}
587
588 \membersection{wxMenuBar::GetMenu}\label{wxmenubargetmenu}
589
590 \constfunc{wxMenu*}{GetMenu}{\param{int}{ menuIndex}}
591
592 Returns the menu at {\it menuIndex} (zero-based).
593
594 \membersection{wxMenuBar::GetMenuCount}\label{wxmenubargetmenucount}
595
596 \constfunc{int}{GetMenuCount}{\void}
597
598 Returns the number of menus in this menubar.
599
600 \membersection{wxMenuBar::IsChecked}\label{wxmenubarischecked}
601
602 \constfunc{bool}{IsChecked}{\param{int}{ id}}
603
604 Determines whether an item is checked.
605
606 \wxheading{Parameters}
607
608 \docparam{id}{The menu item identifier.}
609
610 \wxheading{Return value}
611
612 TRUE if the item was found and is checked, FALSE otherwise.
613
614 \membersection{wxMenuBar::IsEnabled}\label{wxmenubarisenabled}
615
616 \constfunc{bool}{IsEnabled}{\param{int}{ id}}
617
618 Determines whether an item is enabled.
619
620 \wxheading{Parameters}
621
622 \docparam{id}{The menu item identifier.}
623
624 \wxheading{Return value}
625
626 TRUE if the item was found and is enabled, FALSE otherwise.
627
628 \membersection{wxMenuBar::SetHelpString}\label{wxmenubarsethelpstring}
629
630 \func{void}{SetHelpString}{\param{int}{ id}, \param{const wxString\& }{helpString}}
631
632 Sets the help string associated with a menu item.
633
634 \wxheading{Parameters}
635
636 \docparam{id}{Menu item identifier.}
637
638 \docparam{helpString}{Help string to associate with the menu item.}
639
640 \wxheading{See also}
641
642 \helpref{wxMenuBar::GetHelpString}{wxmenubargethelpstring}
643
644 \membersection{wxMenuBar::SetLabel}\label{wxmenubarsetlabel}
645
646 \func{void}{SetLabel}{\param{int}{ id}, \param{const wxString\& }{label}}
647
648 Sets the label of a menu item.
649
650 \wxheading{Parameters}
651
652 \docparam{id}{Menu item identifier.}
653
654 \docparam{label}{Menu item label.}
655
656 \wxheading{Remarks}
657
658 Use only after the menubar has been associated with a frame.
659
660 \wxheading{See also}
661
662 \helpref{wxMenuBar::GetLabel}{wxmenubargetlabel}
663
664 \membersection{wxMenuBar::SetLabelTop}\label{wxmenubarsetlabeltop}
665
666 \func{void}{SetLabelTop}{\param{int}{ pos}, \param{const wxString\& }{label}}
667
668 Sets the label of a top-level menu.
669
670 \wxheading{Parameters}
671
672 \docparam{pos}{The position of a menu on the menu bar, starting from zero.}
673
674 \docparam{label}{The menu label.}
675
676 \wxheading{Remarks}
677
678 Use only after the menubar has been associated with a frame.
679
680 \wxheading{See also}
681
682 \helpref{wxMenuBar::GetLabelTop}{wxmenubargetlabeltop}
683