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