1Tk::ToolBar(3)        User Contributed Perl Documentation       Tk::ToolBar(3)
2
3
4

NAME

6       Tk::ToolBar - A toolbar widget for Perl/Tk
7

SYNOPSIS

9               use Tk;
10               use Tk::ToolBar;
11
12               my $mw = MainWindow->new;
13               my $tb = $mw->ToolBar(qw/-movable 1 -side top
14                                        -indicatorcolor blue/);
15
16               $tb->ToolButton  (-text  => 'Button',
17                                 -tip   => 'tool tip',
18                                 -command => sub { print "hi\n" });
19               $tb->ToolLabel   (-text  => 'A Label');
20               $tb->Label       (-text  => 'Another Label');
21               $tb->ToolLabEntry(-label => 'A LabEntry',
22                                 -labelPack => [-side => "left",
23                                                -anchor => "w"]);
24
25               my $tb2 = $mw->ToolBar;
26               $tb2->ToolButton(-image   => 'navback22',
27                                -tip     => 'back',
28                                -command => \&back);
29               $tb2->ToolButton(-image   => 'navforward22',
30                                -tip     => 'forward',
31                                -command => \&forward);
32               $tb2->separator;
33               $tb2->ToolButton(-image   => 'navhome22',
34                                -tip     => 'home',
35                                -command => \&home);
36               $tb2->ToolButton(-image   => 'actreload22',
37                                -tip     => 'reload',
38                                -command => \&reload);
39
40               MainLoop;
41

DESCRIPTION

43       This module implements a dockable toolbar. It is in the same spirit as
44       the "short-cut" toolbars found in most major applications, such as most
45       web browsers and text editors (where you find the "back" or "save" and
46       other shortcut buttons).
47
48       Buttons of any type (regular, menu, check, radio) can be created inside
49       this widget.  You can also create Label, Entry and LabEntry widgets.
50       Moreover, the ToolBar itself can be made dockable, such that it can be
51       dragged to any edge of your window. Dragging is done in "real-time" so
52       that you can see the contents of your ToolBar as you are dragging it.
53       Furthermore, if you are close to a stickable edge, a visual indicator
54       will show up along that edge to guide you.  ToolBars can be made
55       "floatable" such that if they are dragged beyond their associated
56       window, they will detach and float on the desktop.  Also, multiple
57       ToolBars are embeddable inside each other.
58
59       If you drag a ToolBar to within 15 pixels of an edge, it will stick to
60       that edge. If the ToolBar is further than 15 pixels away from an edge
61       and still inside the window, but you release it over another ToolBar
62       widget, then it will be embedded inside the second ToolBar. You can
63       "un-embed" an embedded ToolBar simply by dragging it out. You can
64       change the 15 pixel limit using the -close option.
65
66       Various icons are built into the Tk::ToolBar widget. Those icons can be
67       used as images for ToolButtons (see "SYNOPSIS"). A demo program is
68       bundled with the module that should be available under the 'User
69       Contributed Demonstrations' when you run the widget program. Run it to
70       see a list of the available images.
71
72       Tk::ToolBar attempts to use Tk::CursorControl if it's already installed
73       on the system. You can further control this using the -cursorcontrol
74       option.  See "PREREQUISITES".
75
76       The ToolBar is supposed to be created as a child of a Toplevel
77       (MainWindow is a Toplevel widget) or a Frame. You are free to
78       experiment otherwise, but expect the unexpected :-)
79

WIDGET-SPECIFIC OPTIONS

81       The ToolBar widget takes the following arguments:
82
83       -side
84           This option tells the ToolBar what edge to initially stick to. Can
85           be one of 'top', 'bottom', 'left' or 'right'. Defaults to 'top'.
86           This option can be set only during object creation. Default is
87           'top'.
88
89       -movable
90           This option specifies whether the ToolBar is dockable or not. A
91           dockable ToolBar can be dragged around with the mouse to any edge
92           of the window, subject to the sticky constraints defined by
93           -sticky. Default is 1.
94
95       -close
96           This option specifies, in pixels, how close we have to drag the
97           ToolBar an edge for the ToolBar to stick to it. Default is 15.
98
99       -sticky
100           This option specifies which sides the toolbar is allowed to stick
101           to. The value must be a string of the following characters 'nsew'.
102           A string of 'ns' means that the ToolBar can only stick to the north
103           (top) or south (bottom) sides. Defaults to 'nsew'. This option can
104           be set only during object creation.
105
106       -in This option allows the toolbar to be embedded within another
107           already instantiated Tk::ToolBar object. The value must be a
108           Tk::ToolBar object. This option can be set only during object
109           creation.
110
111       -float
112           This option specifies whether the toolbar should "float" on the
113           desktop if dragged outside of the window. It defaults to 1. Note
114           that this value is ignored if -cursorcontrol is set to 1.
115
116       -cursorcontrol
117           This option specifies whether to use Tk::CursorControl to confine
118           the cursor during dragging. The value must be either 1 or 0. The
119           default is 1 which checks for Tk::CursorControl and uses it if
120           present.
121
122       -mystyle
123           This option indicates that you want to control how the ToolBar
124           looks like and not rely on Tk::ToolBar's own judgement. The value
125           must be either 1 or 0. For now, the only thing this controls is the
126           relief of ToolButtons and the borderwidth. Defaults to 0.
127
128       -indicatorcolor
129           This option controls the color of the visual indicator that tells
130           you whether you are close enough to an edge when dragging the
131           ToolBar.  Defaults to some shade of blue and green (I like it :P).
132
133       -indicatorrelief
134           This option controls the relief of the visual indicator that tells
135           you whether you are close enough to an edge when dragging the
136           ToolBar.  Defaults to flat.
137

WIDGET METHODS

139       The following methods are used to create widgets that are placed inside
140       the ToolBar. Widgets are ordered in the same order they are created,
141       left to right.
142
143       For all widgets, except Labels, a tooltip can be specified via the -tip
144       option.  An image can be specified using the -image option for Button-
145       and Label-based widgets.
146
147       $ToolBar->ToolButton(?-type => buttonType,? options)
148       $ToolBar->Button(?-type => buttonType,? options)
149           This method creates a new Button inside the ToolBar.  The -type
150           option can be used to specify what kind of button to create. Can be
151           one of 'Button', 'Checkbutton', 'Menubutton', or 'Radiobutton'. A
152           tooltip message can be specified via the -tip option.  An
153           accelerator binding can be specified using the -accelerator option.
154           The value of this option is any legal binding sequence as defined
155           in bind. For example, "-accelerator => '<f>'" will invoke the
156           button when the 'f' key is pressed.  Any other options will be
157           passed directly to the constructor of the button. The Button object
158           is returned.
159
160       $ToolBar->ToolLabel(options)
161       $ToolBar->Label(options)
162           This method creates a new Label inside the ToolBar.  Any options
163           will be passed directly to the constructor of the label. The Label
164           object is returned.
165
166       $ToolBar->ToolEntry(options)
167       $ToolBar->Entry(options)
168           This method creates a new Entry inside the ToolBar.  A tooltip
169           message can be specified via the -tip option.  Any other options
170           will be passed directly to the constructor of the entry. The Entry
171           object is returned.
172
173       $ToolBar->ToolLabEntry(options)
174       $ToolBar->LabEntry(options)
175           This method creates a new LabEntry inside the ToolBar.  A tooltip
176           message can be specified via the -tip option.  Any other options
177           will be passed directly to the constructor of the labentry. The
178           LabEntry object is returned.  In horizontal ToolBars, the label of
179           the LabEntry widget will be packed to the left of the entry. On
180           vertical ToolBars, the label will be packed on top of the entry.
181
182       $ToolBar->ToolOptionmenu(options)
183       $ToolBar->Optionmenu(options)
184           This method creates a new Optionmenu inside the ToolBar.  A tooltip
185           message can be specified via the -tip option.  Any other options
186           will be passed directly to the constructor of the Optionmenu. The
187           Optionmenu object is returned.
188
189       $ToolBar->ToolBrowseEntry(options)
190       $ToolBar->BrowseEntry(options)
191           This method creates a new Tk::BrowseEntry inside the ToolBar.  A
192           tooltip message can be specified via the -tip option.  Any other
193           options will be passed directly to the constructor of the
194           BrowseEntry. The BrowseEntry object is returned.
195
196       $ToolBar->separator(?-movable => 0/1, -space => num?)
197           This method inserts a separator. Separators are movable by default.
198           To change that, set the -movable option to 0. If you want to add
199           some space to the left of a separator (or at the top if your
200           ToolBar is vertical), then you can specify the amount of space (in
201           pixels) via the -space option. This can be used to "right-justify"
202           some buttons.
203

