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

NAME

6       wxToolBar - Functions for wxToolBar class
7

DESCRIPTION

9       A  toolbar is a bar of buttons and/or other controls usually placed be‐
10       low the menu bar in a wxFrame.
11
12       You  may  create  a  toolbar  that  is  managed  by  a  frame   calling
13       wxFrame:createToolBar/2.  Under  Pocket  PC, you should always use this
14       function for creating the toolbar to be managed by the frame,  so  that
15       wxWidgets can use a combined menubar and toolbar. Where you manage your
16       own toolbars, create wxToolBar as usual.
17
18       There are several different types of tools you can add  to  a  toolbar.
19       These types are controlled by the ?wxItemKind enumeration.
20
21       Note  that many methods in wxToolBar such as addTool/6 return a wxTool‐
22       BarToolBase* object. This should be regarded as an opaque handle repre‐
23       senting  the  newly  added toolbar item, providing access to its id and
24       position within the toolbar. Changes to the item's state should be made
25       through  calls to wxToolBar methods, for example enableTool/3. Calls to
26       wxToolBarToolBase (not implemented in wx) methods (undocumented by pur‐
27       pose)  will  not  change  the visible state of the item within the tool
28       bar.
29
30       After you have added all the tools you need, you must call realize/1 to
31       effectively construct and display the toolbar.
32
33       wxMSW  note: Note that under wxMSW toolbar paints tools to reflect sys‐
34       tem-wide colours. If you use more than 16 colours in your tool bitmaps,
35       you  may  wish  to suppress this behaviour, otherwise system colours in
36       your bitmaps will inadvertently be mapped  to  system  colours.  To  do
37       this,  set  the msw.remap system option before creating the toolbar: If
38       you wish to use 32-bit images  (which  include  an  alpha  channel  for
39       transparency)  use: Then colour remapping is switched off, and a trans‐
40       parent background used. But only use this option under Windows XP  with
41       true colour:
42
43       Styles
44
45       This class supports the following styles:
46
47       See: Overview toolbar
48
49       This  class is derived (and can use functions) from: wxControl wxWindow
50       wxEvtHandler
51
52       wxWidgets docs: wxToolBar
53

EVENTS

55       Event  types  emitted  from  this  class:  command_tool_rclicked,  com‐
56       mand_tool_enter, tool_dropdown
57

DATA TYPES

59       wxToolBar() = wx:wx_object()
60

EXPORTS

