1#  Copyright (c) 1990-1994 The Regents of the University of California.
2#  Copyright (c) 1994-1996 Sun Microsystems, Inc.
3#  See the file "license.terms" for information on usage and redistribution
4#  of this file, and for a DISCLAIMER OF ALL WARRANTIES.
5#
6#
7
8=head1 NAME
9
10Tk::Scrollbar - Create and manipulate Scrollbar widgets
11
12=for category  Tk Widget Classes
13
14=head1 SYNOPSIS
15
16I<$scrollbar> = I<$parent>-E<gt>B<Scrollbar>(?I<options>?);
17
18=head1 STANDARD OPTIONS
19
20B<-activebackground>	B<-highlightbackground>	B<-orient>	B<-takefocus>
21B<-background>	B<-highlightcolor>	B<-relief>	B<-troughcolor>
22B<-borderwidth>	B<-highlightthickness>	B<-repeatdelay>
23B<-cursor>	B<-jump>	B<-repeatinterval>
24
25See L<Tk::options> for details of the standard options.
26
27=head1 WIDGET-SPECIFIC OPTIONS
28
29=over 4
30
31=item Name:	B<activeRelief>
32
33=item Class:	B<ActiveRelief>
34
35=item Switch:	B<-activerelief>
36
37Specifies the relief to use when displaying the element that is
38active, if any.
39Elements other than the active element are always displayed with
40a raised relief.
41
42=item Name:	B<command>
43
44=item Class:	B<Command>
45
46=item Switch:	B<-command>
47
48Specifies a callback to invoke to change the view
49in the widget associated with the scrollbar.  When a user requests
50a view change by manipulating the scrollbar, the callback is
51invoked.  The callback is passed
52additional arguments as described later. This option almost always has
53a value such as B<[xview =E<gt> $widget]> or B<[yview =E<gt> $widget]>, consisting of the
54a widget object and either B<xview> (if the scrollbar is for
55horizontal scrolling) or B<yview> (for vertical scrolling).
56All scrollable widgets have B<xview> and B<yview> methods
57that take exactly the additional arguments appended by the scrollbar
58as described in L<"SCROLLING COMMANDS"> below.
59
60=item Name:	B<elementBorderWidth>
61
62=item Class:	B<BorderWidth>
63
64=item Switch:	B<-elementborderwidth>
65
66Specifies the width of borders drawn around the internal elements
67of the scrollbar (the two arrows and the slider).  The value may
68have any of the forms acceptable to B<Tk_GetPixels>.
69If this value is less than zero, the value of the B<borderWidth>
70option is used in its place.
71
72=item Name:	B<width>
73
74=item Class:	B<Width>
75
76=item Switch:	B<-width>
77
78Specifies the desired narrow dimension of the scrollbar window,
79not including 3-D border, if any.  For vertical
80scrollbars this will be the width and for horizontal scrollbars
81this will be the height.
82The value may have any of the forms acceptable to B<Tk_GetPixels>.
83
84=back
85
86=head1 DESCRIPTION
87
88The B<Scrollbar> method creates a new window (given by the
89$widget argument) and makes it into a scrollbar widget.
90Additional options, described above, may be specified on the command
91line or in the option database to configure aspects of the scrollbar
92such as its colors, orientation, and relief.
93The B<scrollbar> command returns its $widget argument.
94At the time this command is invoked, there must not exist a window
95named $widget, but $widget's parent must exist.
96
97A scrollbar is a widget that displays two arrows, one at each end of
98the scrollbar, and a I<slider> in the middle portion of the
99scrollbar.
100It provides information about what is visible in an I<associated window>
101that displays an document of some sort (such as a file being edited or
102a drawing).
103The position and size of the slider indicate which portion of the
104document is visible in the associated window.  For example, if the
105slider in a vertical scrollbar covers the top third of the area
106between the two arrows, it means that the associated window displays
107the top third of its document.
108
109Scrollbars can be used to adjust the view in the associated window
110by clicking or dragging with the mouse.
111See L<"BINDINGS"> below for details.
112
113=head1 ELEMENTS
114
115A scrollbar displays five elements, which are referred to in the
116methods for the scrollbar:
117
118=over 4
119
120=item B<arrow1>
121
122The top or left arrow in the scrollbar.
123
124=item B<trough1>
125
126The region between the slider and B<arrow1>.
127
128=item B<slider>
129
130The rectangle that indicates what is visible in the associated widget.
131
132=item B<trough2>
133
134The region between the slider and B<arrow2>.
135
136=item B<arrow2>
137
138The bottom or right arrow in the scrollbar.
139
140=back
141
142=head1 WIDGET METHODS
143
144The B<Scrollbar> method creates a widget object.
145This object supports the B<configure> and B<cget> methods
146described in L<Tk::options> which can be used to enquire and
147modify the options described above.
148The widget also inherits all the methods provided by the generic
149L<Tk::Widget|Tk::Widget> class.
150
151The following additional methods are available for scrollbar widgets:
152
153=over 4
154
155=item I<$scrollbar>-E<gt>B<activate>(?I<element>?)
156
157Marks the element indicated by I<element> as active, which
158causes it to be displayed as specified by the B<activeBackground>
159and B<activeRelief> options.
160The only element values understood by this command are B<arrow1>,
161B<slider>, or B<arrow2>.
162If any other value is specified then no element of the scrollbar
163will be active.
164If I<element> is not specified, the command returns
165the name of the element that is currently active, or an empty string
166if no element is active.
167
168=item I<$scrollbar>-E<gt>B<delta>(I<deltaX, deltaY>)
169
170Returns a real number indicating the fractional change in
171the scrollbar setting that corresponds to a given change
172in slider position.  For example, if the scrollbar is horizontal,
173the result indicates how much the scrollbar setting must change
174to move the slider I<deltaX> pixels to the right (I<deltaY> is
175ignored in this case).
176If the scrollbar is vertical, the result indicates how much the
177scrollbar setting must change to move the slider I<deltaY> pixels
178down.  The arguments and the result may be zero or negative.
179
180=item I<$scrollbar>-E<gt>B<fraction>(I<x, y>)
181
182Returns a real number between 0 and 1 indicating where the point
183given by I<x> and I<y> lies in the trough area of the scrollbar.
184The value 0 corresponds to the top or left of the trough, the
185value 1 corresponds to the bottom or right, 0.5 corresponds to
186the middle, and so on.
187I<X> and I<y> must be pixel coordinates relative to the scrollbar
188widget.
189If I<x> and I<y> refer to a point outside the trough, the closest
190point in the trough is used.
191
192=item I<$scrollbar>-E<gt>B<get>
193
194Returns the scrollbar settings in the form of a list whose
195elements are the arguments to the most recent B<set> method.
196
197=item I<$scrollbar>-E<gt>B<identify>(I<x, y>)
198
199Returns the name of the element under the point given by I<x> and
200I<y> (such as B<arrow1>), or an empty string if the point does
201not lie in any element of the scrollbar.
202I<X> and I<y> must be pixel coordinates relative to the scrollbar
203widget.
204
205=item I<$scrollbar>-E<gt>B<set>(I<first, last>)
206
207This command is invoked by the scrollbar's associated widget to
208tell the scrollbar about the current view in the widget.
209The command takes two arguments, each of which is a real fraction
210between 0 and 1.
211The fractions describe the range of the document that is visible in
212the associated widget.
213For example, if I<first> is 0.2 and I<last> is 0.4, it means
214that the first part of the document visible in the window is 20%
215of the way through the document, and the last visible part is 40%
216of the way through.
217
218=back
219
220=head1 SCROLLING COMMANDS
221
222When the user interacts with the scrollbar, for example by dragging
223the slider, the scrollbar notifies the associated widget that it
224must change its view.
225The scrollbar makes the notification by evaluating a callback
226specified as the scrollbar's B<-command> option.
227The callback may take several forms.
228In each case, the intial arguments passed are those
229specified in the B<-command> callback itself,
230which usually has a form like [B<yview> =E<gt> I<$widget>].
231(Which will invoke I<$widget>-E<gt>B<yview>(...) where
232the ... part is as below. See L<Tk::callbacks> for details.)
233The callback is passed additional arguments as follows:
234
235=over 4
236
237=item B<moveto>,I<fraction>
238
239I<Fraction> is a real number between 0 and 1.
240The widget should adjust its view so that the point given
241by I<fraction> appears at the beginning of the widget.
242If I<fraction> is 0 it refers to the beginning of the
243document.  1.0 refers to the end of the document, 0.333
244refers to a point one-third of the way through the document,
245and so on.
246
247=item B<scroll,>I<number,>B<units>
248
249The widget should adjust its view by I<number> units.
250The units are defined in whatever way makes sense for the widget,
251such as characters or lines in a text widget.
252I<Number> is either 1, which means one unit should scroll off
253the top or left of the window, or -1, which means that one unit
254should scroll off the bottom or right of the window.
255
256=item B<scroll>,I<number>,B<page>
257
258The widget should adjust its view by I<number> pages.
259It is up to the widget to define the meaning of a page;  typically
260it is slightly less than what fits in the window, so that there
261is a slight overlap between the old and new views.
262I<Number> is either 1, which means the next page should
263become visible, or -1, which means that the previous page should
264become visible.
265
266=back
267
268=head1 OLD COMMAND SYNTAX
269
270In versions of Tk before 4.0, the B<set> and B<get> widget
271commands used a different form.
272This form is still supported for backward compatibility, but it
273is deprecated.
274In the old command syntax, the B<set> method has the
275following form:
276
277=over 4
278
279=item I<$scrollbar>-E<gt>B<set>(I<totalUnits, windowUnits, firstUnit, lastUnit>)
280
281In this form the arguments are all integers.
282I<TotalUnits> gives the total size of the object being displayed in the
283associated widget.  The meaning of one unit depends on the associated
284widget;  for example, in a text editor widget units might
285correspond to lines of
286text.  I<WindowUnits> indicates the total number of units that
287can fit in the associated window at one time.  I<FirstUnit>
288and I<lastUnit> give the indices of the first and last units
289currently visible in the associated window (zero corresponds to the
290first unit of the object).
291
292=back
293
294Under the old syntax the B<get> method returns a list
295of four integers, consisting of the I<totalUnits>, I<windowUnits>,
296I<firstUnit>, and I<lastUnit> values from the last B<set>
297method.
298
299The callbacks generated by scrollbars also have a different form
300when the old syntax is being used, the callback is passed a single argument:
301
302=over 4
303
304=item I<unit>
305
306I<Unit> is an integer that indicates what should appear at
307the top or left of the associated widget's window.
308It has the same meaning as the I<firstUnit> and I<lastUnit>
309arguments to the B<set> method.
310
311=back
312
313The most recent B<set> method determines whether or not
314to use the old syntax.
315If it is given two real arguments then the new syntax will be
316used in the future, and if it is given four integer arguments then
317the old syntax will be used.
318
319=head1 BINDINGS
320
321Tk automatically creates class bindings for scrollbars that give them
322the following default behavior.
323If the behavior is different for vertical and horizontal scrollbars,
324the horizontal behavior is described in parentheses.
325
326=over 4
327
328=item [1]
329
330Pressing button 1 over B<arrow1> causes the view in the
331associated widget to shift up (left) by one unit so that the
332document appears to move down (right) one unit.
333If the button is held down, the action auto-repeats.
334
335=item [2]
336
337Pressing button 1 over B<trough1> causes the view in the
338associated widget to shift up (left) by one screenful so that the
339document appears to move down (right) one screenful.
340If the button is held down, the action auto-repeats.
341
342=item [3]
343
344Pressing button 1 over the slider and dragging causes the view
345to drag with the slider.
346If the B<jump> option is true, then the view doesn't drag along
347with the slider;  it changes only when the mouse button is released.
348
349=item [4]
350
351Pressing button 1 over B<trough2> causes the view in the
352associated widget to shift down (right) by one screenful so that the
353document appears to move up (left) one screenful.
354If the button is held down, the action auto-repeats.
355
356=item [5]
357
358Pressing button 1 over B<arrow2> causes the view in the
359associated widget to shift down (right) by one unit so that the
360document appears to move up (left) one unit.
361If the button is held down, the action auto-repeats.
362
363=item [6]
364
365If button 2 is pressed over the trough or the slider, it sets
366the view to correspond to the mouse position;  dragging the
367mouse with button 2 down causes the view to drag with the mouse.
368If button 2 is pressed over one of the arrows, it causes the
369same behavior as pressing button 1.
370
371=item [7]
372
373If button 1 is pressed with the Control key down, then if the
374mouse is over B<arrow1> or B<trough1> the view changes
375to the very top (left) of the document;  if the mouse is over
376B<arrow2> or B<trough2> the view changes
377to the very bottom (right) of the document;  if the mouse is
378anywhere else then the button press has no effect.
379
380=item [8]
381
382In vertical scrollbars the Up and Down keys have the same behavior
383as mouse clicks over B<arrow1> and B<arrow2>, respectively.
384In horizontal scrollbars these keys have no effect.
385
386=item [9]
387
388In vertical scrollbars Control-Up and Control-Down have the same
389behavior as mouse clicks over B<trough1> and B<trough2>, respectively.
390In horizontal scrollbars these keys have no effect.
391
392=item [10]
393
394In horizontal scrollbars the Up and Down keys have the same behavior
395as mouse clicks over B<arrow1> and B<arrow2>, respectively.
396In vertical scrollbars these keys have no effect.
397
398=item [11]
399
400In horizontal scrollbars Control-Up and Control-Down have the same
401behavior as mouse clicks over B<trough1> and B<trough2>, respectively.
402In vertical scrollbars these keys have no effect.
403
404=item [12]
405
406The Prior and Next keys have the same behavior
407as mouse clicks over B<trough1> and B<trough2>, respectively.
408
409=item [13]
410
411The Home key adjusts the view to the top (left edge) of the document.
412
413=item [14]
414
415The End key adjusts the view to the bottom (right edge) of the document.
416
417=back
418
419=head1 SEE ALSO
420
421L<Tk::callbacks|Tk::callbacks>
422L<Tk::Scrolled|Tk::Scrolled>
423
424=head1 KEYWORDS
425
426scrollbar, widget
427
428=cut
429
430