]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/menu.tex
Unicode overview added
[wxWidgets.git] / docs / latex / wx / menu.tex
... / ...
CommitLineData
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
15\wxheading{Include files}
16
17<wx/menu.h>
18
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.
28The 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
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
44\func{}{wxMenu}{\param{const wxString\& }{title = ""},
45 \param{const wxFunction}{ func = NULL}\param{long}{ style = 0}}
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
55\docparam{style}{If set to \tt{wxMENU_TEAROFF}, the menu will be detachable.}
56
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
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
73\membersection{wxMenu::\destruct{wxMenu}}
74
75\func{}{\destruct{wxMenu}}{\void}
76
77Destructor, destroying the menu.
78
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
86\membersection{wxMenu::Append}\label{wxmenuappend}
87
88\func{void}{Append}{\param{int}{ id}, \param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""},\rtfsp
89\param{const bool}{ checkable = FALSE}}
90
91Adds a string item to the end of the menu.
92
93\func{void}{Append}{\param{int}{ id}, \param{const wxString\& }{ item}, \param{wxMenu *}{subMenu},\rtfsp
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
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
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
159\func{void}{Check}{\param{int}{ id}, \param{const bool}{ check}}
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
175\func{void}{Enable}{\param{int}{ id}, \param{const bool}{ enable}}
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
212\membersection{wxMenu::FindItemForId}\label{wxmenufinditemforid}
213
214\constfunc{wxMenuItem*}{FindItemForId}{\param{int}{ id}, \param{wxMenu **}{ menuForItem = NULL}}
215
216Finds the menu item object associated with the given menu item identifier.
217
218\wxheading{Parameters}
219
220\docparam{id}{Menu item identifier.}
221\docparam{menuForItem}{will be filled with the menu for this item if not NULL.}
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
233\constfunc{wxString}{GetHelpString}{\param{int}{ id}}
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
252\constfunc{wxString}{GetLabel}{\param{int}{ id}}
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
284\constfunc{bool}{IsChecked}{\param{int}{ id}}
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
302\constfunc{bool}{IsEnabled}{\param{int}{ id}}
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
320\func{void}{SetHelpString}{\param{int}{ id}, \param{const wxString\& }{helpString}}
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
336\func{void}{SetLabel}{\param{int}{ id}, \param{const wxString\& }{label}}
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
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
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
389\wxheading{Include files}
390
391<wx/menu.h>
392
393\wxheading{Event handling}
394
395To respond to a menu selection, provide a handler for EVT\_MENU, in the frame
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.
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
418\func{void}{wxMenuBar}{\param{int}{ n}, \param{wxMenu*}{ menus[]}, \param{const wxString }{titles[]}}
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
431\pythonnote{Only the default constructor is supported in wxPython.
432Use wxMenuBar.Append instead.}
433
434
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
455\func{void}{Check}{\param{int}{ id}, \param{const bool}{ check}}
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
472\func{void}{Enable}{\param{int}{ id}, \param{const bool}{ enable}}
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
489\func{void}{EnableTop}{\param{int}{ pos}, \param{const bool}{ enable}}
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
525\membersection{wxMenuBar::FindItemForId}\label{wxmenubarfinditemforid}
526
527\constfunc{wxMenuItem *}{FindItemForId}{\param{int}{ id}}
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
541\constfunc{wxString}{GetHelpString}{\param{int}{ id}}
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
560\constfunc{wxString}{GetLabel}{\param{int}{ id}}
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
578\constfunc{wxString}{GetLabelTop}{\param{int}{ pos}}
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
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
610\membersection{wxMenuBar::IsChecked}\label{wxmenubarischecked}
611
612\constfunc{bool}{IsChecked}{\param{int}{ id}}
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
626\constfunc{bool}{IsEnabled}{\param{int}{ id}}
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::Refresh}\label{wxmenubarrefresh}
639
640\func{void}{Refresh}{\void}
641
642Redraw the menu bar
643
644\membersection{wxMenuBar::SetHelpString}\label{wxmenubarsethelpstring}
645
646\func{void}{SetHelpString}{\param{int}{ id}, \param{const wxString\& }{helpString}}
647
648Sets the help string associated with a menu item.
649
650\wxheading{Parameters}
651
652\docparam{id}{Menu item identifier.}
653
654\docparam{helpString}{Help string to associate with the menu item.}
655
656\wxheading{See also}
657
658\helpref{wxMenuBar::GetHelpString}{wxmenubargethelpstring}
659
660\membersection{wxMenuBar::SetLabel}\label{wxmenubarsetlabel}
661
662\func{void}{SetLabel}{\param{int}{ id}, \param{const wxString\& }{label}}
663
664Sets the label of a menu item.
665
666\wxheading{Parameters}
667
668\docparam{id}{Menu item identifier.}
669
670\docparam{label}{Menu item label.}
671
672\wxheading{Remarks}
673
674Use only after the menubar has been associated with a frame.
675
676\wxheading{See also}
677
678\helpref{wxMenuBar::GetLabel}{wxmenubargetlabel}
679
680\membersection{wxMenuBar::SetLabelTop}\label{wxmenubarsetlabeltop}
681
682\func{void}{SetLabelTop}{\param{int}{ pos}, \param{const wxString\& }{label}}
683
684Sets the label of a top-level menu.
685
686\wxheading{Parameters}
687
688\docparam{pos}{The position of a menu on the menu bar, starting from zero.}
689
690\docparam{label}{The menu label.}
691
692\wxheading{Remarks}
693
694Use only after the menubar has been associated with a frame.
695
696\wxheading{See also}
697
698\helpref{wxMenuBar::GetLabelTop}{wxmenubargetlabeltop}
699
700
701%%% Local Variables:
702%%% mode: latex
703%%% TeX-master: t
704%%% End: