2 '\" Copyright (c) 1990-1994 The Regents of the University of California.
3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
5 '\" See the file "license.terms" for information on usage and redistribution
6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
8 .TH scrollbar n 4.1 Tk "Tk Built-In Commands"
9 .\" The -*- nroff -*- definitions below are for supplemental macros used
10 .\" in Tcl/Tk manual entries.
12 .\" .AP type name in/out ?indent?
13 .\" Start paragraph describing an argument to a library procedure.
14 .\" type is type of argument (int, etc.), in/out is either "in", "out",
15 .\" or "in/out" to describe whether procedure reads or modifies arg,
16 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
17 .\" needed; use .AS below instead)
20 .\" Give maximum sizes of arguments for setting tab stops. Type and
21 .\" name are examples of largest possible arguments that will be passed
22 .\" to .AP later. If args are omitted, default tab stops are used.
25 .\" Start box enclosure. From here until next .BE, everything will be
26 .\" enclosed in one large box.
29 .\" End of box enclosure.
32 .\" Begin code excerpt.
37 .\" .VS ?version? ?br?
38 .\" Begin vertical sidebar, for use in marking newly-changed parts
39 .\" of man pages. The first argument is ignored and used for recording
40 .\" the version when the .VS was added, so that the sidebars can be
41 .\" found and removed when they reach a certain age. If another argument
42 .\" is present, then a line break is forced before starting the sidebar.
45 .\" End of vertical sidebar.
48 .\" Begin an indented unfilled display.
51 .\" End of indented unfilled display.
54 .\" Start of list of standard options for a Tk widget. The manpage
55 .\" argument defines where to look up the standard options; if
56 .\" omitted, defaults to "options". The options follow on successive
57 .\" lines, in three columns separated by tabs.
60 .\" End of list of standard options for a Tk widget.
62 .\" .OP cmdName dbName dbClass
63 .\" Start of description of a specific option. cmdName gives the
64 .\" option's name as specified in the class command, dbName gives
65 .\" the option's name in the option database, and dbClass gives
66 .\" the option's class in the option database.
69 .\" Print arg1 underlined, then print arg2 normally.
72 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
75 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
76 .\" (for trailing punctuation) and then a closing parenthesis.
78 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
82 .\" # Start an argument description
86 . ie !"\\$2"" .TP \\n()Cu
91 \&\\$1 \\fI\\$2\\fP (\\$3)
104 .\" # define tabbing values for .AP
107 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
110 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
111 .nr )C \\n()Bu+\\w'(in/out)'u+2n
113 .AS Tcl_Interp Tcl_CreateInterp in/out
114 .\" # BS - start boxed text
115 .\" # ^y = starting y location
123 .if n \l'\\n(.lu\(ul'
126 .\" # BE - end boxed text (draw box now)
131 .ie n \l'\\n(^lu\(ul'
133 .\" Draw four-sided box normally, but don't draw top of
134 .\" box if the box started on an earlier page.
136 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
139 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
146 .\" # VS - start vertical sidebar
147 .\" # ^Y = starting y location
148 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
152 .ie n 'mc \s12\(br\s0
155 .\" # VE - end of vertical sidebar
163 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
170 .\" # Special macro to handle page bottom: finish off current
171 .\" # box/sidebar if in box/sidebar mode, then invoked standard
172 .\" # page bottom macro.
179 .\" Draw three-sided box if this is the box's first page,
180 .\" draw two sides but no top otherwise.
181 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
182 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
185 .nr ^x \\n(^tu+1v-\\n(^Yu
186 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
199 .\" # DS - begin display
205 .\" # DE - end display
211 .\" # SO - start of list of standard options
213 'ie '\\$1'' .ds So \\fBoptions\\fR
214 'el .ds So \\fB\\$1\\fR
215 .SH "STANDARD OPTIONS"
221 .\" # SE - end of list of standard options
226 See the \\*(So manual entry for details on the standard options.
228 .\" # OP - start of full description for a single option
233 Command-Line Name: \\fB\\$1\\fR
234 Database Name: \\fB\\$2\\fR
235 Database Class: \\fB\\$3\\fR
239 .\" # CS - begin code excerpt
245 .\" # CE - end code excerpt
250 .\" # UL - underline word
254 .\" # QW - apply quotation marks to word
256 .ie '\\*(lq'"' ``\\$1''\\$2
257 .\"" fix emacs highlighting
258 .el \\*(lq\\$1\\*(rq\\$2
260 .\" # PQ - apply parens and quotation marks to word
262 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
263 .\"" fix emacs highlighting
264 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
266 .\" # QR - quoted range
268 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
269 .\"" fix emacs highlighting
270 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
272 .\" # MT - "empty" string
277 '\" Note: do not modify the .SH NAME line immediately below!
279 scrollbar \- Create and manipulate 'scrollbar' scrolling control and indicator widgets
281 \fBscrollbar\fR \fIpathName \fR?\fIoptions\fR?
283 \-activebackground \-highlightcolor \-repeatdelay
284 \-background \-highlightthickness \-repeatinterval
285 \-borderwidth \-jump \-takefocus
286 \-cursor \-orient \-troughcolor
287 \-highlightbackground \-relief
289 .SH "WIDGET-SPECIFIC OPTIONS"
290 .OP \-activerelief activeRelief ActiveRelief
291 Specifies the relief to use when displaying the element that is
293 Elements other than the active element are always displayed with
295 .OP \-command command Command
296 Specifies the prefix of a Tcl command to invoke to change the view
297 in the widget associated with the scrollbar. When a user requests
298 a view change by manipulating the scrollbar, a Tcl command is
299 invoked. The actual command consists of this option followed by
300 additional information as described later. This option almost always has
301 a value such as \fB.t xview\fR or \fB.t yview\fR, consisting of the
302 name of a widget and either \fBxview\fR (if the scrollbar is for
303 horizontal scrolling) or \fByview\fR (for vertical scrolling).
304 All scrollable widgets have \fBxview\fR and \fByview\fR commands
305 that take exactly the additional arguments appended by the scrollbar
306 as described in \fBSCROLLING COMMANDS\fR below.
307 .OP \-elementborderwidth elementBorderWidth BorderWidth
308 Specifies the width of borders drawn around the internal elements
309 of the scrollbar (the two arrows and the slider). The value may
310 have any of the forms acceptable to \fBTk_GetPixels\fR.
311 If this value is less than zero, the value of the \fB\-borderwidth\fR
312 option is used in its place.
313 .OP \-width width Width
314 Specifies the desired narrow dimension of the scrollbar window,
315 not including 3-D border, if any. For vertical
316 scrollbars this will be the width and for horizontal scrollbars
317 this will be the height.
318 The value may have any of the forms acceptable to \fBTk_GetPixels\fR.
322 The \fBscrollbar\fR command creates a new window (given by the
323 \fIpathName\fR argument) and makes it into a scrollbar widget.
324 Additional options, described above, may be specified on the command
325 line or in the option database to configure aspects of the scrollbar
326 such as its colors, orientation, and relief.
327 The \fBscrollbar\fR command returns its \fIpathName\fR argument.
328 At the time this command is invoked, there must not exist a window
329 named \fIpathName\fR, but \fIpathName\fR's parent must exist.
331 A scrollbar is a widget that displays two arrows, one at each end of
332 the scrollbar, and a \fIslider\fR in the middle portion of the
334 It provides information about what is visible in an \fIassociated window\fR
335 that displays a document of some sort (such as a file being edited or
337 The position and size of the slider indicate which portion of the
338 document is visible in the associated window. For example, if the
339 slider in a vertical scrollbar covers the top third of the area
340 between the two arrows, it means that the associated window displays
341 the top third of its document.
343 Scrollbars can be used to adjust the view in the associated window
344 by clicking or dragging with the mouse. See the \fBBINDINGS\fR section
348 A scrollbar displays five elements, which are referred to in the
349 widget commands for the scrollbar:
352 The top or left arrow in the scrollbar.
355 The region between the slider and \fBarrow1\fR.
358 The rectangle that indicates what is visible in the associated widget.
361 The region between the slider and \fBarrow2\fR.
364 The bottom or right arrow in the scrollbar.
367 The \fBscrollbar\fR command creates a new Tcl command whose
368 name is \fIpathName\fR. This
369 command may be used to invoke various
370 operations on the widget. It has the following general form:
372 \fIpathName option \fR?\fIarg arg ...\fR?
374 \fIOption\fR and the \fIarg\fRs
375 determine the exact behavior of the command. The following
376 commands are possible for scrollbar widgets:
378 \fIpathName \fBactivate \fR?\fIelement\fR?
380 Marks the element indicated by \fIelement\fR as active, which
381 causes it to be displayed as specified by the \fB\-activebackground\fR
382 and \fB\-activerelief\fR options.
383 The only element values understood by this command are \fBarrow1\fR,
384 \fBslider\fR, or \fBarrow2\fR.
385 If any other value is specified then no element of the scrollbar
387 If \fIelement\fR is not specified, the command returns
388 the name of the element that is currently active, or an empty string
389 if no element is active.
391 \fIpathName \fBcget \fIoption\fR
393 Returns the current value of the configuration option given
395 \fIOption\fR may have any of the values accepted by the \fBscrollbar\fR
398 \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
400 Query or modify the configuration options of the widget.
401 If no \fIoption\fR is specified, returns a list describing all of
402 the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for
403 information on the format of this list). If \fIoption\fR is specified
404 with no \fIvalue\fR, then the command returns a list describing the
405 one named option (this list will be identical to the corresponding
406 sublist of the value returned if no \fIoption\fR is specified). If
407 one or more \fIoption\-value\fR pairs are specified, then the command
408 modifies the given widget option(s) to have the given value(s); in
409 this case the command returns an empty string.
410 \fIOption\fR may have any of the values accepted by the \fBscrollbar\fR
413 \fIpathName \fBdelta \fIdeltaX deltaY\fR
415 Returns a real number indicating the fractional change in
416 the scrollbar setting that corresponds to a given change
417 in slider position. For example, if the scrollbar is horizontal,
418 the result indicates how much the scrollbar setting must change
419 to move the slider \fIdeltaX\fR pixels to the right (\fIdeltaY\fR is
420 ignored in this case).
421 If the scrollbar is vertical, the result indicates how much the
422 scrollbar setting must change to move the slider \fIdeltaY\fR pixels
423 down. The arguments and the result may be zero or negative.
425 \fIpathName \fBfraction \fIx y\fR
427 Returns a real number between 0 and 1 indicating where the point
428 given by \fIx\fR and \fIy\fR lies in the trough area of the scrollbar.
429 The value 0 corresponds to the top or left of the trough, the
430 value 1 corresponds to the bottom or right, 0.5 corresponds to
431 the middle, and so on.
432 \fIX\fR and \fIy\fR must be pixel coordinates relative to the scrollbar
434 If \fIx\fR and \fIy\fR refer to a point outside the trough, the closest
435 point in the trough is used.
437 \fIpathName \fBget\fR
439 Returns the scrollbar settings in the form of a list whose
440 elements are the arguments to the most recent \fBset\fR widget command.
442 \fIpathName \fBidentify \fIx y\fR
444 Returns the name of the element under the point given by \fIx\fR and
445 \fIy\fR (such as \fBarrow1\fR), or an empty string if the point does
446 not lie in any element of the scrollbar.
447 \fIX\fR and \fIy\fR must be pixel coordinates relative to the scrollbar
450 \fIpathName \fBset \fIfirst last\fR
452 This command is invoked by the scrollbar's associated widget to
453 tell the scrollbar about the current view in the widget.
454 The command takes two arguments, each of which is a real fraction
456 The fractions describe the range of the document that is visible in
457 the associated widget.
458 For example, if \fIfirst\fR is 0.2 and \fIlast\fR is 0.4, it means
459 that the first part of the document visible in the window is 20%
460 of the way through the document, and the last visible part is 40%
462 .SH "SCROLLING COMMANDS"
464 When the user interacts with the scrollbar, for example by dragging
465 the slider, the scrollbar notifies the associated widget that it
466 must change its view.
467 The scrollbar makes the notification by evaluating a Tcl command
468 generated from the scrollbar's \fB\-command\fR option.
469 The command may take any of the following forms.
470 In each case, \fIprefix\fR is the contents of the
471 \fB\-command\fR option, which usually has a form like
474 \fIprefix \fBmoveto \fIfraction\fR
476 \fIFraction\fR is a real number between 0 and 1.
477 The widget should adjust its view so that the point given
478 by \fIfraction\fR appears at the beginning of the widget.
479 If \fIfraction\fR is 0 it refers to the beginning of the
480 document. 1.0 refers to the end of the document, 0.333
481 refers to a point one-third of the way through the document,
484 \fIprefix \fBscroll \fInumber \fBunits\fR
486 The widget should adjust its view by \fInumber\fR units.
487 The units are defined in whatever way makes sense for the widget,
488 such as characters or lines in a text widget.
489 \fINumber\fR is either 1, which means one unit should scroll off
490 the top or left of the window, or \-1, which means that one unit
491 should scroll off the bottom or right of the window.
493 \fIprefix \fBscroll \fInumber \fBpages\fR
495 The widget should adjust its view by \fInumber\fR pages.
496 It is up to the widget to define the meaning of a page; typically
497 it is slightly less than what fits in the window, so that there
498 is a slight overlap between the old and new views.
499 \fINumber\fR is either 1, which means the next page should
500 become visible, or \-1, which means that the previous page should
502 .SH "OLD COMMAND SYNTAX"
504 In versions of Tk before 4.0, the \fBset\fR and \fBget\fR widget
505 commands used a different form.
506 This form is still supported for backward compatibility, but it
508 In the old command syntax, the \fBset\fR widget command has the
511 \fIpathName \fBset \fItotalUnits windowUnits firstUnit lastUnit\fR
512 In this form the arguments are all integers.
513 \fITotalUnits\fR gives the total size of the object being displayed in the
514 associated widget. The meaning of one unit depends on the associated
515 widget; for example, in a text editor widget units might
516 correspond to lines of
517 text. \fIWindowUnits\fR indicates the total number of units that
518 can fit in the associated window at one time. \fIFirstUnit\fR
519 and \fIlastUnit\fR give the indices of the first and last units
520 currently visible in the associated window (zero corresponds to the
521 first unit of the object).
523 Under the old syntax the \fBget\fR widget command returns a list
524 of four integers, consisting of the \fItotalUnits\fR, \fIwindowUnits\fR,
525 \fIfirstUnit\fR, and \fIlastUnit\fR values from the last \fBset\fR
528 The commands generated by scrollbars also have a different form
529 when the old syntax is being used:
531 \fIprefix\fR \fIunit\fR
532 \fIUnit\fR is an integer that indicates what should appear at
533 the top or left of the associated widget's window.
534 It has the same meaning as the \fIfirstUnit\fR and \fIlastUnit\fR
535 arguments to the \fBset\fR widget command.
537 The most recent \fBset\fR widget command determines whether or not
538 to use the old syntax.
539 If it is given two real arguments then the new syntax will be
540 used in the future, and if it is given four integer arguments then
541 the old syntax will be used.
544 Tk automatically creates class bindings for scrollbars that give them
545 the following default behavior.
546 If the behavior is different for vertical and horizontal scrollbars,
547 the horizontal behavior is described in parentheses.
549 Pressing button 1 over \fBarrow1\fR causes the view in the
550 associated widget to shift up (left) by one unit so that the
551 document appears to move down (right) one unit.
552 If the button is held down, the action auto-repeats.
554 Pressing button 1 over \fBtrough1\fR causes the view in the
555 associated widget to shift up (left) by one screenful so that the
556 document appears to move down (right) one screenful.
557 If the button is held down, the action auto-repeats.
559 Pressing button 1 over the slider and dragging causes the view
560 to drag with the slider.
561 If the \fBjump\fR option is true, then the view does not drag along
562 with the slider; it changes only when the mouse button is released.
564 Pressing button 1 over \fBtrough2\fR causes the view in the
565 associated widget to shift down (right) by one screenful so that the
566 document appears to move up (left) one screenful.
567 If the button is held down, the action auto-repeats.
569 Pressing button 1 over \fBarrow2\fR causes the view in the
570 associated widget to shift down (right) by one unit so that the
571 document appears to move up (left) one unit.
572 If the button is held down, the action auto-repeats.
574 If button 2 is pressed over the trough or the slider, it sets
575 the view to correspond to the mouse position; dragging the
576 mouse with button 2 down causes the view to drag with the mouse.
577 If button 2 is pressed over one of the arrows, it causes the
578 same behavior as pressing button 1.
580 If button 1 is pressed with the Control key down, then if the
581 mouse is over \fBarrow1\fR or \fBtrough1\fR the view changes
582 to the very top (left) of the document; if the mouse is over
583 \fBarrow2\fR or \fBtrough2\fR the view changes
584 to the very bottom (right) of the document; if the mouse is
585 anywhere else then the button press has no effect.
587 In vertical scrollbars the Up and Down keys have the same behavior
588 as mouse clicks over \fBarrow1\fR and \fBarrow2\fR, respectively.
589 In horizontal scrollbars these keys have no effect.
591 In vertical scrollbars Control-Up and Control-Down have the same
592 behavior as mouse clicks over \fBtrough1\fR and \fBtrough2\fR, respectively.
593 In horizontal scrollbars these keys have no effect.
595 In horizontal scrollbars the Up and Down keys have the same behavior
596 as mouse clicks over \fBarrow1\fR and \fBarrow2\fR, respectively.
597 In vertical scrollbars these keys have no effect.
599 In horizontal scrollbars Control-Up and Control-Down have the same
600 behavior as mouse clicks over \fBtrough1\fR and \fBtrough2\fR, respectively.
601 In vertical scrollbars these keys have no effect.
603 The Prior and Next keys have the same behavior
604 as mouse clicks over \fBtrough1\fR and \fBtrough2\fR, respectively.
606 The Home key adjusts the view to the top (left edge) of the document.
608 The End key adjusts the view to the bottom (right edge) of the document.
611 Create a window with a scrollable \fBtext\fR widget:
614 text .tl.t \-yscrollcommand {.tl.s set}
615 \fBscrollbar\fR .tl.s \-command {.tl.t yview}
616 grid .tl.t .tl.s \-sticky nsew
617 grid columnconfigure .tl 0 \-weight 1
618 grid rowconfigure .tl 0 \-weight 1
OSDN Git Service
