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
14 -borderwidth -highlightthickness -repeatdelay
15 -cursor -jump -repeatinterval
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
33 callback is passed additional arguments as described later. This
34 option almost always has a value such as [xview => $widget] or
35 [yview => $widget], consisting of the a widget object and either
36 xview (if the scrollbar is for horizontal scrolling) or yview (for
37 vertical scrolling). All scrollable widgets have xview and yview
38 methods that take exactly the additional arguments appended by the
39 scrollbar 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
60 argument) 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,
63 orientation, and relief. The scrollbar command returns its $widget
64 argument. At the time this command is invoked, there must not exist a
65 window 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
82 methods 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
92 widget.
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
111 activeRelief options. The only element values understood by this
112 command are arrow1, slider, or arrow2. If any other value is
113 specified then no element of the scrollbar will be active. If
114 element is not specified, the command returns the name of the
115 element that is currently active, or an empty string if no element
116 is active.
117 $scrollbar->delta(deltaX, deltaY)
119 Returns a real number indicating the fractional change in the
120 scrollbar setting that corresponds to a given change in slider
121 position. For example, if the scrollbar is horizontal, the result
122 indicates how much the scrollbar setting must change to move the
123 slider deltaX pixels to the right (deltaY is ignored in this case).
124 If the scrollbar is vertical, the result indicates how much the
125 scrollbar setting must change to move the slider deltaY pixels
126 down. The arguments and the result may be zero or negative.
127 $scrollbar->fraction(x, y)
129 Returns a real number between 0 and 1 indicating where the point
130 given by x and y lies in the trough area of the scrollbar. The
131 value 0 corresponds to the top or left of the trough, the value 1
132 corresponds to the bottom or right, 0.5 corresponds to the middle,
133 and so on. X and y must be pixel coordinates relative to the
134 scrollbar widget. If x and y refer to a point outside the trough,
135 the closest point in the trough is used.
136 $scrollbar->get
138 Returns the scrollbar settings in the form of a list whose elements
139 are the arguments to the most recent set method.
140 $scrollbar->identify(x, y)
142 Returns the name of the element under the point given by x and y
143 (such as arrow1), or an empty string if the point does not lie in
144 any element of the scrollbar. X and y must be pixel coordinates
145 relative to the scrollbar widget.
146 $scrollbar->set(first, last)
148 This command is invoked by the scrollbar's associated widget to
149 tell the scrollbar about the current view in the widget. The
150 command takes two arguments, each of which is a real fraction
151 between 0 and 1. The fractions describe the range of the document
152 that is visible in the associated widget. For example, if first is
153 0.2 and last is 0.4, it means that the first part of the document
154 visible in the window is 20% of the way through the document, and
155 the last visible part is 40% of the way through.
156
158 When the user interacts with the scrollbar, for example by dragging the
159 slider, the scrollbar notifies the associated widget that it must
160 change its view. The scrollbar makes the notification by evaluating a
161 callback specified as the scrollbar's -command option. The callback
162 may take several forms. In each case, the intial arguments passed are
163 those specified in the -command callback itself, which usually has a
164 form like [yview => $widget]. (Which will invoke $widget->yview(...)
165 where the ... part is as below. See Tk::callbacks for details.) The
166 callback is passed additional arguments as follows:
167 moveto,fraction
169 Fraction is a real number between 0 and 1. The widget should
170 adjust its view so that the point given by fraction appears at the
171 beginning of the widget. If fraction is 0 it refers to the
172 beginning of the document. 1.0 refers to the end of the document,
173 0.333 refers to a point one-third of the way through the document,
174 and so on.
175 scroll,number,units
177 The widget should adjust its view by number units. The units are
178 defined in whatever way makes sense for the widget, such as
179 characters or lines in a text widget. Number is either 1, which
180 means one unit should scroll off the top or left of the window, or
181 -1, which means that one unit should scroll off the bottom or right
182 of the window.
183 scroll,number,page
185 The widget should adjust its view by number pages. It is up to the
186 widget to define the meaning of a page; typically it is slightly
187 less than what fits in the window, so that there is a slight
188 overlap between the old and new views. Number is either 1, which
189 means the next page should become visible, or -1, which means that
190 the previous page should become visible.
191
193 In versions of Tk before 4.0, the set and get widget commands used a
194 different form. This form is still supported for backward
195 compatibility, but it is deprecated. In the old command syntax, the
196 set method has the following form:
197 $scrollbar->set(totalUnits, windowUnits, firstUnit, lastUnit)
199 In this form the arguments are all integers. TotalUnits gives the
200 total size of the object being displayed in the associated widget.
201 The meaning of one unit depends on the associated widget; for
202 example, in a text editor widget units might correspond to lines of
203 text. WindowUnits indicates the total number of units that can fit
204 in the associated window at one time. FirstUnit and lastUnit give
205 the indices of the first and last units currently visible in the
206 associated window (zero corresponds to the first unit of the
207 object).
208 Under the old syntax the get method returns a list of four integers,
210 consisting of the totalUnits, windowUnits, firstUnit, and lastUnit
211 values from the last set method.
212 The callbacks generated by scrollbars also have a different form when
214 the old syntax is being used, the callback is passed a single argument:
215 unit
217 Unit is an integer that indicates what should appear at the top or
218 left of the associated widget's window. It has the same meaning as
219 the firstUnit and lastUnit arguments to the set method.
220 The most recent set method determines whether or not to use the old
222 syntax. If it is given two real arguments then the new syntax will be
223 used in the future, and if it is given four integer arguments then the
224 old syntax will be used.
225
227 Tk automatically creates class bindings for scrollbars that give them
228 the following default behavior. If the behavior is different for
229 vertical and horizontal scrollbars, the horizontal behavior is
230 described in parentheses.
231 [1] Pressing button 1 over arrow1 causes the view in the associated
233 widget to shift up (left) by one unit so that the document appears
234 to move down (right) one unit. If the button is held down, the
235 action auto-repeats.
236 [2] Pressing button 1 over trough1 causes the view in the associated
238 widget to shift up (left) by one screenful so that the document
239 appears to move down (right) one screenful. If the button is held
240 down, the action auto-repeats.
241 [3] Pressing button 1 over the slider and dragging causes the view to
243 drag with the slider. If the jump option is true, then the view
244 doesn't drag along with the slider; it changes only when the mouse
245 button is released.
246 [4] Pressing button 1 over trough2 causes the view in the associated
248 widget to shift down (right) by one screenful so that the document
249 appears to move up (left) one screenful. If the button is held
250 down, the action auto-repeats.
251 [5] Pressing button 1 over arrow2 causes the view in the associated
253 widget to shift down (right) by one unit so that the document
254 appears to move up (left) one unit. If the button is held down,
255 the action auto-repeats.
256 [6] If button 2 is pressed over the trough or the slider, it sets the
258 view to correspond to the mouse position; dragging the mouse with
259 button 2 down causes the view to drag with the mouse. If button 2
260 is pressed over one of the arrows, it causes the same behavior as
261 pressing button 1.
262 [7] If button 1 is pressed with the Control key down, then if the mouse
264 is over arrow1 or trough1 the view changes to the very top (left)
265 of the document; if the mouse is over arrow2 or trough2 the view
266 changes to the very bottom (right) of the document; if the mouse
267 is anywhere else then the button press has no effect.
268 [8] In vertical scrollbars the Up and Down keys have the same behavior
270 as mouse clicks over arrow1 and arrow2, respectively. In
271 horizontal scrollbars these keys have no effect.
272 [9] In vertical scrollbars Control-Up and Control-Down have the same
274 behavior as mouse clicks over trough1 and trough2, respectively.
275 In horizontal scrollbars these keys have no effect.
276 [10]
278 In horizontal scrollbars the Up and Down keys have the same
279 behavior as mouse clicks over arrow1 and arrow2, respectively. In
280 vertical scrollbars these keys have no effect.
281 [11]
283 In horizontal scrollbars Control-Up and Control-Down have the same
284 behavior as mouse clicks over trough1 and trough2, respectively.
285 In vertical scrollbars these keys have no effect.
286 [12]
288 The Prior and Next keys have the same behavior as mouse clicks over
289 trough1 and trough2, respectively.
290 [13]
292 The Home key adjusts the view to the top (left edge) of the
293 document.
294 [14]
296 The End key adjusts the view to the bottom (right edge) of the
297 document.
298
300 Tk::callbacks Tk::Scrolled
301
303 scrollbar, widget
304perl v5.36.0 2023-01-20 Scrollbar(3)