1wxMenu(3)                  Erlang Module Definition                  wxMenu(3)
2
3
4

NAME

6       wxMenu - Functions for wxMenu class
7

DESCRIPTION

9       A menu is a popup (or pull down) list of items, one of which may be se‐
10       lected before the menu goes  away  (clicking  elsewhere  dismisses  the
11       menu). Menus may be used to construct either menu bars or popup menus.
12
13       A  menu  item has an integer ID associated with it which can be used to
14       identify the selection, or to change the menu item in some way. A  menu
15       item  with  a special identifier wxID_SEPARATOR is a separator item and
16       doesn't have an associated command but just makes a separator line  ap‐
17       pear in the menu.
18
19       Note:  Please  note  that  wxID_ABOUT  and  wxID_EXIT are predefined by
20       wxWidgets and have a special meaning since entries using these IDs will
21       be  taken out of the normal menus under macOS and will be inserted into
22       the system menu (following the appropriate macOS interface guideline).
23
24       Menu items may be either normal items, check items or radio items. Nor‐
25       mal  items don't have any special properties while the check items have
26       a boolean flag associated to them and they show a checkmark in the menu
27       when  the  flag  is set. wxWidgets automatically toggles the flag value
28       when the item is clicked and its value may be  retrieved  using  either
29       isChecked/2  method  of  wxMenu  or  wxMenuBar  itself  or by using wx‐
30       Event::IsChecked when you get the menu notification  for  the  item  in
31       question.
32
33       The  radio  items  are  similar  to the check items except that all the
34       other items in the same radio group are unchecked when a radio item  is
35       checked.  The  radio  group  is  formed  by a contiguous range of radio
36       items, i.e. it starts at the first item of this kind and ends with  the
37       first  item  of  a different kind (or the end of the menu). Notice that
38       because the radio groups are defined in terms of the item positions in‐
39       serting  or  removing  the items in the menu containing the radio items
40       risks to not work correctly.
41
42       Allocation strategy
43
44       All menus must be created on the heap because all menus attached  to  a
45       menubar  or  to another menu will be deleted by their parent when it is
46       deleted. The only exception to this rule  are  the  popup  menus  (i.e.
47       menus  used  with  wxWindow:popupMenu/4)  as wxWidgets does not destroy
48       them to allow reusing the same menu more than once. But  the  exception
49       applies  only  to the menus themselves and not to any submenus of popup
50       menus which are still destroyed by wxWidgets as usual and  so  must  be
51       heap-allocated.
52
53       As the frame menubar is deleted by the frame itself, it means that nor‐
54       mally all menus used are deleted automatically.
55
56       Event handling
57
58       Event handlers for the commands generated by the menu items can be con‐
59       nected  directly  to  the menu object itself using wxEvtHandler::Bind()
60       (not implemented in wx). If this menu is a submenu of another one,  the
61       events  from  its items can also be processed in the parent menu and so
62       on, recursively.
63
64       If the menu is part of a menu bar, then events can also be  handled  in
65       wxMenuBar object.
66
67       Finally,  menu  events  can  also  be handled in the associated window,
68       which is either the wxFrame associated with the menu bar this menu  be‐
69       longs  to  or  the window for which wxWindow:popupMenu/4 was called for
70       the popup menus.
71
72       See overview_events_bind for how to bind event handlers to the  various
73       objects.
74
75       See:  wxMenuBar,  wxWindow:popupMenu/4,  Overview events, wxFileHistory
76       (not implemented in wx)
77
78       This class is derived (and can use functions) from: wxEvtHandler
79
80       wxWidgets docs: wxMenu
81

DATA TYPES

83       wxMenu() = wx:wx_object()
84

EXPORTS

