]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/menu.tex
wxMkDir() has 'perm' argument
[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
44\func{}{wxMenu}{\param{const wxString\& }{title = ""}, \param{const wxFunction}{ func = NULL}}
45
46Constructs 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
06d20283
RD
54\pythonnote{The wxPython version of the \tt{wxMenu} constructor
55doesn't accept the callback argument because of reference counting
56issues. There is a specialized wxMenu constructor called
57\tt{wxPyMenu} which does and can be used for PopupMenus when callbacks
58are needed. You must retain a reference to the menu while useing it
59otherwise your callback function will get dereferenced when the menu
60does.
61}
62
a660d684
KB
63\membersection{wxMenu::\destruct{wxMenu}}
64
65\func{}{\destruct{wxMenu}}{\void}
66
67Destructor, destroying the menu.
68
b412f9be
JS
69Note: under Motif, a popup menu must have a valid parent (the window
70it was last popped up on) when being destroyed. Therefore, make sure
71you delete or re-use the popup menu {\it before} destroying the
72parent window. Re-use in this context means popping up the menu on
73a different window from last time, which causes an implicit destruction
74and recreation of internal data structures.
75
a660d684
KB
76\membersection{wxMenu::Append}\label{wxmenuappend}
77
eaaa6a06 78\func{void}{Append}{\param{int}{ id}, \param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""},\rtfsp
a660d684
KB
79\param{const bool}{ checkable = FALSE}}
80
81Adds a string item to the end of the menu.
82
eaaa6a06 83\func{void}{Append}{\param{int}{ id}, \param{const wxString\& }{ item}, \param{wxMenu *}{subMenu},\rtfsp
a660d684
KB
84\param{const wxString\& }{helpString = ""}}
85
86Adds a pull-right submenu to the end of the menu.
87
88\func{void}{Append}{\param{wxMenuItem*}{ menuItem}}
89
90Adds a menu item object. You can specify various extra properties of a menu item this way,
91such 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.
104By default, \helpref{wxFrame::OnMenuHighlight}{wxframeonmenuhighlight} displays
105this string in the status line.}
106
107\docparam{menuItem}{A menuitem object. It will be owned by the wxMenu object after this function
108is called, so do not delete it yourself.}
109
110\wxheading{Remarks}
111
112This command can be used after the menu has been shown, as well as on initial
113creation 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
06d20283
RD
120
121\pythonnote{In place of a single overloaded method name, wxPython
122implements 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
a660d684
KB
131\membersection{wxMenu::AppendSeparator}\label{wxmenuappendseparator}
132
133\func{void}{AppendSeparator}{\void}
134
135Adds 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
145Inserts a break in a menu, causing the next appended item to appear in a new column.
146
147\membersection{wxMenu::Check}\label{wxmenucheck}
148
eaaa6a06 149\func{void}{Check}{\param{int}{ id}, \param{const bool}{ check}}
a660d684
KB
150
151Checks 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
eaaa6a06 165\func{void}{Enable}{\param{int}{ id}, \param{const bool}{ enable}}
a660d684
KB
166
167Enables 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
183Finds 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
191Menu item identifier, or -1 if none is found.
192
193\wxheading{Remarks}
194
195Any special menu codes are stripped out of source and target strings
196before matching.
197
198\wxheading{See also}
199
200\helpref{wxMenu::FindItemForId}{wxmenufinditemforid}
201
202\membersection{wxMenu::FindItemForId}\label{wxmenufinditemforid}
203
c626a8b7 204\constfunc{wxMenuItem*}{FindItemForId}{\param{int}{ id}, \param{wxMenu **}{ menuForItem = NULL}}
a660d684
KB
205
206Finds the menu item object associated with the given menu item identifier.
207
208\wxheading{Parameters}
209
210\docparam{id}{Menu item identifier.}
c626a8b7 211\docparam{menuForItem}{will be filled with the menu for this item if not NULL.}
a660d684
KB
212
213\wxheading{Return value}
214
215Returns 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
eaaa6a06 223\constfunc{wxString}{GetHelpString}{\param{int}{ id}}
a660d684
KB
224
225Returns 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
233The help string, or the empty string if there is no help string or the
234item 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
eaaa6a06 242\constfunc{wxString}{GetLabel}{\param{int}{ id}}
a660d684
KB
243
244Returns a menu item label.
245
246\wxheading{Parameters}
247
248\docparam{id}{The menu item identifier.}
249
250\wxheading{Return value}
251
252The 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
262Returns the title of the menu.
263
264\wxheading{Remarks}
265
266This 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
eaaa6a06 274\constfunc{bool}{IsChecked}{\param{int}{ id}}
a660d684
KB
275
276Determines whether a menu item is checked.
277
278\wxheading{Parameters}
279
280\docparam{id}{The menu item identifier.}
281
282\wxheading{Return value}
283
284TRUE 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
eaaa6a06 292\constfunc{bool}{IsEnabled}{\param{int}{ id}}
a660d684
KB
293
294Determines whether a menu item is enabled.
295
296\wxheading{Parameters}
297
298\docparam{id}{The menu item identifier.}
299
300\wxheading{Return value}
301
302TRUE 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
eaaa6a06 310\func{void}{SetHelpString}{\param{int}{ id}, \param{const wxString\& }{helpString}}
a660d684
KB
311
312Sets 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
eaaa6a06 326\func{void}{SetLabel}{\param{int}{ id}, \param{const wxString\& }{label}}
a660d684
KB
327
328Sets 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
344Sets the title of the menu.
345
346\wxheading{Parameters}
347
348\docparam{title}{The title to set.}
349
350\wxheading{Remarks}
351
352This is relevant only to popup menus.
353
354\wxheading{See also}
355
356\helpref{wxMenu::SetTitle}{wxmenusettitle}
357
631f1bfe
JS
358\membersection{wxMenu::UpdateUI}\label{wxmenuupdateui}
359
360\constfunc{void}{UpdateUI}{\param{wxEvtHandler*}{ source = NULL}}
361
362Sends events to {\it source} (or owning window if NULL) to update the
363menu UI. This is called just before the menu is popped up with \helpref{wxWindow::PopupMenu}{wxwindowpopupmenu}, but
364the application may call it at other times if required.
365
366\wxheading{See also}
367
368\helpref{wxUpdateUIEvent}{wxupdateuievent}
369
a660d684
KB
370\section{\class{wxMenuBar}}\label{wxmenubar}
371
372A 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
954b8ae6
JS
379\wxheading{Include files}
380
381<wx/menu.h>
382
a660d684
KB
383\wxheading{Event handling}
384
385To respond to a menu selection, provide a handler for EVT\_MENU, in the frame
386that contains the menu bar.
387
388\wxheading{See also}
389
390\helpref{wxMenu}{wxmenu}, \helpref{Event handling overview}{eventhandlingoverview}
391
392\latexignore{\rtfignore{\wxheading{Members}}}
393
394\membersection{wxMenuBar::wxMenuBar}\label{wxmenubarconstr}
395
396\func{void}{wxMenuBar}{\void}
397
398Default constructor.
399
eaaa6a06 400\func{void}{wxMenuBar}{\param{int}{ n}, \param{wxMenu*}{ menus[]}, \param{const wxString }{titles[]}}
a660d684
KB
401
402Construct a menu bar from arrays of menus and titles.
403
404\wxheading{Parameters}
405
406\docparam{n}{The number of menus.}
407
408\docparam{menus}{An array of menus. Do not use this array again - it now belongs to the
409menu bar.}
410
411\docparam{titles}{An array of title strings. Deallocate this array after creating the menu bar.}
412
06d20283
RD
413\pythonnote{Only the default constructor is supported in wxPython.
414Use wxMenuBar.Append instead.}
415
416
a660d684
KB
417\membersection{wxMenuBar::\destruct{wxMenuBar}}
418
419\func{void}{\destruct{wxMenuBar}}{\void}
420
421Destructor, destroying the menu bar and removing it from the parent frame (if any).
422
423\membersection{wxMenuBar::Append}\label{wxmenubarappend}
424
425\func{void}{Append}{\param{wxMenu *}{menu}, \param{const wxString\& }{title}}
426
427Adds the item to the end of the menu bar.
428
429\wxheading{Parameters}
430
431\docparam{menu}{The menu to add. Do not deallocate this menu after calling {\bf Append}.}
432
433\docparam{title}{The title of the menu.}
434
435\membersection{wxMenuBar::Check}\label{wxmenubarcheck}
436
eaaa6a06 437\func{void}{Check}{\param{int}{ id}, \param{const bool}{ check}}
a660d684
KB
438
439Checks or unchecks a menu item.
440
441\wxheading{Parameters}
442
443\docparam{id}{The menu item identifier.}
444
445\docparam{check}{If TRUE, checks the menu item, otherwise the item is unchecked.}
446
447\wxheading{Remarks}
448
449Only use this when the menu bar has been associated
450with a frame; otherwise, use the wxMenu equivalent call.
451
452\membersection{wxMenuBar::Enable}\label{wxmenubarenable}
453
eaaa6a06 454\func{void}{Enable}{\param{int}{ id}, \param{const bool}{ enable}}
a660d684
KB
455
456Enables or disables (greys out) a menu item.
457
458\wxheading{Parameters}
459
460\docparam{id}{The menu item identifier.}
461
462\docparam{enable}{TRUE to enable the item, FALSE to disable it.}
463
464\wxheading{Remarks}
465
466Only use this when the menu bar has been
467associated with a frame; otherwise, use the wxMenu equivalent call.
468
469\membersection{wxMenuBar::EnableTop}\label{wxmenubarenabletop}
470
eaaa6a06 471\func{void}{EnableTop}{\param{int}{ pos}, \param{const bool}{ enable}}
a660d684
KB
472
473Enables or disables a whole menu.
474
475\wxheading{Parameters}
476
477\docparam{pos}{The position of the menu, starting from zero.}
478
479\docparam{enable}{TRUE to enable the menu, FALSE to disable it.}
480
481\wxheading{Remarks}
482
483Only use this when the menu bar has been
484associated with a frame.
485
486\membersection{wxMenuBar::FindMenuItem}\label{wxmenubarfindmenuitem}
487
488\constfunc{int}{FindMenuItem}{\param{const wxString\& }{menuString}, \param{const wxString\& }{itemString}}
489
490Finds the menu item id for a menu name/menu item string pair.
491
492\wxheading{Parameters}
493
494\docparam{menuString}{Menu title to find.}
495
496\docparam{itemString}{Item to find.}
497
498\wxheading{Return value}
499
500The menu item identifier, or -1 if none was found.
501
502\wxheading{Remarks}
503
504Any special menu codes are stripped out of source and target strings
505before matching.
506
507\membersection{wxMenuBar::FindItemById}\label{wxmenubarfinditembyid}
508
eaaa6a06 509\constfunc{wxMenuItem *}{FindItemById}{\param{int}{ id}}
a660d684
KB
510
511Finds the menu item object associated with the given menu item identifier,
512
513\wxheading{Parameters}
514
515\docparam{id}{Menu item identifier.}
516
517\wxheading{Return value}
518
519The found menu item object, or NULL if one was not found.
520
521\membersection{wxMenuBar::GetHelpString}\label{wxmenubargethelpstring}
522
eaaa6a06 523\constfunc{wxString}{GetHelpString}{\param{int}{ id}}
a660d684
KB
524
525Gets the help string associated with the menu item identifer.
526
527\wxheading{Parameters}
528
529\docparam{id}{The menu item identifier.}
530
531\wxheading{Return value}
532
533The help string, or the empty string if there was no help string or the menu item
534was not found.
535
536\wxheading{See also}
537
538\helpref{wxMenuBar::SetHelpString}{wxmenubarsethelpstring}
539
540\membersection{wxMenuBar::GetLabel}\label{wxmenubargetlabel}
541
eaaa6a06 542\constfunc{wxString}{GetLabel}{\param{int}{ id}}
a660d684
KB
543
544Gets the label associated with a menu item.
545
546\wxheading{Parameters}
547
548\docparam{id}{The menu item identifier.}
549
550\wxheading{Return value}
551
552The menu item label, or the empty string if the item was not found.
553
554\wxheading{Remarks}
555
556Use only after the menubar has been associated with a frame.
557
558\membersection{wxMenuBar::GetLabelTop}\label{wxmenubargetlabeltop}
559
eaaa6a06 560\constfunc{wxString}{GetLabelTop}{\param{int}{ pos}}
a660d684
KB
561
562Returns the label of a top-level menu.
563
564\wxheading{Parameters}
565
566\docparam{pos}{Position of the menu on the menu bar, starting from zero.}
567
568\wxheading{Return value}
569
570The menu label, or the empty string if the menu was not found.
571
572\wxheading{Remarks}
573
574Use only after the menubar has been associated with a frame.
575
576\wxheading{See also}
577
578\helpref{wxMenuBar::SetLabelTop}{wxmenubarsetlabeltop}
579
7f555861
JS
580\membersection{wxMenuBar::GetMenu}\label{wxmenubargetmenu}
581
582\constfunc{wxMenu*}{GetMenu}{\param{int}{ menuIndex}}
583
584Returns the menu at {\it menuIndex} (zero-based).
585
586\membersection{wxMenuBar::GetMenuCount}\label{wxmenubargetmenucount}
587
588\constfunc{int}{GetMenuCount}{\void}
589
590Returns the number of menus in this menubar.
591
a660d684
KB
592\membersection{wxMenuBar::IsChecked}\label{wxmenubarischecked}
593
eaaa6a06 594\constfunc{bool}{IsChecked}{\param{int}{ id}}
a660d684
KB
595
596Determines whether an item is checked.
597
598\wxheading{Parameters}
599
600\docparam{id}{The menu item identifier.}
601
602\wxheading{Return value}
603
604TRUE if the item was found and is checked, FALSE otherwise.
605
606\membersection{wxMenuBar::IsEnabled}\label{wxmenubarisenabled}
607
eaaa6a06 608\constfunc{bool}{IsEnabled}{\param{int}{ id}}
a660d684
KB
609
610Determines whether an item is enabled.
611
612\wxheading{Parameters}
613
614\docparam{id}{The menu item identifier.}
615
616\wxheading{Return value}
617
618TRUE if the item was found and is enabled, FALSE otherwise.
619
620\membersection{wxMenuBar::SetHelpString}\label{wxmenubarsethelpstring}
621
eaaa6a06 622\func{void}{SetHelpString}{\param{int}{ id}, \param{const wxString\& }{helpString}}
a660d684
KB
623
624Sets the help string associated with a menu item.
625
626\wxheading{Parameters}
627
628\docparam{id}{Menu item identifier.}
629
630\docparam{helpString}{Help string to associate with the menu item.}
631
632\wxheading{See also}
633
634\helpref{wxMenuBar::GetHelpString}{wxmenubargethelpstring}
635
636\membersection{wxMenuBar::SetLabel}\label{wxmenubarsetlabel}
637
eaaa6a06 638\func{void}{SetLabel}{\param{int}{ id}, \param{const wxString\& }{label}}
a660d684
KB
639
640Sets the label of a menu item.
641
642\wxheading{Parameters}
643
644\docparam{id}{Menu item identifier.}
645
646\docparam{label}{Menu item label.}
647
648\wxheading{Remarks}
649
650Use only after the menubar has been associated with a frame.
651
652\wxheading{See also}
653
654\helpref{wxMenuBar::GetLabel}{wxmenubargetlabel}
655
656\membersection{wxMenuBar::SetLabelTop}\label{wxmenubarsetlabeltop}
657
eaaa6a06 658\func{void}{SetLabelTop}{\param{int}{ pos}, \param{const wxString\& }{label}}
a660d684
KB
659
660Sets the label of a top-level menu.
661
662\wxheading{Parameters}
663
664\docparam{pos}{The position of a menu on the menu bar, starting from zero.}
665
666\docparam{label}{The menu label.}
667
668\wxheading{Remarks}
669
670Use only after the menubar has been associated with a frame.
671
672\wxheading{See also}
673
674\helpref{wxMenuBar::GetLabelTop}{wxmenubargetlabeltop}
675