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