86       new() -> wxMenu()
87
88              Constructs a wxMenu object.
89
90       new(Options :: [Option]) -> wxMenu()
91
92              Types:
93
94                 Option = {style, integer()}
95
96              Constructs a wxMenu object.
97
98       new(Title, Options :: [Option]) -> wxMenu()
99
100              Types:
101
102                 Title = unicode:chardata()
103                 Option = {style, integer()}
104
105              Constructs a wxMenu object with a title.
106
107       destroy(This :: wxMenu()) -> ok
108
109              Destructor, destroying the menu.
110
111              Note: Under Motif, a popup menu must have a  valid  parent  (the
112              window  it  was  last popped up on) when being destroyed. There‐
113              fore, make sure you delete or re-use the popup menu  before  de‐
114              stroying the parent window. Re-use in this context means popping
115              up the menu on a different window from last time,  which  causes
116              an  implicit  destruction and recreation of internal data struc‐
117              tures.
118
119       append(This, MenuItem) -> wxMenuItem:wxMenuItem()
120
121              Types:
122
123                 This = wxMenu()
124                 MenuItem = wxMenuItem:wxMenuItem()
125
126              Adds a menu item object.
127
128              This is the most generic variant of append/5 method  because  it
129              may  be  used for both items (including separators) and submenus
130              and because you can also specify various extra properties  of  a
131              menu item this way, such as bitmaps and fonts.
132
133              Remark: See the remarks for the other append/5 overloads.
134
135              See:  appendSeparator/1,  appendCheckItem/4,  appendRadioItem/4,
136              AppendSubMenu() (not implemented in wx),  insert/6,  setLabel/3,
137              getHelpString/2, setHelpString/3, wxMenuItem
138
139       append(This, Id, Item) -> wxMenuItem:wxMenuItem()
140
141              Types:
142
143                 This = wxMenu()
144                 Id = integer()
145                 Item = unicode:chardata()
146
147       append(This, Id, Item, SubMenu) -> wxMenuItem:wxMenuItem()
148
149       append(This, Id, Item, SubMenu :: [Option]) ->
150                 wxMenuItem:wxMenuItem()
151
152              Types:
153
154                 This = wxMenu()
155                 Id = integer()
156                 Item = unicode:chardata()
157                 Option = {help, unicode:chardata()} | {kind, wx:wx_enum()}
158
159              Adds a menu item.
160
161              Example:
162
163              or even better for stock menu items (see wxMenuItem:new/1):
164
165              Remark:  This command can be used after the menu has been shown,
166              as well as on initial creation of a menu or menubar.
167
168              See:  appendSeparator/1,  appendCheckItem/4,  appendRadioItem/4,
169              AppendSubMenu()  (not  implemented in wx), insert/6, setLabel/3,
170              getHelpString/2, setHelpString/3, wxMenuItem
171
172       append(This, Id, Item, SubMenu, Options :: [Option]) ->
173                 wxMenuItem:wxMenuItem()
174
175              Types:
176
177                 This = wxMenu()
178                 Id = integer()
179                 Item = unicode:chardata()
180                 SubMenu = wxMenu()
181                 Option = {help, unicode:chardata()}
182
183              Adds a submenu.
184
185              Deprecated: This function  is  deprecated,  use  AppendSubMenu()
186              (not implemented in wx) instead.
187
188              See:  appendSeparator/1,  appendCheckItem/4,  appendRadioItem/4,
189              AppendSubMenu() (not implemented in wx),  insert/6,  setLabel/3,
190              getHelpString/2, setHelpString/3, wxMenuItem
191
192       appendCheckItem(This, Id, Item) -> wxMenuItem:wxMenuItem()
193
194              Types:
195
196                 This = wxMenu()
197                 Id = integer()
198                 Item = unicode:chardata()
199
200       appendCheckItem(This, Id, Item, Options :: [Option]) ->
201                          wxMenuItem:wxMenuItem()
202
203              Types:
204
205                 This = wxMenu()
206                 Id = integer()
207                 Item = unicode:chardata()
208                 Option = {help, unicode:chardata()}
209
210              Adds a checkable item to the end of the menu.
211
212              See: append/5, insertCheckItem/5
213
214       appendRadioItem(This, Id, Item) -> wxMenuItem:wxMenuItem()
215
216              Types:
217
218                 This = wxMenu()
219                 Id = integer()
220                 Item = unicode:chardata()
221
222       appendRadioItem(This, Id, Item, Options :: [Option]) ->
223                          wxMenuItem:wxMenuItem()
224
225              Types:
226
227                 This = wxMenu()
228                 Id = integer()
229                 Item = unicode:chardata()
230                 Option = {help, unicode:chardata()}
231
232              Adds a radio item to the end of the menu.
233
234              All  consequent radio items form a group and when an item in the
235              group is checked, all the others are automatically unchecked.
236
237              Note: Radio items are not supported under wxMotif.
238
239              See: append/5, insertRadioItem/5
240
241       appendSeparator(This) -> wxMenuItem:wxMenuItem()
242
243              Types:
244
245                 This = wxMenu()
246
247              Adds a separator to the end of the menu.
248
249              See: append/5, insertSeparator/2
250
251       break(This) -> ok
252
253              Types:
254
255                 This = wxMenu()
256
257              Inserts a break in a menu, causing the next appended item to ap‐
258              pear in a new column.
259
260              This  function  only  actually inserts a break in wxMSW and does
261              nothing under the other platforms.
262
263       check(This, Id, Check) -> ok
264
265              Types:
266
267                 This = wxMenu()
268                 Id = integer()
269                 Check = boolean()
270
271              Checks or unchecks the menu item.
272
273              See: isChecked/2
274
275       delete(This, Id) -> boolean()
276
277       delete(This, Item) -> boolean()
278
279              Types:
280
281                 This = wxMenu()
282                 Item = wxMenuItem:wxMenuItem()
283
284              Deletes the menu item from the menu.
285
286              If the item is a submenu, it  will  not  be  deleted.  Use  'De‐
287              stroy'/2 if you want to delete a submenu.
288
289              See: findItem/2, 'Destroy'/2, remove/2
290
291       'Destroy'(This, Id) -> boolean()
292
293       'Destroy'(This, Item) -> boolean()
294
295              Types:
296
297                 This = wxMenu()
298                 Item = wxMenuItem:wxMenuItem()
299
300              Deletes the menu item from the menu.
301
302              If  the  item  is a submenu, it will be deleted. Use remove/2 if
303              you want to keep the submenu (for example, to reuse it later).
304
305              See: findItem/2, delete/2, remove/2
306
307       enable(This, Id, Enable) -> ok
308
309              Types:
310
311                 This = wxMenu()
312                 Id = integer()
313                 Enable = boolean()
314
315              Enables or disables (greys out) a menu item.
316
317              See: isEnabled/2
318
319       findItem(This, Id) -> wxMenuItem:wxMenuItem()
320
321       findItem(This, ItemString) -> integer()
322
323              Types:
324
325                 This = wxMenu()
326                 ItemString = unicode:chardata()
327
328              Finds the menu id for a menu item string.
329
330              Return: Menu item identifier, or wxNOT_FOUND if none is found.
331
332              Remark: Any special menu codes are stripped out  of  source  and
333              target strings before matching.
334
335       findItemByPosition(This, Position) -> wxMenuItem:wxMenuItem()
336
337              Types:
338
339                 This = wxMenu()
340                 Position = integer()
341
342              Returns the wxMenuItem given a position in the menu.
343
344       getHelpString(This, Id) -> unicode:charlist()
345
346              Types:
347
348                 This = wxMenu()
349                 Id = integer()
350
351              Returns the help string associated with a menu item.
352
353              Return: The help string, or the empty string if there is no help
354              string or the item was not found.
355
356              See: setHelpString/3, append/5
357
358       getLabel(This, Id) -> unicode:charlist()
359
360              Types:
361
362                 This = wxMenu()
363                 Id = integer()
364
365              Returns a menu item label.
366
367              Return: The item label, or the empty string if the item was  not
368              found.
369
370              See: GetLabelText() (not implemented in wx), setLabel/3
371
372       getMenuItemCount(This) -> integer()
373
374              Types:
375
376                 This = wxMenu()
377
378              Returns the number of items in the menu.
379
380       getMenuItems(This) -> [wxMenuItem:wxMenuItem()]
381
382              Types:
383
384                 This = wxMenu()
385
386       getTitle(This) -> unicode:charlist()
387
388              Types:
389
390                 This = wxMenu()
391
392              Returns the title of the menu.
393
394              See: setTitle/2
395
396       insert(This, Pos, Id) -> wxMenuItem:wxMenuItem()
397
398       insert(This, Pos, MenuItem) -> wxMenuItem:wxMenuItem()
399
400              Types:
401
402                 This = wxMenu()
403                 Pos = integer()
404                 MenuItem = wxMenuItem:wxMenuItem()
405
406              Inserts the given item before the position pos.
407
408              Inserting the item at position getMenuItemCount/1 is the same as
409              appending it.
410
411              See: append/5, prepend/5
412
413       insert(This, Pos, Id, Options :: [Option]) ->
414                 wxMenuItem:wxMenuItem()
415
416              Types:
417
418                 This = wxMenu()
419                 Pos = Id = integer()
420                 Option =
421                     {text, unicode:chardata()} |
422                     {help, unicode:chardata()} |
423                     {kind, wx:wx_enum()}
424
425              Inserts the given item before the position pos.
426
427              Inserting the item at position getMenuItemCount/1 is the same as
428              appending it.
429
430              See: append/5, prepend/5
431
432       insert(This, Pos, Id, Text, Submenu) -> wxMenuItem:wxMenuItem()
433
434              Types:
435
436                 This = wxMenu()
437                 Pos = Id = integer()
438                 Text = unicode:chardata()
439                 Submenu = wxMenu()
440
441       insert(This, Pos, Id, Text, Submenu, Options :: [Option]) ->
442                 wxMenuItem:wxMenuItem()
443
444              Types:
445
446                 This = wxMenu()
447                 Pos = Id = integer()
448                 Text = unicode:chardata()
449                 Submenu = wxMenu()
450                 Option = {help, unicode:chardata()}
451
452              Inserts the given submenu before the position pos.
453
454              text  is  the text shown in the menu for it and help is the help
455              string shown in the status bar when  the  submenu  item  is  se‐
456              lected.
457
458              See: AppendSubMenu() (not implemented in wx), prepend/5
459
460       insertCheckItem(This, Pos, Id, Item) -> wxMenuItem:wxMenuItem()
461
462              Types:
463
464                 This = wxMenu()
465                 Pos = Id = integer()
466                 Item = unicode:chardata()
467
468       insertCheckItem(This, Pos, Id, Item, Options :: [Option]) ->
469                          wxMenuItem:wxMenuItem()
470
471              Types:
472
473                 This = wxMenu()
474                 Pos = Id = integer()
475                 Item = unicode:chardata()
476                 Option = {help, unicode:chardata()}
477
478              Inserts a checkable item at the given position.
479
480              See: insert/6, appendCheckItem/4
481
482       insertRadioItem(This, Pos, Id, Item) -> wxMenuItem:wxMenuItem()
483
484              Types:
485
486                 This = wxMenu()
487                 Pos = Id = integer()
488                 Item = unicode:chardata()
489
490       insertRadioItem(This, Pos, Id, Item, Options :: [Option]) ->
491                          wxMenuItem:wxMenuItem()
492
493              Types:
494
495                 This = wxMenu()
496                 Pos = Id = integer()
497                 Item = unicode:chardata()
498                 Option = {help, unicode:chardata()}
499
500              Inserts a radio item at the given position.
501
502              See: insert/6, appendRadioItem/4
503
504       insertSeparator(This, Pos) -> wxMenuItem:wxMenuItem()
505
506              Types:
507
508                 This = wxMenu()
509                 Pos = integer()
510
511              Inserts a separator at the given position.
512
513              See: insert/6, appendSeparator/1
514
515       isChecked(This, Id) -> boolean()
516
517              Types:
518
519                 This = wxMenu()
520                 Id = integer()
521
522              Determines whether a menu item is checked.
523
524              Return: true if the menu item is checked, false otherwise.
525
526              See: check/3
527
528       isEnabled(This, Id) -> boolean()
529
530              Types:
531
532                 This = wxMenu()
533                 Id = integer()
534
535              Determines whether a menu item is enabled.
536
537              Return: true if the menu item is enabled, false otherwise.
538
539              See: enable/3
540
541       prepend(This, Id) -> wxMenuItem:wxMenuItem()
542
543       prepend(This, Item) -> wxMenuItem:wxMenuItem()
544
545              Types:
546
547                 This = wxMenu()
548                 Item = wxMenuItem:wxMenuItem()
549
550              Inserts  the given item at position 0, i.e. before all the other
551              existing items.
552
553              See: append/5, insert/6
554
555       prepend(This, Id, Options :: [Option]) -> wxMenuItem:wxMenuItem()
556
557              Types:
558
559                 This = wxMenu()
560                 Id = integer()
561                 Option =
562                     {text, unicode:chardata()} |
563                     {help, unicode:chardata()} |
564                     {kind, wx:wx_enum()}
565
566              Inserts the given item at position 0, i.e. before all the  other
567              existing items.
568
569              See: append/5, insert/6
570
571       prepend(This, Id, Text, Submenu) -> wxMenuItem:wxMenuItem()
572
573              Types:
574
575                 This = wxMenu()
576                 Id = integer()
577                 Text = unicode:chardata()
578                 Submenu = wxMenu()
579
580       prepend(This, Id, Text, Submenu, Options :: [Option]) ->
581                  wxMenuItem:wxMenuItem()
582
583              Types:
584
585                 This = wxMenu()
586                 Id = integer()
587                 Text = unicode:chardata()
588                 Submenu = wxMenu()
589                 Option = {help, unicode:chardata()}
590
591              Inserts the given submenu at position 0.
592
593              See: AppendSubMenu() (not implemented in wx), insert/6
594
595       prependCheckItem(This, Id, Item) -> wxMenuItem:wxMenuItem()
596
597              Types:
598
599                 This = wxMenu()
600                 Id = integer()
601                 Item = unicode:chardata()
602
603       prependCheckItem(This, Id, Item, Options :: [Option]) ->
604                           wxMenuItem:wxMenuItem()
605
606              Types:
607
608                 This = wxMenu()
609                 Id = integer()
610                 Item = unicode:chardata()
611                 Option = {help, unicode:chardata()}
612
613              Inserts a checkable item at position 0.
614
615              See: prepend/5, appendCheckItem/4
616
617       prependRadioItem(This, Id, Item) -> wxMenuItem:wxMenuItem()
618
619              Types:
620
621                 This = wxMenu()
622                 Id = integer()
623                 Item = unicode:chardata()
624
625       prependRadioItem(This, Id, Item, Options :: [Option]) ->
626                           wxMenuItem:wxMenuItem()
627
628              Types:
629
630                 This = wxMenu()
631                 Id = integer()
632                 Item = unicode:chardata()
633                 Option = {help, unicode:chardata()}
634
635              Inserts a radio item at position 0.
636
637              See: prepend/5, appendRadioItem/4
638
639       prependSeparator(This) -> wxMenuItem:wxMenuItem()
640
641              Types:
642
643                 This = wxMenu()
644
645              Inserts a separator at position 0.
646
647              See: prepend/5, appendSeparator/1
648
649       remove(This, Id) -> wxMenuItem:wxMenuItem()
650
651       remove(This, Item) -> wxMenuItem:wxMenuItem()
652
653              Types:
654
655                 This = wxMenu()
656                 Item = wxMenuItem:wxMenuItem()
657
658              Removes the menu item from the menu but doesn't delete the asso‐
659              ciated C++ object.
660
661              This allows you to reuse the same item later by adding  it  back
662              to the menu (especially useful with submenus).
663
664              Return: A pointer to the item which was detached from the menu.
665
666       setHelpString(This, Id, HelpString) -> ok
667
668              Types:
669
670                 This = wxMenu()
671                 Id = integer()
672                 HelpString = unicode:chardata()
673
674              Sets an item's help string.
675
676              See: getHelpString/2
677
678       setLabel(This, Id, Label) -> ok
679
680              Types:
681
682                 This = wxMenu()
683                 Id = integer()
684                 Label = unicode:chardata()
685
686              Sets the label of a menu item.
687
688              See: append/5, getLabel/2
689
690       setTitle(This, Title) -> ok
691
692              Types:
693
694                 This = wxMenu()
695                 Title = unicode:chardata()
696
697              Sets the title of the menu.
698
699              Remark:  Notice  that you can only call this method directly for
700              the popup menus, to change the title of a menu that is part of a
701              menu bar you need to use wxMenuBar:setLabelTop/3.
702
703              See: getTitle/1
704
705
706
707wxWidgets team.                    wx 2.2.2                          wxMenu(3)