1Tk::ToolBar(3) User Contributed Perl Documentation Tk::ToolBar(3)
2
6 Tk::ToolBar - A toolbar widget for Perl/Tk
7
9 use Tk;
10 use Tk::ToolBar;
11 my $mw = MainWindow->new;
13 my $tb = $mw->ToolBar(qw/-movable 1 -side top
14 -indicatorcolor blue/);
15 $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 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 MainLoop;
41
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 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 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 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 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 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
81 The ToolBar widget takes the following arguments:
82 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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
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 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 $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 $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 $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 $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 $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 $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 $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
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 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 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
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 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
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 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
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 Note also that Tk::CursorControl is defined as a prerequisite in
250 Makefile.PL. So, during installation you might get a warning saying:
251 "Warning: prerequisite Tk::CursorControl failed to load ..."
253 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
259 Either the usual:
260 perl Makefile.PL
262 make
263 make install
264 or just stick it somewhere in @INC where perl can find it. It's in pure
266 Perl.
267
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 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
278 Ala Qumsieh aqumsieh@cpan.org
279
281 This module is distributed under the same terms as Perl itself.
282perl v5.32.0 2020-07-28 Tk::ToolBar(3)