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