62       addControl(This, Control) -> wx:wx_object()
63
64              Types:
65
66                 This = wxToolBar()
67                 Control = wxControl:wxControl()
68
69       addControl(This, Control, Options :: [Option]) -> wx:wx_object()
70
71              Types:
72
73                 This = wxToolBar()
74                 Control = wxControl:wxControl()
75                 Option = {label, unicode:chardata()}
76
77              Adds any control to the toolbar, typically e.g. a wxComboBox.
78
79              Remark:  wxMac:  labels are only displayed if wxWidgets is built
80              with wxMAC_USE_NATIVE_TOOLBAR set to 1
81
82       addSeparator(This) -> wx:wx_object()
83
84              Types:
85
86                 This = wxToolBar()
87
88              Adds a separator for spacing groups of tools.
89
90              Notice that the separator uses the look appropriate for the cur‐
91              rent  platform  so it can be a vertical line (MSW, some versions
92              of GTK) or just an empty space or something else.
93
94              See: addTool/6, setToolSeparation/2, addStretchableSpace/1
95
96       addTool(This, Tool) -> wx:wx_object()
97
98              Types:
99
100                 This = wxToolBar()
101                 Tool = wx:wx_object()
102
103              Adds a tool to the toolbar.
104
105              Remark: After you have added tools to a toolbar, you  must  call
106              realize/1 in order to have the tools appear.
107
108              See:  addSeparator/1,  addCheckTool/5,  addRadioTool/5,  insert‐
109              Tool/6, deleteTool/2, realize/1, SetDropdownMenu()  (not  imple‐
110              mented in wx)
111
112       addTool(This, ToolId, Label, Bitmap) -> wx:wx_object()
113
114              Types:
115
116                 This = wxToolBar()
117                 ToolId = integer()
118                 Label = unicode:chardata()
119                 Bitmap = wxBitmap:wxBitmap()
120
121       addTool(This, ToolId, Label, Bitmap, BmpDisabled) ->
122                  wx:wx_object()
123
124       addTool(This, ToolId, Label, Bitmap, BmpDisabled :: [Option]) ->
125                  wx:wx_object()
126
127              Types:
128
129                 This = wxToolBar()
130                 ToolId = integer()
131                 Label = unicode:chardata()
132                 Bitmap = wxBitmap:wxBitmap()
133                 Option    =    {shortHelp,   unicode:chardata()}   |   {kind,
134                 wx:wx_enum()}
135
136              Adds a tool to the toolbar.
137
138              This most commonly used version has fewer  parameters  than  the
139              full  version  below which specifies the more rarely used button
140              features.
141
142              Remark: After you have added tools to a toolbar, you  must  call
143              realize/1 in order to have the tools appear.
144
145              See:  addSeparator/1,  addCheckTool/5,  addRadioTool/5,  insert‐
146              Tool/6, deleteTool/2, realize/1, SetDropdownMenu()  (not  imple‐
147              mented in wx)
148
149       addTool(This, ToolId, Label, Bitmap, BmpDisabled,
150               Options :: [Option]) ->
151                  wx:wx_object()
152
153              Types:
154
155                 This = wxToolBar()
156                 ToolId = integer()
157                 Label = unicode:chardata()
158                 Bitmap = BmpDisabled = wxBitmap:wxBitmap()
159                 Option =
160                     {kind, wx:wx_enum()} |
161                     {shortHelp, unicode:chardata()} |
162                     {longHelp, unicode:chardata()} |
163                     {data, wx:wx_object()}
164
165              Adds a tool to the toolbar.
166
167              Remark:  After  you have added tools to a toolbar, you must call
168              realize/1 in order to have the tools appear.
169
170              See:  addSeparator/1,  addCheckTool/5,  addRadioTool/5,  insert‐
171              Tool/6,  deleteTool/2,  realize/1, SetDropdownMenu() (not imple‐
172              mented in wx)
173
174       addCheckTool(This, ToolId, Label, Bitmap1) -> wx:wx_object()
175
176              Types:
177
178                 This = wxToolBar()
179                 ToolId = integer()
180                 Label = unicode:chardata()
181                 Bitmap1 = wxBitmap:wxBitmap()
182
183       addCheckTool(This, ToolId, Label, Bitmap1, Options :: [Option]) ->
184                       wx:wx_object()
185
186              Types:
187
188                 This = wxToolBar()
189                 ToolId = integer()
190                 Label = unicode:chardata()
191                 Bitmap1 = wxBitmap:wxBitmap()
192                 Option =
193                     {bmpDisabled, wxBitmap:wxBitmap()} |
194                     {shortHelp, unicode:chardata()} |
195                     {longHelp, unicode:chardata()} |
196                     {data, wx:wx_object()}
197
198              Adds a new check (or toggle) tool to the toolbar.
199
200              The parameters are the same as in addTool/6.
201
202              See: addTool/6
203
204       addRadioTool(This, ToolId, Label, Bitmap1) -> wx:wx_object()
205
206              Types:
207
208                 This = wxToolBar()
209                 ToolId = integer()
210                 Label = unicode:chardata()
211                 Bitmap1 = wxBitmap:wxBitmap()
212
213       addRadioTool(This, ToolId, Label, Bitmap1, Options :: [Option]) ->
214                       wx:wx_object()
215
216              Types:
217
218                 This = wxToolBar()
219                 ToolId = integer()
220                 Label = unicode:chardata()
221                 Bitmap1 = wxBitmap:wxBitmap()
222                 Option =
223                     {bmpDisabled, wxBitmap:wxBitmap()} |
224                     {shortHelp, unicode:chardata()} |
225                     {longHelp, unicode:chardata()} |
226                     {data, wx:wx_object()}
227
228              Adds a new radio tool to the toolbar.
229
230              Consecutive radio tools form a radio group such that exactly one
231              button  in  the  group  is pressed at any moment, in other words
232              whenever a button in the group is pressed the previously pressed
233              button  is  automatically  released. You should avoid having the
234              radio groups of only one element as it would be  impossible  for
235              the user to use such button.
236
237              By  default,  the  first  button in the radio group is initially
238              pressed, the others are not.
239
240              See: addTool/6
241
242       addStretchableSpace(This) -> wx:wx_object()
243
244              Types:
245
246                 This = wxToolBar()
247
248              Adds a stretchable space to the toolbar.
249
250              Any space not taken up by the fixed items (all items except  for
251              stretchable  spaces) is distributed in equal measure between the
252              stretchable spaces in the toolbar. The most common use for  this
253              method  is  to  add  a single stretchable space before the items
254              which should be right-aligned in the toolbar,  but  more  exotic
255              possibilities  are  possible,  e.g.  a  stretchable space may be
256              added in the beginning and the end of the toolbar to centre  all
257              toolbar items.
258
259              See: addTool/6, addSeparator/1, insertStretchableSpace/2
260
261              Since: 2.9.1
262
263       insertStretchableSpace(This, Pos) -> wx:wx_object()
264
265              Types:
266
267                 This = wxToolBar()
268                 Pos = integer()
269
270              Inserts a stretchable space at the given position.
271
272              See addStretchableSpace/1 for details about stretchable spaces.
273
274              See: insertTool/6, insertSeparator/2
275
276              Since: 2.9.1
277
278       deleteTool(This, ToolId) -> boolean()
279
280              Types:
281
282                 This = wxToolBar()
283                 ToolId = integer()
284
285              Removes the specified tool from the toolbar and deletes it.
286
287              If you don't want to delete the tool, but just to remove it from
288              the toolbar (to possibly add it back later), you may use remove‐
289              Tool/2 instead.
290
291              Note: It is unnecessary to call realize/1 for the change to take
292              place, it will happen immediately.
293
294              Return: true if the tool was deleted, false otherwise.
295
296              See: deleteToolByPos/2
297
298       deleteToolByPos(This, Pos) -> boolean()
299
300              Types:
301
302                 This = wxToolBar()
303                 Pos = integer()
304
305              This function behaves like deleteTool/2 but it deletes the  tool
306              at the specified position and not the one with the given id.
307
308       enableTool(This, ToolId, Enable) -> ok
309
310              Types:
311
312                 This = wxToolBar()
313                 ToolId = integer()
314                 Enable = boolean()
315
316              Enables or disables the tool.
317
318              Remark:  Some  implementations  will change the visible state of
319              the tool to indicate that it is disabled.
320
321              See: getToolEnabled/2, toggleTool/3
322
323       findById(This, Id) -> wx:wx_object()
324
325              Types:
326
327                 This = wxToolBar()
328                 Id = integer()
329
330              Returns a pointer to the tool identified by id  or  NULL  if  no
331              corresponding tool is found.
332
333       findControl(This, Id) -> wxControl:wxControl()
334
335              Types:
336
337                 This = wxToolBar()
338                 Id = integer()
339
340              Returns  a pointer to the control identified by id or NULL if no
341              corresponding control is found.
342
343       findToolForPosition(This, X, Y) -> wx:wx_object()
344
345              Types:
346
347                 This = wxToolBar()
348                 X = Y = integer()
349
350              Finds a tool for the given mouse position.
351
352              Return: A pointer to a tool if a tool is found, or  NULL  other‐
353              wise.
354
355              Remark:  Currently not implemented in wxGTK (always returns NULL
356              there).
357
358       getToolSize(This) -> {W :: integer(), H :: integer()}
359
360              Types:
361
362                 This = wxToolBar()
363
364              Returns the size of a whole button, which is usually larger than
365              a tool bitmap because of added 3D effects.
366
367              See: setToolBitmapSize/2, getToolBitmapSize/1
368
369       getToolBitmapSize(This) -> {W :: integer(), H :: integer()}
370
371              Types:
372
373                 This = wxToolBar()
374
375              Returns the size of bitmap that the toolbar expects to have.
376
377              The  default  bitmap size is platform-dependent: for example, it
378              is 16*15 for MSW and 24*24 for GTK. This size does not necessar‐
379              ily  indicate the best size to use for the toolbars on the given
380              platform, for this you should use  wxArtProvider::GetNativeSize‐
381              Hint(wxART_TOOLBAR)  but  in any case, as the bitmap size is de‐
382              duced automatically from the size of the bitmaps associated with
383              the  tools  added  to  the toolbar, it is usually unnecessary to
384              call setToolBitmapSize/2 explicitly.
385
386              Remark: Note that this is the size of the bitmap you pass to ad‐
387              dTool/6, and not the eventual size of the tool button.
388
389              See: setToolBitmapSize/2, getToolSize/1
390
391       getMargins(This) -> {W :: integer(), H :: integer()}
392
393              Types:
394
395                 This = wxToolBar()
396
397              Returns  the  left/right  and top/bottom margins, which are also
398              used for inter-toolspacing.
399
400              See: setMargins/3
401
402       getToolEnabled(This, ToolId) -> boolean()
403
404              Types:
405
406                 This = wxToolBar()
407                 ToolId = integer()
408
409              Called to determine whether a tool is enabled (responds to  user
410              input).
411
412              Return: true if the tool is enabled, false otherwise.
413
414              See: enableTool/3
415
416       getToolLongHelp(This, ToolId) -> unicode:charlist()
417
418              Types:
419
420                 This = wxToolBar()
421                 ToolId = integer()
422
423              Returns the long help for the given tool.
424
425              See: setToolLongHelp/3, setToolShortHelp/3
426
427       getToolPacking(This) -> integer()
428
429              Types:
430
431                 This = wxToolBar()
432
433              Returns the value used for packing tools.
434
435              See: setToolPacking/2
436
437       getToolPos(This, ToolId) -> integer()
438
439              Types:
440
441                 This = wxToolBar()
442                 ToolId = integer()
443
444              Returns  the tool position in the toolbar, or wxNOT_FOUND if the
445              tool is not found.
446
447       getToolSeparation(This) -> integer()
448
449              Types:
450
451                 This = wxToolBar()
452
453              Returns the default separator size.
454
455              See: setToolSeparation/2
456
457       getToolShortHelp(This, ToolId) -> unicode:charlist()
458
459              Types:
460
461                 This = wxToolBar()
462                 ToolId = integer()
463
464              Returns the short help for the given tool.
465
466              See: getToolLongHelp/2, setToolShortHelp/3
467
468       getToolState(This, ToolId) -> boolean()
469
470              Types:
471
472                 This = wxToolBar()
473                 ToolId = integer()
474
475              Gets the on/off state of a toggle tool.
476
477              Return: true if the tool is toggled on, false otherwise.
478
479              See: toggleTool/3
480
481       insertControl(This, Pos, Control) -> wx:wx_object()
482
483              Types:
484
485                 This = wxToolBar()
486                 Pos = integer()
487                 Control = wxControl:wxControl()
488
489       insertControl(This, Pos, Control, Options :: [Option]) ->
490                        wx:wx_object()
491
492              Types:
493
494                 This = wxToolBar()
495                 Pos = integer()
496                 Control = wxControl:wxControl()
497                 Option = {label, unicode:chardata()}
498
499              Inserts the control into the toolbar at the given position.
500
501              You must call realize/1 for the change to take place.
502
503              See: addControl/3, insertTool/6
504
505       insertSeparator(This, Pos) -> wx:wx_object()
506
507              Types:
508
509                 This = wxToolBar()
510                 Pos = integer()
511
512              Inserts the separator into the toolbar at the given position.
513
514              You must call realize/1 for the change to take place.
515
516              See: addSeparator/1, insertTool/6
517
518       insertTool(This, Pos, Tool) -> wx:wx_object()
519
520              Types:
521
522                 This = wxToolBar()
523                 Pos = integer()
524                 Tool = wx:wx_object()
525
526       insertTool(This, Pos, ToolId, Label, Bitmap) -> wx:wx_object()
527
528              Types:
529
530                 This = wxToolBar()
531                 Pos = ToolId = integer()
532                 Label = unicode:chardata()
533                 Bitmap = wxBitmap:wxBitmap()
534
535       insertTool(This, Pos, ToolId, Label, Bitmap, Options :: [Option]) ->
536                     wx:wx_object()
537
538              Types:
539
540                 This = wxToolBar()
541                 Pos = ToolId = integer()
542                 Label = unicode:chardata()
543                 Bitmap = wxBitmap:wxBitmap()
544                 Option =
545                     {bmpDisabled, wxBitmap:wxBitmap()} |
546                     {kind, wx:wx_enum()} |
547                     {shortHelp, unicode:chardata()} |
548                     {longHelp, unicode:chardata()} |
549                     {clientData, wx:wx_object()}
550
551              Inserts the tool with the specified attributes into the  toolbar
552              at the given position.
553
554              You must call realize/1 for the change to take place.
555
556              See: addTool/6, insertControl/4, insertSeparator/2
557
558              Return:  The newly inserted tool or NULL on failure. Notice that
559              with the overload taking tool parameter the caller is  responsi‐
560              ble for deleting the tool in the latter case.
561
562       realize(This) -> boolean()
563
564              Types:
565
566                 This = wxToolBar()
567
568              This function should be called after you have added tools.
569
570       removeTool(This, Id) -> wx:wx_object()
571
572              Types:
573
574                 This = wxToolBar()
575                 Id = integer()
576
577              Removes the given tool from the toolbar but doesn't delete it.
578
579              This allows inserting/adding this tool back to this (or another)
580              toolbar later.
581
582              Note: It is unnecessary to call realize/1 for the change to take
583              place, it will happen immediately.
584
585              See: deleteTool/2
586
587       setMargins(This, X, Y) -> ok
588
589              Types:
590
591                 This = wxToolBar()
592                 X = Y = integer()
593
594              Set the values to be used as margins for the toolbar.
595
596              Remark:  This must be called before the tools are added if abso‐
597              lute positioning is to be used, and the default (zero-size) mar‐
598              gins are to be overridden.
599
600              See: getMargins/1
601
602       setToolBitmapSize(This, Size) -> ok
603
604              Types:
605
606                 This = wxToolBar()
607                 Size = {W :: integer(), H :: integer()}
608
609              Sets the default size of each tool bitmap.
610
611              The default bitmap size is 16 by 15 pixels.
612
613              Remark:  This should be called to tell the toolbar what the tool
614              bitmap size is. Call it before you add tools.
615
616              See: getToolBitmapSize/1, getToolSize/1
617
618       setToolLongHelp(This, ToolId, HelpString) -> ok
619
620              Types:
621
622                 This = wxToolBar()
623                 ToolId = integer()
624                 HelpString = unicode:chardata()
625
626              Sets the long help for the given tool.
627
628              Remark: You might use the long help for displaying the tool pur‐
629              pose on the status line.
630
631              See: getToolLongHelp/2, setToolShortHelp/3
632
633       setToolPacking(This, Packing) -> ok
634
635              Types:
636
637                 This = wxToolBar()
638                 Packing = integer()
639
640              Sets the value used for spacing tools.
641
642              The default value is 1.
643
644              Remark:  The  packing is used for spacing in the vertical direc‐
645              tion if the toolbar is horizontal, and for spacing in the  hori‐
646              zontal direction if the toolbar is vertical.
647
648              See: getToolPacking/1
649
650       setToolShortHelp(This, ToolId, HelpString) -> ok
651
652              Types:
653
654                 This = wxToolBar()
655                 ToolId = integer()
656                 HelpString = unicode:chardata()
657
658              Sets the short help for the given tool.
659
660              Remark:  An application might use short help for identifying the
661              tool purpose in a tooltip.
662
663              See: getToolShortHelp/2, setToolLongHelp/3
664
665       setToolSeparation(This, Separation) -> ok
666
667              Types:
668
669                 This = wxToolBar()
670                 Separation = integer()
671
672              Sets the default separator size.
673
674              The default value is 5.
675
676              See: addSeparator/1
677
678       toggleTool(This, ToolId, Toggle) -> ok
679
680              Types:
681
682                 This = wxToolBar()
683                 ToolId = integer()
684                 Toggle = boolean()
685
686              Toggles a tool on or off.
687
688              This does not cause any event to get emitted.
689
690              Remark: Only applies to a tool that has been specified as a tog‐
691              gle tool.
692
693
694
695wxWidgets team.                     wx 2.1                        wxToolBar(3)