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