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