]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: menu.h | |
3 | // Purpose: interface of wxMenuBar | |
4 | // Author: wxWidgets team | |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows licence | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | @class wxMenuBar | |
11 | ||
12 | A menu bar is a series of menus accessible from the top of a frame. | |
13 | ||
14 | @remarks | |
15 | To respond to a menu selection, provide a handler for EVT_MENU, in the frame | |
16 | that contains the menu bar. | |
17 | ||
18 | If you have a toolbar which uses the same identifiers as your EVT_MENU entries, | |
19 | events from the toolbar will also be processed by your EVT_MENU event handlers. | |
20 | ||
21 | Tip: under Windows, if you discover that menu shortcuts (for example, Alt-F | |
22 | to show the file menu) are not working, check any EVT_CHAR events you are | |
23 | handling in child windows. | |
24 | If you are not calling event.Skip() for events that you don't process in | |
25 | these event handlers, menu shortcuts may cease to work. | |
26 | ||
27 | @library{wxcore} | |
28 | @category{menus} | |
29 | ||
30 | @see wxMenu, @ref overview_events | |
31 | */ | |
32 | class wxMenuBar : public wxWindow | |
33 | { | |
34 | public: | |
35 | /** | |
36 | Construct an empty menu bar. | |
37 | ||
38 | @param style | |
39 | If wxMB_DOCKABLE the menu bar can be detached (wxGTK only). | |
40 | */ | |
41 | wxMenuBar(long style = 0); | |
42 | ||
43 | /** | |
44 | Construct a menu bar from arrays of menus and titles. | |
45 | ||
46 | @param n | |
47 | The number of menus. | |
48 | @param menus | |
49 | An array of menus. Do not use this array again - it now belongs to | |
50 | the menu bar. | |
51 | @param titles | |
52 | An array of title strings. Deallocate this array after creating | |
53 | the menu bar. | |
54 | @param style | |
55 | If wxMB_DOCKABLE the menu bar can be detached (wxGTK only). | |
56 | ||
57 | @beginWxPerlOnly | |
58 | Not supported by wxPerl. | |
59 | @endWxPerlOnly | |
60 | */ | |
61 | wxMenuBar(size_t n, wxMenu* menus[], const wxString titles[], | |
62 | long style = 0); | |
63 | ||
64 | /** | |
65 | Destructor, destroying the menu bar and removing it from the parent | |
66 | frame (if any). | |
67 | */ | |
68 | virtual ~wxMenuBar(); | |
69 | ||
70 | /** | |
71 | Adds the item to the end of the menu bar. | |
72 | ||
73 | @param menu | |
74 | The menu to add. Do not deallocate this menu after calling Append(). | |
75 | @param title | |
76 | The title of the menu, must be non-empty. | |
77 | ||
78 | @return @true on success, @false if an error occurred. | |
79 | ||
80 | @see Insert() | |
81 | */ | |
82 | virtual bool Append(wxMenu* menu, const wxString& title); | |
83 | ||
84 | /** | |
85 | Checks or unchecks a menu item. | |
86 | ||
87 | @param id | |
88 | The menu item identifier. | |
89 | @param check | |
90 | If @true, checks the menu item, otherwise the item is unchecked. | |
91 | ||
92 | @remarks Only use this when the menu bar has been associated with a | |
93 | frame; otherwise, use the wxMenu equivalent call. | |
94 | */ | |
95 | void Check(int id, bool check); | |
96 | ||
97 | /** | |
98 | Enables or disables (greys out) a menu item. | |
99 | ||
100 | @param id | |
101 | The menu item identifier. | |
102 | @param enable | |
103 | @true to enable the item, @false to disable it. | |
104 | ||
105 | @remarks Only use this when the menu bar has been associated with a | |
106 | frame; otherwise, use the wxMenu equivalent call. | |
107 | */ | |
108 | void Enable(int id, bool enable); | |
109 | ||
110 | /** | |
111 | Enables or disables a whole menu. | |
112 | ||
113 | @param pos | |
114 | The position of the menu, starting from zero. | |
115 | @param enable | |
116 | @true to enable the menu, @false to disable it. | |
117 | ||
118 | @remarks Only use this when the menu bar has been associated with a frame. | |
119 | */ | |
120 | virtual void EnableTop(size_t pos, bool enable); | |
121 | ||
122 | /** | |
123 | Finds the menu item object associated with the given menu item identifier. | |
124 | ||
125 | @param id | |
126 | Menu item identifier. | |
127 | @param menu | |
128 | If not @NULL, menu will get set to the associated menu. | |
129 | ||
130 | @return The found menu item object, or @NULL if one was not found. | |
131 | ||
132 | @beginWxPerlOnly | |
133 | In wxPerl this method takes just the @a id parameter; | |
134 | in scalar context it returns the associated @c Wx::MenuItem, in list | |
135 | context it returns a 2-element list (item, submenu). | |
136 | @endWxPerlOnly | |
137 | */ | |
138 | virtual wxMenuItem* FindItem(int id, wxMenu* menu = NULL) const; | |
139 | ||
140 | /** | |
141 | Returns the index of the menu with the given @a title or @c wxNOT_FOUND if no | |
142 | such menu exists in this menubar. | |
143 | ||
144 | The @a title parameter may specify either the menu title | |
145 | (with accelerator characters, i.e. @c "&File") or just the | |
146 | menu label (@c "File") indifferently. | |
147 | */ | |
148 | int FindMenu(const wxString& title) const; | |
149 | ||
150 | /** | |
151 | Finds the menu item id for a menu name/menu item string pair. | |
152 | ||
153 | @param menuString | |
154 | Menu title to find. | |
155 | @param itemString | |
156 | Item to find. | |
157 | ||
158 | @return The menu item identifier, or wxNOT_FOUND if none was found. | |
159 | ||
160 | @remarks Any special menu codes are stripped out of source and target | |
161 | strings before matching. | |
162 | */ | |
163 | virtual int FindMenuItem(const wxString& menuString, | |
164 | const wxString& itemString) const; | |
165 | ||
166 | /** | |
167 | Gets the help string associated with the menu item identifier. | |
168 | ||
169 | @param id | |
170 | The menu item identifier. | |
171 | ||
172 | @return The help string, or the empty string if there was no help string | |
173 | or the menu item was not found. | |
174 | ||
175 | @see SetHelpString() | |
176 | */ | |
177 | wxString GetHelpString(int id) const; | |
178 | ||
179 | /** | |
180 | Gets the label associated with a menu item. | |
181 | ||
182 | @param id | |
183 | The menu item identifier. | |
184 | ||
185 | @return The menu item label, or the empty string if the item was not | |
186 | found. | |
187 | ||
188 | @remarks Use only after the menubar has been associated with a frame. | |
189 | */ | |
190 | wxString GetLabel(int id) const; | |
191 | ||
192 | /** | |
193 | Returns the label of a top-level menu. Note that the returned string does not | |
194 | include the accelerator characters which could have been specified in the menu | |
195 | title string during its construction. | |
196 | ||
197 | @param pos | |
198 | Position of the menu on the menu bar, starting from zero. | |
199 | ||
200 | @return The menu label, or the empty string if the menu was not found. | |
201 | ||
202 | @remarks Use only after the menubar has been associated with a frame. | |
203 | ||
204 | @deprecated | |
205 | This function is deprecated in favour of GetMenuLabel() and GetMenuLabelText(). | |
206 | ||
207 | @see SetLabelTop() | |
208 | */ | |
209 | wxString GetLabelTop(size_t pos) const; | |
210 | ||
211 | /** | |
212 | Returns the menu at @a menuIndex (zero-based). | |
213 | */ | |
214 | wxMenu* GetMenu(size_t menuIndex) const; | |
215 | ||
216 | /** | |
217 | Returns the number of menus in this menubar. | |
218 | */ | |
219 | size_t GetMenuCount() const; | |
220 | ||
221 | /** | |
222 | Returns the label of a top-level menu. Note that the returned string | |
223 | includes the accelerator characters that have been specified in the menu | |
224 | title string during its construction. | |
225 | ||
226 | @param pos | |
227 | Position of the menu on the menu bar, starting from zero. | |
228 | ||
229 | @return The menu label, or the empty string if the menu was not found. | |
230 | ||
231 | @remarks Use only after the menubar has been associated with a frame. | |
232 | ||
233 | @see GetMenuLabelText(), SetMenuLabel() | |
234 | */ | |
235 | virtual wxString GetMenuLabel(size_t pos) const; | |
236 | ||
237 | /** | |
238 | Returns the label of a top-level menu. Note that the returned string does not | |
239 | include any accelerator characters that may have been specified in the menu | |
240 | title string during its construction. | |
241 | ||
242 | @param pos | |
243 | Position of the menu on the menu bar, starting from zero. | |
244 | ||
245 | @return The menu label, or the empty string if the menu was not found. | |
246 | ||
247 | @remarks Use only after the menubar has been associated with a frame. | |
248 | ||
249 | @see GetMenuLabel(), SetMenuLabel() | |
250 | */ | |
251 | virtual wxString GetMenuLabelText(size_t pos) const; | |
252 | ||
253 | /** | |
254 | Inserts the menu at the given position into the menu bar. Inserting menu at | |
255 | position 0 will insert it in the very beginning of it, inserting at position | |
256 | GetMenuCount() is the same as calling Append(). | |
257 | ||
258 | @param pos | |
259 | The position of the new menu in the menu bar | |
260 | @param menu | |
261 | The menu to add. wxMenuBar owns the menu and will free it. | |
262 | @param title | |
263 | The title of the menu. | |
264 | ||
265 | @return @true on success, @false if an error occurred. | |
266 | ||
267 | @see Append() | |
268 | */ | |
269 | virtual bool Insert(size_t pos, wxMenu* menu, const wxString& title); | |
270 | ||
271 | /** | |
272 | Determines whether an item is checked. | |
273 | ||
274 | @param id | |
275 | The menu item identifier. | |
276 | ||
277 | @return @true if the item was found and is checked, @false otherwise. | |
278 | */ | |
279 | bool IsChecked(int id) const; | |
280 | ||
281 | /** | |
282 | Determines whether an item is enabled. | |
283 | ||
284 | @param id | |
285 | The menu item identifier. | |
286 | ||
287 | @return @true if the item was found and is enabled, @false otherwise. | |
288 | */ | |
289 | bool IsEnabled(int id) const; | |
290 | ||
291 | /** | |
292 | Redraw the menu bar | |
293 | */ | |
294 | virtual void Refresh(bool eraseBackground = true, const wxRect* rect = NULL); | |
295 | ||
296 | /** | |
297 | Removes the menu from the menu bar and returns the menu object - the caller | |
298 | is responsible for deleting it. This function may be used together with | |
299 | Insert() to change the menubar dynamically. | |
300 | ||
301 | @see Replace() | |
302 | */ | |
303 | virtual wxMenu* Remove(size_t pos); | |
304 | ||
305 | /** | |
306 | Replaces the menu at the given position with another one. | |
307 | ||
308 | @param pos | |
309 | The position of the new menu in the menu bar | |
310 | @param menu | |
311 | The menu to add. | |
312 | @param title | |
313 | The title of the menu. | |
314 | ||
315 | @return The menu which was previously at position pos. | |
316 | The caller is responsible for deleting it. | |
317 | ||
318 | @see Insert(), Remove() | |
319 | */ | |
320 | virtual wxMenu* Replace(size_t pos, wxMenu* menu, const wxString& title); | |
321 | ||
322 | /** | |
323 | Sets the help string associated with a menu item. | |
324 | ||
325 | @param id | |
326 | Menu item identifier. | |
327 | @param helpString | |
328 | Help string to associate with the menu item. | |
329 | ||
330 | @see GetHelpString() | |
331 | */ | |
332 | void SetHelpString(int id, const wxString& helpString); | |
333 | ||
334 | /** | |
335 | Sets the label of a menu item. | |
336 | ||
337 | @param id | |
338 | Menu item identifier. | |
339 | @param label | |
340 | Menu item label. | |
341 | ||
342 | @remarks Use only after the menubar has been associated with a frame. | |
343 | ||
344 | @see GetLabel() | |
345 | */ | |
346 | void SetLabel(int id, const wxString& label); | |
347 | ||
348 | /** | |
349 | Sets the label of a top-level menu. | |
350 | ||
351 | @param pos | |
352 | The position of a menu on the menu bar, starting from zero. | |
353 | @param label | |
354 | The menu label. | |
355 | ||
356 | @remarks Use only after the menubar has been associated with a frame. | |
357 | ||
358 | @deprecated | |
359 | This function has been deprecated in favour of SetMenuLabel(). | |
360 | ||
361 | @see GetLabelTop() | |
362 | */ | |
363 | void SetLabelTop(size_t pos, const wxString& label); | |
364 | ||
365 | /** | |
366 | Sets the label of a top-level menu. | |
367 | ||
368 | @param pos | |
369 | The position of a menu on the menu bar, starting from zero. | |
370 | @param label | |
371 | The menu label. | |
372 | ||
373 | @remarks Use only after the menubar has been associated with a frame. | |
374 | */ | |
375 | virtual void SetMenuLabel(size_t pos, const wxString& label); | |
376 | }; | |
377 | ||
378 | ||
379 | ||
380 | /** | |
381 | @class wxMenu | |
382 | ||
383 | A menu is a popup (or pull down) list of items, one of which may be | |
384 | selected before the menu goes away (clicking elsewhere dismisses the | |
385 | menu). Menus may be used to construct either menu bars or popup menus. | |
386 | ||
387 | A menu item has an integer ID associated with it which can be used to | |
388 | identify the selection, or to change the menu item in some way. A menu item | |
389 | with a special identifier -1 is a separator item and doesn't have an | |
390 | associated command but just makes a separator line appear in the menu. | |
391 | ||
392 | @note | |
393 | Please note that @e wxID_ABOUT and @e wxID_EXIT are predefined by wxWidgets | |
394 | and have a special meaning since entries using these IDs will be taken out | |
395 | of the normal menus under MacOS X and will be inserted into the system menu | |
396 | (following the appropriate MacOS X interface guideline). | |
397 | On PalmOS @e wxID_EXIT is disabled according to Palm OS Companion guidelines. | |
398 | ||
399 | Menu items may be either @e normal items, @e check items or @e radio items. | |
400 | Normal items don't have any special properties while the check items have a | |
401 | boolean flag associated to them and they show a checkmark in the menu when | |
402 | the flag is set. | |
403 | wxWidgets automatically toggles the flag value when the item is clicked and its | |
404 | value may be retrieved using either wxMenu::IsChecked method of wxMenu or | |
405 | wxMenuBar itself or by using wxEvent::IsChecked when you get the menu | |
406 | notification for the item in question. | |
407 | ||
408 | The radio items are similar to the check items except that all the other items | |
409 | in the same radio group are unchecked when a radio item is checked. The radio | |
410 | group is formed by a contiguous range of radio items, i.e. it starts at the | |
411 | first item of this kind and ends with the first item of a different kind (or | |
412 | the end of the menu). Notice that because the radio groups are defined in terms | |
413 | of the item positions inserting or removing the items in the menu containing | |
414 | the radio items risks to not work correctly. | |
415 | ||
416 | ||
417 | @section menu_allocation Allocation strategy | |
418 | ||
419 | All menus must be created on the @b heap because all menus attached to a | |
420 | menubar or to another menu will be deleted by their parent when it is | |
421 | deleted. The only exception to this rule are the popup menus (i.e. menus | |
422 | used with wxWindow::PopupMenu()) as wxWidgets does not destroy them to | |
423 | allow reusing the same menu more than once. But the exception applies only | |
424 | to the menus themselves and not to any submenus of popup menus which are | |
425 | still destroyed by wxWidgets as usual and so must be heap-allocated. | |
426 | ||
427 | As the frame menubar is deleted by the frame itself, it means that normally | |
428 | all menus used are deleted automatically. | |
429 | ||
430 | ||
431 | @section menu_eventhandling Event handling | |
432 | ||
433 | If the menu is part of a menubar, then wxMenuBar event processing is used. | |
434 | ||
435 | With a popup menu (see wxWindow::PopupMenu), there is a variety of ways to | |
436 | handle a menu selection event (@c wxEVT_COMMAND_MENU_SELECTED): | |
437 | - Provide @c EVT_MENU handlers in the window which pops up the menu, or in an | |
438 | ancestor of that window (the simplest method); | |
439 | - Derive a new class from wxMenu and define event table entries using the @c EVT_MENU macro; | |
440 | - Set a new event handler for wxMenu, through wxEvtHandler::SetNextHandler, | |
441 | specifying an object whose class has @c EVT_MENU entries; | |
442 | ||
443 | Note that instead of static @c EVT_MENU macros you can also use dynamic | |
444 | connection; see @ref overview_events_bind. | |
445 | ||
446 | @library{wxcore} | |
447 | @category{menus} | |
448 | ||
449 | @see wxMenuBar, wxWindow::PopupMenu, @ref overview_events, | |
450 | @ref wxFileHistory "wxFileHistory (most recently used files menu)" | |
451 | */ | |
452 | class wxMenu : public wxEvtHandler | |
453 | { | |
454 | public: | |
455 | /** | |
456 | Constructs a wxMenu object. | |
457 | ||
458 | @param style | |
459 | If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only). | |
460 | */ | |
461 | wxMenu(long style); | |
462 | ||
463 | /** | |
464 | Constructs a wxMenu object with a title. | |
465 | ||
466 | @param title | |
467 | Title at the top of the menu (not always supported). | |
468 | @param style | |
469 | If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only). | |
470 | */ | |
471 | wxMenu(const wxString& title, long style = 0); | |
472 | ||
473 | /** | |
474 | Destructor, destroying the menu. | |
475 | ||
476 | @note | |
477 | Under Motif, a popup menu must have a valid parent (the window | |
478 | it was last popped up on) when being destroyed. Therefore, make sure | |
479 | you delete or re-use the popup menu @e before destroying the parent | |
480 | window. Re-use in this context means popping up the menu on a different | |
481 | window from last time, which causes an implicit destruction and | |
482 | recreation of internal data structures. | |
483 | */ | |
484 | virtual ~wxMenu(); | |
485 | ||
486 | /** | |
487 | Adds a menu item. | |
488 | ||
489 | @param id | |
490 | The menu command identifier. | |
491 | @param item | |
492 | The string to appear on the menu item. | |
493 | See wxMenuItem::SetItemLabel() for more details. | |
494 | @param helpString | |
495 | An optional help string associated with the item. | |
496 | By default, the handler for the @c wxEVT_MENU_HIGHLIGHT event displays | |
497 | this string in the status line. | |
498 | @param kind | |
499 | May be @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, @c wxITEM_CHECK or @c wxITEM_RADIO. | |
500 | ||
501 | Example: | |
502 | @code | |
503 | m_pFileMenu->Append(ID_NEW_FILE, "&New file\tCTRL+N", "Creates a new XYZ document"); | |
504 | @endcode | |
505 | or even better for stock menu items (see wxMenuItem::wxMenuItem): | |
506 | @code | |
507 | m_pFileMenu->Append(wxID_NEW, "", "Creates a new XYZ document"); | |
508 | @endcode | |
509 | ||
510 | @remarks | |
511 | This command can be used after the menu has been shown, as well as on | |
512 | initial creation of a menu or menubar. | |
513 | ||
514 | @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(), | |
515 | AppendSubMenu(), Insert(), SetLabel(), GetHelpString(), | |
516 | SetHelpString(), wxMenuItem | |
517 | */ | |
518 | wxMenuItem* Append(int id, const wxString& item = wxEmptyString, | |
519 | const wxString& helpString = wxEmptyString, | |
520 | wxItemKind kind = wxITEM_NORMAL); | |
521 | ||
522 | /** | |
523 | Adds a submenu. | |
524 | ||
525 | @deprecated This function is deprecated, use AppendSubMenu() instead. | |
526 | ||
527 | @param id | |
528 | The menu command identifier. | |
529 | @param item | |
530 | The string to appear on the menu item. | |
531 | @param subMenu | |
532 | Pull-right submenu. | |
533 | @param helpString | |
534 | An optional help string associated with the item. | |
535 | By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays | |
536 | this string in the status line. | |
537 | ||
538 | @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(), | |
539 | AppendSubMenu(), Insert(), SetLabel(), GetHelpString(), | |
540 | SetHelpString(), wxMenuItem | |
541 | */ | |
542 | wxMenuItem* Append(int id, const wxString& item, wxMenu* subMenu, | |
543 | const wxString& helpString = wxEmptyString); | |
544 | ||
545 | /** | |
546 | Adds a menu item object. | |
547 | ||
548 | This is the most generic variant of Append() method because it may be | |
549 | used for both items (including separators) and submenus and because | |
550 | you can also specify various extra properties of a menu item this way, | |
551 | such as bitmaps and fonts. | |
552 | ||
553 | @param menuItem | |
554 | A menuitem object. It will be owned by the wxMenu object after this | |
555 | function is called, so do not delete it yourself. | |
556 | ||
557 | @remarks | |
558 | See the remarks for the other Append() overloads. | |
559 | ||
560 | @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(), | |
561 | AppendSubMenu(), Insert(), SetLabel(), GetHelpString(), | |
562 | SetHelpString(), wxMenuItem | |
563 | */ | |
564 | wxMenuItem* Append(wxMenuItem* menuItem); | |
565 | ||
566 | /** | |
567 | Adds a checkable item to the end of the menu. | |
568 | ||
569 | @see Append(), InsertCheckItem() | |
570 | */ | |
571 | wxMenuItem* AppendCheckItem(int id, const wxString& item, | |
572 | const wxString& help = wxEmptyString); | |
573 | ||
574 | /** | |
575 | Adds a radio item to the end of the menu. | |
576 | All consequent radio items form a group and when an item in the group is | |
577 | checked, all the others are automatically unchecked. | |
578 | ||
579 | @note Radio items are not supported under wxMotif. | |
580 | ||
581 | @see Append(), InsertRadioItem() | |
582 | */ | |
583 | wxMenuItem* AppendRadioItem(int id, const wxString& item, | |
584 | const wxString& help = wxEmptyString); | |
585 | ||
586 | /** | |
587 | Adds a separator to the end of the menu. | |
588 | ||
589 | @see Append(), InsertSeparator() | |
590 | */ | |
591 | wxMenuItem* AppendSeparator(); | |
592 | ||
593 | /** | |
594 | Adds the given @a submenu to this menu. @a text is the text shown in the | |
595 | menu for it and @a help is the help string shown in the status bar when the | |
596 | submenu item is selected. | |
597 | */ | |
598 | wxMenuItem* AppendSubMenu(wxMenu* submenu, const wxString& text, | |
599 | const wxString& help = wxEmptyString); | |
600 | ||
601 | /** | |
602 | Inserts a break in a menu, causing the next appended item to appear in | |
603 | a new column. | |
604 | */ | |
605 | virtual void Break(); | |
606 | ||
607 | /** | |
608 | Checks or unchecks the menu item. | |
609 | ||
610 | @param id | |
611 | The menu item identifier. | |
612 | @param check | |
613 | If @true, the item will be checked, otherwise it will be unchecked. | |
614 | ||
615 | @see IsChecked() | |
616 | */ | |
617 | void Check(int id, bool check); | |
618 | ||
619 | /** | |
620 | Deletes the menu item from the menu. If the item is a submenu, it will | |
621 | @b not be deleted. Use Destroy() if you want to delete a submenu. | |
622 | ||
623 | @param id | |
624 | Id of the menu item to be deleted. | |
625 | ||
626 | @see FindItem(), Destroy(), Remove() | |
627 | */ | |
628 | bool Delete(int id); | |
629 | ||
630 | /** | |
631 | Deletes the menu item from the menu. If the item is a submenu, it will | |
632 | @b not be deleted. Use Destroy() if you want to delete a submenu. | |
633 | ||
634 | @param item | |
635 | Menu item to be deleted. | |
636 | ||
637 | @see FindItem(), Destroy(), Remove() | |
638 | */ | |
639 | bool Delete(wxMenuItem* item); | |
640 | ||
641 | /** | |
642 | Deletes the menu item from the menu. If the item is a submenu, it will | |
643 | be deleted. Use Remove() if you want to keep the submenu (for example, | |
644 | to reuse it later). | |
645 | ||
646 | @param id | |
647 | Id of the menu item to be deleted. | |
648 | ||
649 | @see FindItem(), Deletes(), Remove() | |
650 | */ | |
651 | bool Destroy(int id); | |
652 | ||
653 | /** | |
654 | Deletes the menu item from the menu. If the item is a submenu, it will | |
655 | be deleted. Use Remove() if you want to keep the submenu (for example, | |
656 | to reuse it later). | |
657 | ||
658 | @param item | |
659 | Menu item to be deleted. | |
660 | ||
661 | @see FindItem(), Deletes(), Remove() | |
662 | */ | |
663 | bool Destroy(wxMenuItem* item); | |
664 | ||
665 | /** | |
666 | Enables or disables (greys out) a menu item. | |
667 | ||
668 | @param id | |
669 | The menu item identifier. | |
670 | @param enable | |
671 | @true to enable the menu item, @false to disable it. | |
672 | ||
673 | @see IsEnabled() | |
674 | */ | |
675 | void Enable(int id, bool enable); | |
676 | ||
677 | /** | |
678 | Finds the menu item object associated with the given menu item identifier | |
679 | and, optionally, the position of the item in the menu. | |
680 | ||
681 | Unlike FindItem(), this function doesn't recurse but only looks at the | |
682 | direct children of this menu. | |
683 | ||
684 | @param id | |
685 | The identifier of the menu item to find. | |
686 | @param pos | |
687 | If the pointer is not @NULL, it is filled with the item's position if | |
688 | it was found or @c (size_t)wxNOT_FOUND otherwise. | |
689 | @return | |
690 | Menu item object or @NULL if not found. | |
691 | */ | |
692 | wxMenuItem *FindChildItem(int id, size_t *pos = NULL) const; | |
693 | ||
694 | /** | |
695 | Finds the menu id for a menu item string. | |
696 | ||
697 | @param itemString | |
698 | Menu item string to find. | |
699 | ||
700 | @return Menu item identifier, or wxNOT_FOUND if none is found. | |
701 | ||
702 | @remarks Any special menu codes are stripped out of source and target | |
703 | strings before matching. | |
704 | */ | |
705 | virtual int FindItem(const wxString& itemString) const; | |
706 | ||
707 | /** | |
708 | Finds the menu item object associated with the given menu item identifier and, | |
709 | optionally, the (sub)menu it belongs to. | |
710 | ||
711 | @param id | |
712 | Menu item identifier. | |
713 | @param menu | |
714 | If the pointer is not @NULL, it will be filled with the item's | |
715 | parent menu (if the item was found) | |
716 | ||
717 | @return Menu item object or NULL if none is found. | |
718 | */ | |
719 | wxMenuItem* FindItem(int id, wxMenu** menu = NULL) const; | |
720 | ||
721 | /** | |
722 | Returns the wxMenuItem given a position in the menu. | |
723 | */ | |
724 | wxMenuItem* FindItemByPosition(size_t position) const; | |
725 | ||
726 | /** | |
727 | Returns the help string associated with a menu item. | |
728 | ||
729 | @param id | |
730 | The menu item identifier. | |
731 | ||
732 | @return The help string, or the empty string if there is no help string | |
733 | or the item was not found. | |
734 | ||
735 | @see SetHelpString(), Append() | |
736 | */ | |
737 | virtual wxString GetHelpString(int id) const; | |
738 | ||
739 | /** | |
740 | Returns a menu item label. | |
741 | ||
742 | @param id | |
743 | The menu item identifier. | |
744 | ||
745 | @return The item label, or the empty string if the item was not found. | |
746 | ||
747 | @see GetLabelText(), SetLabel() | |
748 | */ | |
749 | wxString GetLabel(int id) const; | |
750 | ||
751 | /** | |
752 | Returns a menu item label, without any of the original mnemonics and | |
753 | accelerators. | |
754 | ||
755 | @param id | |
756 | The menu item identifier. | |
757 | ||
758 | @return The item label, or the empty string if the item was not found. | |
759 | ||
760 | @see GetLabel(), SetLabel() | |
761 | */ | |
762 | wxString GetLabelText(int id) const; | |
763 | ||
764 | /** | |
765 | Returns the number of items in the menu. | |
766 | */ | |
767 | size_t GetMenuItemCount() const; | |
768 | ||
769 | //@{ | |
770 | /** | |
771 | Returns the list of items in the menu. | |
772 | ||
773 | wxMenuItemList is a pseudo-template list class containing wxMenuItem | |
774 | pointers, see wxList. | |
775 | */ | |
776 | wxMenuItemList& GetMenuItems() const; | |
777 | const wxMenuItemList& GetMenuItems() const; | |
778 | //@} | |
779 | ||
780 | /** | |
781 | Returns the title of the menu. | |
782 | ||
783 | @remarks This is relevant only to popup menus, use | |
784 | wxMenuBar::GetMenuLabel for the menus in the menubar. | |
785 | ||
786 | @see SetTitle() | |
787 | */ | |
788 | const wxString& GetTitle() const; | |
789 | ||
790 | /** | |
791 | Inserts the given @a item before the position @a pos. | |
792 | ||
793 | Inserting the item at position GetMenuItemCount() is the same | |
794 | as appending it. | |
795 | ||
796 | @see Append(), Prepend() | |
797 | */ | |
798 | wxMenuItem* Insert(size_t pos, wxMenuItem* item); | |
799 | ||
800 | /** | |
801 | Inserts the given @a item before the position @a pos. | |
802 | ||
803 | Inserting the item at position GetMenuItemCount() is the same | |
804 | as appending it. | |
805 | ||
806 | @see Append(), Prepend() | |
807 | */ | |
808 | wxMenuItem* Insert(size_t pos, int id, | |
809 | const wxString& item = wxEmptyString, | |
810 | const wxString& helpString = wxEmptyString, | |
811 | wxItemKind kind = wxITEM_NORMAL); | |
812 | ||
813 | /** | |
814 | Inserts a checkable item at the given position. | |
815 | ||
816 | @see Insert(), AppendCheckItem() | |
817 | */ | |
818 | wxMenuItem* InsertCheckItem(size_t pos, int id, const wxString& item, | |
819 | const wxString& helpString = wxEmptyString); | |
820 | ||
821 | /** | |
822 | Inserts a radio item at the given position. | |
823 | ||
824 | @see Insert(), AppendRadioItem() | |
825 | */ | |
826 | wxMenuItem* InsertRadioItem(size_t pos, int id, const wxString& item, | |
827 | const wxString& helpString = wxEmptyString); | |
828 | ||
829 | /** | |
830 | Inserts a separator at the given position. | |
831 | ||
832 | @see Insert(), AppendSeparator() | |
833 | */ | |
834 | wxMenuItem* InsertSeparator(size_t pos); | |
835 | ||
836 | /** | |
837 | Determines whether a menu item is checked. | |
838 | ||
839 | @param id | |
840 | The menu item identifier. | |
841 | ||
842 | @return @true if the menu item is checked, @false otherwise. | |
843 | ||
844 | @see Check() | |
845 | */ | |
846 | bool IsChecked(int id) const; | |
847 | ||
848 | /** | |
849 | Determines whether a menu item is enabled. | |
850 | ||
851 | @param id | |
852 | The menu item identifier. | |
853 | ||
854 | @return @true if the menu item is enabled, @false otherwise. | |
855 | ||
856 | @see Enable() | |
857 | */ | |
858 | bool IsEnabled(int id) const; | |
859 | ||
860 | /** | |
861 | Inserts the given @a item at position 0, i.e. before all the other | |
862 | existing items. | |
863 | ||
864 | @see Append(), Insert() | |
865 | */ | |
866 | wxMenuItem* Prepend(wxMenuItem* item); | |
867 | ||
868 | /** | |
869 | Inserts the given @a item at position 0, i.e. before all the other | |
870 | existing items. | |
871 | ||
872 | @see Append(), Insert() | |
873 | */ | |
874 | wxMenuItem* Prepend(int id, const wxString& item = wxEmptyString, | |
875 | const wxString& helpString = wxEmptyString, | |
876 | wxItemKind kind = wxITEM_NORMAL); | |
877 | ||
878 | /** | |
879 | Inserts a checkable item at position 0. | |
880 | ||
881 | @see Prepend(), AppendCheckItem() | |
882 | */ | |
883 | wxMenuItem* PrependCheckItem(int id, const wxString& item, | |
884 | const wxString& helpString = wxEmptyString); | |
885 | ||
886 | /** | |
887 | Inserts a radio item at position 0. | |
888 | ||
889 | @see Prepend(), AppendRadioItem() | |
890 | */ | |
891 | wxMenuItem* PrependRadioItem(int id, const wxString& item, | |
892 | const wxString& helpString = wxEmptyString); | |
893 | ||
894 | /** | |
895 | Inserts a separator at position 0. | |
896 | ||
897 | @see Prepend(), AppendSeparator() | |
898 | */ | |
899 | wxMenuItem* PrependSeparator(); | |
900 | ||
901 | /** | |
902 | Removes the menu item from the menu but doesn't delete the associated C++ | |
903 | object. This allows you to reuse the same item later by adding it back to | |
904 | the menu (especially useful with submenus). | |
905 | ||
906 | @param id | |
907 | The identifier of the menu item to remove. | |
908 | ||
909 | @return A pointer to the item which was detached from the menu. | |
910 | */ | |
911 | wxMenuItem* Remove(int id); | |
912 | ||
913 | /** | |
914 | Removes the menu item from the menu but doesn't delete the associated C++ | |
915 | object. This allows you to reuse the same item later by adding it back to | |
916 | the menu (especially useful with submenus). | |
917 | ||
918 | @param item | |
919 | The menu item to remove. | |
920 | ||
921 | @return A pointer to the item which was detached from the menu. | |
922 | */ | |
923 | wxMenuItem* Remove(wxMenuItem* item); | |
924 | ||
925 | /** | |
926 | Sets an item's help string. | |
927 | ||
928 | @param id | |
929 | The menu item identifier. | |
930 | @param helpString | |
931 | The help string to set. | |
932 | ||
933 | @see GetHelpString() | |
934 | */ | |
935 | virtual void SetHelpString(int id, const wxString& helpString); | |
936 | ||
937 | /** | |
938 | Sets the label of a menu item. | |
939 | ||
940 | @param id | |
941 | The menu item identifier. | |
942 | @param label | |
943 | The menu item label to set. | |
944 | ||
945 | @see Append(), GetLabel() | |
946 | */ | |
947 | void SetLabel(int id, const wxString& label); | |
948 | ||
949 | /** | |
950 | Sets the title of the menu. | |
951 | ||
952 | @param title | |
953 | The title to set. | |
954 | ||
955 | @remarks This is relevant only to popup menus, use | |
956 | wxMenuBar::SetLabelTop for the menus in the menubar. | |
957 | ||
958 | @see GetTitle() | |
959 | */ | |
960 | virtual void SetTitle(const wxString& title); | |
961 | ||
962 | /** | |
963 | Sends events to @a source (or owning window if @NULL) to update the | |
964 | menu UI. | |
965 | ||
966 | This is called just before the menu is popped up with wxWindow::PopupMenu, | |
967 | but the application may call it at other times if required. | |
968 | */ | |
969 | void UpdateUI(wxEvtHandler* source = NULL); | |
970 | }; | |
971 |