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