IMAGES

205       Tk::ToolBar now comes with a set of useful images that can be used in
206       your Tk programs. To view those images, run the widget program that is
207       bundled with Tk, scroll down to the 'User Contributed Demonstrations',
208       and click on the Tk::ToolBar entry.
209
210       Note that the images are created using the text method. Also,
211       Tk::ToolBar, upon its creation, pre-loads all of the bundled images
212       into memory. This means that those images are available for use in
213       other widgets in your Tk program. This also means that unless those
214       images are explicitly destroyed, they will use up a small amount of
215       memory even if you are not using them explicitly.
216
217       As far as I know, all the bundled images are in the free domain. If
218       that is not the case, then please let me know.
219

BUGS

221       Not really a bug, but a feature ;-) The ToolBar widget assumes that you
222       use pack in its parent.  Actually, it will pack() itself inside its
223       parent. If you are using another geometry manager, then you MIGHT get
224       some weird behaviour.  I have tested it very quickly, and found no
225       surprises, but let me know if you do.
226
227       Another thing I noticed is that on slower window managers dragging a
228       ToolBar might not go very smoothly, and you can "drop" the ToolBar
229       midway through dragging it. I noticed this on Solaris 7 and 8, running
230       any of OpenLook, CDE or GNOME2 window managers. I would appreciate any
231       reports on different platforms.
232

TODO

234       I have implemented everything I wanted, and then some.  Here are things
235       that were requested, but are not implemented yet.  If you want more,
236       send me requests.
237
238       o Allow buttons to be "tied" to menu items. Somewhat taken care of with
239       the -accelerator method for buttons.
240       o Implement Drag-n-Drop to be able to move Tool* widgets interactively.
241       Do we really want this?
242

PREREQUISITES

244       Tk::ToolBar uses only core pTk modules. So you don't need any special
245       prerequisites. But, if Tk::CursorControl is installed on your system,
246       then Tk::ToolBar will use it to confine the cursor to your window when
247       dragging ToolBars (unless you tell it not to).
248
249       Note also that Tk::CursorControl is defined as a prerequisite in
250       Makefile.PL. So, during installation you might get a warning saying:
251
252       "Warning: prerequisite Tk::CursorControl failed to load ..."
253
254       if you don't have it installed. You can ignore this warning if you
255       don't want to install Tk::CursorControl. Tk::ToolBar will continue to
256       work properly.
257

INSTALLATION

259       Either the usual:
260
261               perl Makefile.PL
262               make
263               make install
264
265       or just stick it somewhere in @INC where perl can find it. It's in pure
266       Perl.
267

ACKNOWLEDGEMENTS

269       The following people have given me helpful comments and bug reports to
270       keep me busy: Chris Whiting, Jack Dunnigan, Robert Brooks, Peter
271       Lipecka, Martin Thurn and Shahriar Mokhtarzad.
272
273       Also thanks to the various artists of the KDE team for creating those
274       great icons, and to Adrian Davis for packaging them in a Tk-friendly
275       format.
276

AUTHOR

278       Ala Qumsieh aqumsieh@cpan.org
279

LICENSE

281       This module is distributed under the same terms as Perl itself.
282
283
284
285perl v5.32.0                      2020-07-28                    Tk::ToolBar(3)
Impressum