1Scrollbar(3) User Contributed Perl Documentation Scrollbar(3)
2
6 Tk::Scrollbar - Create and manipulate Scrollbar widgets
7
9 $scrollbar = $parent->Scrollbar(?options?);
10
12 -activebackground -highlightbackground -orient -takefocus
13 -background -highlightcolor -relief -troughcolor -border‐
14 width -highlightthickness -repeatdelay -cursor -jump -repeatin‐
15 terval
16 See Tk::options for details of the standard options.
18
20 Name: activeRelief
21 Class: ActiveRelief
22 Switch: -activerelief
23 Specifies the relief to use when displaying the element that is
24 active, if any. Elements other than the active element are always
25 displayed with a raised relief.
26 Name: command
28 Class: Command
29 Switch: -command
30 Specifies a callback to invoke to change the view in the widget
31 associated with the scrollbar. When a user requests a view change
32 by manipulating the scrollbar, the callback is invoked. The call‐
33 back is passed additional arguments as described later. This option
34 almost always has a value such as [xview => $widget] or [yview =>
35 $widget], consisting of the a widget object and either xview (if
36 the scrollbar is for horizontal scrolling) or yview (for vertical
37 scrolling). All scrollable widgets have xview and yview methods
38 that take exactly the additional arguments appended by the scroll‐
39 bar as described in "SCROLLING COMMANDS" below.
40 Name: elementBorderWidth
42 Class: BorderWidth
43 Switch: -elementborderwidth
44 Specifies the width of borders drawn around the internal elements
45 of the scrollbar (the two arrows and the slider). The value may
46 have any of the forms acceptable to Tk_GetPixels. If this value is
47 less than zero, the value of the borderWidth option is used in its
48 place.
49 Name: width
51 Class: Width
52 Switch: -width
53 Specifies the desired narrow dimension of the scrollbar window, not
54 including 3-D border, if any. For vertical scrollbars this will be
55 the width and for horizontal scrollbars this will be the height.
56 The value may have any of the forms acceptable to Tk_GetPixels.
57
59 The Scrollbar method creates a new window (given by the $widget argu‐
60 ment) and makes it into a scrollbar widget. Additional options,
61 described above, may be specified on the command line or in the option
62 database to configure aspects of the scrollbar such as its colors, ori‐
63 entation, and relief. The scrollbar command returns its $widget argu‐
64 ment. At the time this command is invoked, there must not exist a win‐
65 dow named $widget, but $widget's parent must exist.
66 A scrollbar is a widget that displays two arrows, one at each end of
68 the scrollbar, and a slider in the middle portion of the scrollbar. It
69 provides information about what is visible in an associated window that
70 displays an document of some sort (such as a file being edited or a
71 drawing). The position and size of the slider indicate which portion
72 of the document is visible in the associated window. For example, if
73 the slider in a vertical scrollbar covers the top third of the area
74 between the two arrows, it means that the associated window displays
75 the top third of its document.
76 Scrollbars can be used to adjust the view in the associated window by
78 clicking or dragging with the mouse. See "BINDINGS" below for details.
79
81 A scrollbar displays five elements, which are referred to in the meth‐
82 ods for the scrollbar:
83 arrow1
85 The top or left arrow in the scrollbar.
86 trough1
88 The region between the slider and arrow1.
89 slider
91 The rectangle that indicates what is visible in the associated wid‐
92 get.
93 trough2
95 The region between the slider and arrow2.
96 arrow2
98 The bottom or right arrow in the scrollbar.
99
101 The Scrollbar method creates a widget object. This object supports the
102 configure and cget methods described in Tk::options which can be used
103 to enquire and modify the options described above. The widget also
104 inherits all the methods provided by the generic Tk::Widget class.
105 The following additional methods are available for scrollbar widgets:
107 $scrollbar->activate(?element?)
109 Marks the element indicated by element as active, which causes it
110 to be displayed as specified by the activeBackground and activeRe‐
111 lief options. The only element values understood by this command
112 are arrow1, slider, or arrow2. If any other value is specified
113 then no element of the scrollbar will be active. If element is not
114 specified, the command returns the name of the element that is cur‐
115 rently active, or an empty string if no element is active.
116 $scrollbar->delta(deltaX, deltaY)
118 Returns a real number indicating the fractional change in the
119 scrollbar setting that corresponds to a given change in slider
120 position. For example, if the scrollbar is horizontal, the result
121 indicates how much the scrollbar setting must change to move the
122 slider deltaX pixels to the right (deltaY is ignored in this case).
123 If the scrollbar is vertical, the result indicates how much the
124 scrollbar setting must change to move the slider deltaY pixels
125 down. The arguments and the result may be zero or negative.
126 $scrollbar->fraction(x, y)
128 Returns a real number between 0 and 1 indicating where the point
129 given by x and y lies in the trough area of the scrollbar. The
130 value 0 corresponds to the top or left of the trough, the value 1
131 corresponds to the bottom or right, 0.5 corresponds to the middle,
132 and so on. X and y must be pixel coordinates relative to the
133 scrollbar widget. If x and y refer to a point outside the trough,
134 the closest point in the trough is used.
135 $scrollbar->get
137 Returns the scrollbar settings in the form of a list whose elements
138 are the arguments to the most recent set method.
139 $scrollbar->identify(x, y)
141 Returns the name of the element under the point given by x and y
142 (such as arrow1), or an empty string if the point does not lie in
143 any element of the scrollbar. X and y must be pixel coordinates
144 relative to the scrollbar widget.
145 $scrollbar->set(first, last)
147 This command is invoked by the scrollbar's associated widget to
148 tell the scrollbar about the current view in the widget. The com‐
149 mand takes two arguments, each of which is a real fraction between
150 0 and 1. The fractions describe the range of the document that is
151 visible in the associated widget. For example, if first is 0.2 and
152 last is 0.4, it means that the first part of the document visible
153 in the window is 20% of the way through the document, and the last
154 visible part is 40% of the way through.
155
157 When the user interacts with the scrollbar, for example by dragging the
158 slider, the scrollbar notifies the associated widget that it must
159 change its view. The scrollbar makes the notification by evaluating a
160 callback specified as the scrollbar's -command option. The callback
161 may take several forms. In each case, the intial arguments passed are
162 those specified in the -command callback itself, which usually has a
163 form like [yview => $widget]. (Which will invoke $widget->yview(...)
164 where the ... part is as below. See Tk::callbacks for details.) The
165 callback is passed additional arguments as follows:
166 moveto,fraction
168 Fraction is a real number between 0 and 1. The widget should
169 adjust its view so that the point given by fraction appears at the
170 beginning of the widget. If fraction is 0 it refers to the begin‐
171 ning of the document. 1.0 refers to the end of the document, 0.333
172 refers to a point one-third of the way through the document, and so
173 on.
174 scroll,number,units
176 The widget should adjust its view by number units. The units are
177 defined in whatever way makes sense for the widget, such as charac‐
178 ters or lines in a text widget. Number is either 1, which means
179 one unit should scroll off the top or left of the window, or -1,
180 which means that one unit should scroll off the bottom or right of
181 the window.
182 scroll,number,page
184 The widget should adjust its view by number pages. It is up to the
185 widget to define the meaning of a page; typically it is slightly
186 less than what fits in the window, so that there is a slight over‐
187 lap between the old and new views. Number is either 1, which means
188 the next page should become visible, or -1, which means that the
189 previous page should become visible.
190
192 In versions of Tk before 4.0, the set and get widget commands used a
193 different form. This form is still supported for backward compatibil‐
194 ity, but it is deprecated. In the old command syntax, the set method
195 has the following form:
196 $scrollbar->set(totalUnits, windowUnits, firstUnit, lastUnit)
198 In this form the arguments are all integers. TotalUnits gives the
199 total size of the object being displayed in the associated widget.
200 The meaning of one unit depends on the associated widget; for
201 example, in a text editor widget units might correspond to lines of
202 text. WindowUnits indicates the total number of units that can fit
203 in the associated window at one time. FirstUnit and lastUnit give
204 the indices of the first and last units currently visible in the
205 associated window (zero corresponds to the first unit of the
206 object).
207 Under the old syntax the get method returns a list of four integers,
209 consisting of the totalUnits, windowUnits, firstUnit, and lastUnit val‐
210 ues from the last set method.
211 The callbacks generated by scrollbars also have a different form when
213 the old syntax is being used, the callback is passed a single argument:
214 unit
216 Unit is an integer that indicates what should appear at the top or
217 left of the associated widget's window. It has the same meaning as
218 the firstUnit and lastUnit arguments to the set method.
219 The most recent set method determines whether or not to use the old
221 syntax. If it is given two real arguments then the new syntax will be
222 used in the future, and if it is given four integer arguments then the
223 old syntax will be used.
224
226 Tk automatically creates class bindings for scrollbars that give them
227 the following default behavior. If the behavior is different for ver‐
228 tical and horizontal scrollbars, the horizontal behavior is described
229 in parentheses.
230 [1] Pressing button 1 over arrow1 causes the view in the associated
232 widget to shift up (left) by one unit so that the document appears
233 to move down (right) one unit. If the button is held down, the
234 action auto-repeats.
235 [2] Pressing button 1 over trough1 causes the view in the associated
237 widget to shift up (left) by one screenful so that the document
238 appears to move down (right) one screenful. If the button is held
239 down, the action auto-repeats.
240 [3] Pressing button 1 over the slider and dragging causes the view to
242 drag with the slider. If the jump option is true, then the view
243 doesn't drag along with the slider; it changes only when the mouse
244 button is released.
245 [4] Pressing button 1 over trough2 causes the view in the associated
247 widget to shift down (right) by one screenful so that the document
248 appears to move up (left) one screenful. If the button is held
249 down, the action auto-repeats.
250 [5] Pressing button 1 over arrow2 causes the view in the associated
252 widget to shift down (right) by one unit so that the document
253 appears to move up (left) one unit. If the button is held down,
254 the action auto-repeats.
255 [6] If button 2 is pressed over the trough or the slider, it sets the
257 view to correspond to the mouse position; dragging the mouse with
258 button 2 down causes the view to drag with the mouse. If button 2
259 is pressed over one of the arrows, it causes the same behavior as
260 pressing button 1.
261 [7] If button 1 is pressed with the Control key down, then if the mouse
263 is over arrow1 or trough1 the view changes to the very top (left)
264 of the document; if the mouse is over arrow2 or trough2 the view
265 changes to the very bottom (right) of the document; if the mouse
266 is anywhere else then the button press has no effect.
267 [8] In vertical scrollbars the Up and Down keys have the same behavior
269 as mouse clicks over arrow1 and arrow2, respectively. In horizon‐
270 tal scrollbars these keys have no effect.
271 [9] In vertical scrollbars Control-Up and Control-Down have the same
273 behavior as mouse clicks over trough1 and trough2, respectively.
274 In horizontal scrollbars these keys have no effect.
275 [10]
277 In horizontal scrollbars the Up and Down keys have the same behav‐
278 ior as mouse clicks over arrow1 and arrow2, respectively. In ver‐
279 tical scrollbars these keys have no effect.
280 [11]
282 In horizontal scrollbars Control-Up and Control-Down have the same
283 behavior as mouse clicks over trough1 and trough2, respectively.
284 In vertical scrollbars these keys have no effect.
285 [12]
287 The Prior and Next keys have the same behavior as mouse clicks over
288 trough1 and trough2, respectively.
289 [13]
291 The Home key adjusts the view to the top (left edge) of the docu‐
292 ment.
293 [14]
295 The End key adjusts the view to the bottom (right edge) of the doc‐
296 ument.
297
299 Tk::callbacks Tk::Scrolled
300
302 scrollbar, widget
303perl v5.8.8 2008-02-05 Scrollbar(3)