1scrollbar(n)                 Tk Built-In Commands                 scrollbar(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       scrollbar  -  Create  and  manipulate 'scrollbar' scrolling control and
9       indicator widgets
10

SYNOPSIS

12       scrollbar pathName ?options?
13

STANDARD OPTIONS

15       -activebackground     -highlightcolor      -repeatdelay
16       -background           -highlightthickness  -repeatinterval
17       -borderwidth          -jump                -takefocus
18       -cursor               -orient              -troughcolor
19       -highlightbackground  -relief
20
21       See the options manual entry for details on the standard options.
22

WIDGET-SPECIFIC OPTIONS

24       Command-Line Name:-activerelief
25       Database Name:  activeRelief
26       Database Class: ActiveRelief
27
28              Specifies the relief to use when displaying the element that  is
29              active,  if  any.   Elements  other  than the active element are
30              always displayed with a raised relief.
31
32       Command-Line Name:-command
33       Database Name:  command
34       Database Class: Command
35
36              Specifies the prefix of a Tcl command to invoke  to  change  the
37              view  in  the widget associated with the scrollbar.  When a user
38              requests a view change by manipulating the scrollbar, a Tcl com‐
39              mand  is  invoked.   The  actual command consists of this option
40              followed by additional information  as  described  later.   This
41              option  almost  always has a value such as .t xview or .t yview,
42              consisting of the name of a widget  and  either  xview  (if  the
43              scrollbar  is  for  horizontal scrolling) or yview (for vertical
44              scrolling).  All scrollable widgets have xview  and  yview  com‐
45              mands that take exactly the additional arguments appended by the
46              scrollbar as described in SCROLLING COMMANDS below.
47
48       Command-Line Name:-elementborderwidth
49       Database Name:  elementBorderWidth
50       Database Class: BorderWidth
51
52              Specifies the width of borders drawn around  the  internal  ele‐
53              ments  of  the  scrollbar  (the two arrows and the slider).  The
54              value may have any of the forms acceptable to Tk_GetPixels.   If
55              this  value  is  less  than  zero, the value of the -borderwidth
56              option is used in its place.
57
58       Command-Line Name:-width
59       Database Name:  width
60       Database Class: Width
61
62              Specifies the desired narrow dimension of the scrollbar  window,
63              not  including 3-D border, if any.  For vertical scrollbars this
64              will be the width and for horizontal scrollbars this will be the
65              height.   The  value  may  have  any  of the forms acceptable to
66              Tk_GetPixels.
67______________________________________________________________________________
68

DESCRIPTION

70       The scrollbar command creates a new window (given by the pathName argu‐
71       ment)  and  makes  it  into  a  scrollbar  widget.  Additional options,
72       described above, may be specified on the command line or in the  option
73       database to configure aspects of the scrollbar such as its colors, ori‐
74       entation, and relief.  The scrollbar command returns its pathName argu‐
75       ment.  At the time this command is invoked, there must not exist a win‐
76       dow named pathName, but pathName's parent must exist.
77
78       A scrollbar is a widget that displays two arrows, one at  each  end  of
79       the scrollbar, and a slider in the middle portion of the scrollbar.  It
80       provides information about what is visible in an associated window that
81       displays  a  document  of  some  sort (such as a file being edited or a
82       drawing).  The position and size of the slider indicate  which  portion
83       of  the  document is visible in the associated window.  For example, if
84       the slider in a vertical scrollbar covers the top  third  of  the  area
85       between  the  two  arrows, it means that the associated window displays
86       the top third of its document.
87
88       Scrollbars can be used to adjust the view in the associated  window  by
89       clicking  or  dragging  with the mouse.  See the BINDINGS section below
90       for details.
91

ELEMENTS

93       A scrollbar displays five elements, which are referred to in the widget
94       commands for the scrollbar:
95
96       arrow1    The top or left arrow in the scrollbar.
97
98       trough1   The region between the slider and arrow1.
99
100       slider    The  rectangle  that indicates what is visible in the associ‐
101                 ated widget.
102
103       trough2   The region between the slider and arrow2.
104
105       arrow2    The bottom or right arrow in the scrollbar.
106

WIDGET COMMAND

108       The scrollbar command creates a new Tcl command whose name is pathName.
109       This  command  may  be used to invoke various operations on the widget.
110       It has the following general form:
111              pathName option ?arg arg ...?
112       Option and the args determine the exact behavior of the  command.   The
113       following commands are possible for scrollbar widgets:
114
115       pathName activate ?element?
116              Marks  the  element indicated by element as active, which causes
117              it to be displayed as specified  by  the  -activebackground  and
118              -activerelief  options.   The  only element values understood by
119              this command are arrow1, slider, or arrow2.  If any other  value
120              is  specified  then  no element of the scrollbar will be active.
121              If element is not specified, the command returns the name of the
122              element  that is currently active, or an empty string if no ele‐
123              ment is active.
124
125       pathName cget option
126              Returns the current value of the configuration option  given  by
127              option.   Option  may  have  any  of  the values accepted by the
128              scrollbar command.
129
130       pathName configure ?option? ?value option value ...?
131              Query or modify the configuration options of the widget.  If  no
132              option is specified, returns a list describing all of the avail‐
133              able options for pathName (see Tk_ConfigureInfo for  information
134              on  the  format  of  this list).  If option is specified with no
135              value, then the command returns a list describing the one  named
136              option (this list will be identical to the corresponding sublist
137              of the value returned if no option is  specified).   If  one  or
138              more option-value pairs are specified, then the command modifies
139              the given widget option(s) to have the given value(s);  in  this
140              case  the  command returns an empty string.  Option may have any
141              of the values accepted by the scrollbar command.
142
143       pathName delta deltaX deltaY
144              Returns a real number indicating the fractional  change  in  the
145              scrollbar  setting  that corresponds to a given change in slider
146              position.  For example, if  the  scrollbar  is  horizontal,  the
147              result  indicates  how much the scrollbar setting must change to
148              move the slider deltaX pixels to the right (deltaY is ignored in
149              this  case).  If the scrollbar is vertical, the result indicates
150              how much the scrollbar setting must change to  move  the  slider
151              deltaY pixels down.  The arguments and the result may be zero or
152              negative.
153
154       pathName fraction x y
155              Returns a real number between 0 and 1 indicating where the point
156              given  by x and y lies in the trough area of the scrollbar.  The
157              value 0 corresponds to the top or left of the trough, the  value
158              1  corresponds  to  the  bottom or right, 0.5 corresponds to the
159              middle, and so on.  X and y must be pixel  coordinates  relative
160              to  the  scrollbar  widget.  If x and y refer to a point outside
161              the trough, the closest point in the trough is used.
162
163       pathName get
164              Returns the scrollbar settings in the form of a list whose  ele‐
165              ments are the arguments to the most recent set widget command.
166
167       pathName identify x y
168              Returns the name of the element under the point given by x and y
169              (such as arrow1), or an empty string if the point does  not  lie
170              in  any element of the scrollbar.  X and y must be pixel coordi‐
171              nates relative to the scrollbar widget.
172
173       pathName set first last
174              This command is invoked by the scrollbar's associated widget  to
175              tell  the  scrollbar  about the current view in the widget.  The
176              command takes two arguments, each of which is  a  real  fraction
177              between  0 and 1.  The fractions describe the range of the docu‐
178              ment that is visible in the associated widget.  For example,  if
179              first  is  0.2  and last is 0.4, it means that the first part of
180              the document visible in the window is 20% of the way through the
181              document, and the last visible part is 40% of the way through.
182

SCROLLING COMMANDS

184       When the user interacts with the scrollbar, for example by dragging the
185       slider, the scrollbar notifies  the  associated  widget  that  it  must
186       change  its view.  The scrollbar makes the notification by evaluating a
187       Tcl command generated from the scrollbar's -command option.   The  com‐
188       mand  may take any of the following forms.  In each case, prefix is the
189       contents of  the  -command  option,  which  usually  has  a  form  like
190.t”yview
191
192       prefix moveto fraction
193              Fraction  is  a  real number between 0 and 1.  The widget should
194              adjust its view so that the point given by fraction  appears  at
195              the  beginning of the widget.  If fraction is 0 it refers to the
196              beginning of the document.  1.0 refers to the end of  the  docu‐
197              ment,  0.333  refers to a point one-third of the way through the
198              document, and so on.
199
200       prefix scroll number units
201              The widget should adjust its view by number  units.   The  units
202              are  defined in whatever way makes sense for the widget, such as
203              characters or lines in a text widget.  Number is either 1, which
204              means  one unit should scroll off the top or left of the window,
205              or -1, which means that one unit should scroll off the bottom or
206              right of the window.
207
208       prefix scroll number pages
209              The  widget should adjust its view by number pages.  It is up to
210              the widget to define the meaning of a  page;   typically  it  is
211              slightly  less  than what fits in the window, so that there is a
212              slight overlap between the old and new views.  Number is  either
213              1, which means the next page should become visible, or -1, which
214              means that the previous page should become visible.
215

OLD COMMAND SYNTAX

217       In versions of Tk before 4.0, the set and get widget  commands  used  a
218       different  form.  This form is still supported for backward compatibil‐
219       ity, but it is deprecated.  In the old command syntax, the  set  widget
220       command has the following form:
221
222       pathName set totalUnits windowUnits firstUnit lastUnit
223              In  this  form the arguments are all integers.  TotalUnits gives
224              the total size of the object being displayed in  the  associated
225              widget.   The meaning of one unit depends on the associated wid‐
226              get;  for example, in a text editor widget  units  might  corre‐
227              spond  to lines of text.  WindowUnits indicates the total number
228              of units that can fit in the  associated  window  at  one  time.
229              FirstUnit  and  lastUnit  give the indices of the first and last
230              units currently visible in the associated  window  (zero  corre‐
231              sponds to the first unit of the object).
232
233       Under  the  old  syntax  the  get widget command returns a list of four
234       integers, consisting of the  totalUnits,  windowUnits,  firstUnit,  and
235       lastUnit values from the last set widget command.
236
237       The  commands  generated  by scrollbars also have a different form when
238       the old syntax is being used:
239
240       prefix unit
241              Unit is an integer that indicates what should appear at the  top
242              or  left  of  the  associated  widget's window.  It has the same
243              meaning as the firstUnit and lastUnit arguments to the set  wid‐
244              get command.
245
246       The most recent set widget command determines whether or not to use the
247       old syntax.  If it is given two real arguments then the new syntax will
248       be  used  in the future, and if it is given four integer arguments then
249       the old syntax will be used.
250

BINDINGS

252       Tk automatically creates class bindings for scrollbars that  give  them
253       the  following default behavior.  If the behavior is different for ver‐
254       tical and horizontal scrollbars, the horizontal behavior  is  described
255       in parentheses.
256
257       [1]    Pressing  button 1 over arrow1 causes the view in the associated
258              widget to shift up (left) by  one  unit  so  that  the  document
259              appears  to  move  down (right) one unit.  If the button is held
260              down, the action auto-repeats.
261
262       [2]    Pressing button 1 over trough1 causes the view in the associated
263              widget  to shift up (left) by one screenful so that the document
264              appears to move down (right) one screenful.  If  the  button  is
265              held down, the action auto-repeats.
266
267       [3]    Pressing  button  1 over the slider and dragging causes the view
268              to drag with the slider.  If the jump option is true,  then  the
269              view  does not drag along with the slider;  it changes only when
270              the mouse button is released.
271
272       [4]    Pressing button 1 over trough2 causes the view in the associated
273              widget  to shift down (right) by one screenful so that the docu‐
274              ment appears to move up (left) one screenful.  If the button  is
275              held down, the action auto-repeats.
276
277       [5]    Pressing  button 1 over arrow2 causes the view in the associated
278              widget to shift down (right) by one unit so  that  the  document
279              appears to move up (left) one unit.  If the button is held down,
280              the action auto-repeats.
281
282       [6]    If button 2 is pressed over the trough or the  slider,  it  sets
283              the  view  to  correspond  to  the mouse position;  dragging the
284              mouse with button 2 down causes the view to drag with the mouse.
285              If  button  2  is  pressed over one of the arrows, it causes the
286              same behavior as pressing button 1.
287
288       [7]    If button 1 is pressed with the Control key down,  then  if  the
289              mouse is over arrow1 or trough1 the view changes to the very top
290              (left) of the document;  if the mouse is over arrow2 or  trough2
291              the view changes to the very bottom (right) of the document;  if
292              the mouse is anywhere else then the button press has no effect.
293
294       [8]    In vertical scrollbars the Up and Down keys have the same behav‐
295              ior  as  mouse  clicks over arrow1 and arrow2, respectively.  In
296              horizontal scrollbars these keys have no effect.
297
298       [9]    In vertical scrollbars Control-Up and Control-Down have the same
299              behavior as mouse clicks over trough1 and trough2, respectively.
300              In horizontal scrollbars these keys have no effect.
301
302       [10]   In horizontal scrollbars the Up and  Down  keys  have  the  same
303              behavior  as  mouse clicks over arrow1 and arrow2, respectively.
304              In vertical scrollbars these keys have no effect.
305
306       [11]   In horizontal scrollbars Control-Up and  Control-Down  have  the
307              same  behavior as mouse clicks over trough1 and trough2, respec‐
308              tively.  In vertical scrollbars these keys have no effect.
309
310       [12]   The Prior and Next keys have the same behavior as  mouse  clicks
311              over trough1 and trough2, respectively.
312
313       [13]   The Home key adjusts the view to the top (left edge) of the doc‐
314              ument.
315
316       [14]   The End key adjusts the view to the bottom (right edge)  of  the
317              document.
318

EXAMPLE

320       Create a window with a scrollable text widget:
321              toplevel .tl
322              text .tl.t -yscrollcommand {.tl.s set}
323              scrollbar .tl.s -command {.tl.t yview}
324              grid .tl.t .tl.s -sticky nsew
325              grid columnconfigure .tl 0 -weight 1
326              grid rowconfigure .tl 0 -weight 1
327

SEE ALSO

329       ttk:scrollbar(n)
330

KEYWORDS

332       scrollbar, widget
333
334
335
336Tk                                    4.1                         scrollbar(n)
Impressum