NAME
       scrollbar - Create and manipulate scrollbar widgets

SYNOPSIS
       scrollbar pathName ?options?

STANDARD OPTIONS
       -activebackground     -highlightcolor      -repeatdelay
       -background           -highlightthickness  -repeatinterval
       -borderwidth          -jump                -takefocus
       -cursor               -orient              -troughcolor
       -highlightbackground  -relief

       See  the  options manual entry for details on the standard
       options.

WIDGET-SPECIFIC OPTIONS
       Command-Line Name:-activerelief
       Database Name:  activeRelief
       Database Class: ActiveRelief

              Specifies the relief to  use  when  displaying  the
              element  that  is  active,  if any.  Elements other
              than the active element are always displayed with a
              raised relief.

       Command-Line Name:-command
       Database Name:  command
       Database Class: Command

              Specifies  the prefix of a Tcl command to invoke to
              change the view in the widget associated  with  the
              scrollbar.   When  a user requests a view change by
              manipulating  the  scrollbar,  a  Tcl  command   is
              invoked.   The  actual  command  consists  of  this
              option  followed  by  additional   information   as
              described  later.   This option almost always has a
              value such as .t xview or .t yview,  consisting  of
              the  name  of  a  widget  and  either xview (if the
              scrollbar is for  horizontal  scrolling)  or  yview
              (for  vertical  scrolling).  All scrollable widgets
              have xview and yview commands that take exactly the
              additional  arguments  appended by the scrollbar as
              described in SCROLLING COMMANDS below.

       Command-Line Name:-elementborderwidth
       Database Name:  elementBorderWidth
       Database Class: BorderWidth

              Specifies the width of  borders  drawn  around  the
              internal  elements of the scrollbar (the two arrows
              and the slider).  The value may  have  any  of  the
              forms acceptable to Tk_GetPixels.  If this value is
              less than zero, the value of the borderWidth option
              is used in its place.

       Command-Line Name:-width
       Database Name:  width
       Database Class: Width

              Specifies  the  desired  narrow  dimension  of  the
              scrollbar window, not including 3-D border, if any.
              For  vertical scrollbars this will be the width and
              for horizontal scrollbars this will be the  height.
              The  value  may have any of the forms acceptable to
              Tk_GetPixels.


DESCRIPTION
       The scrollbar command creates a new window (given  by  the
       pathName  argument)  and makes it into a scrollbar widget.
       Additional options, described above, may be  specified  on
       the  command  line  or in the option database to configure
       aspects of the scrollbar such as its colors,  orientation,
       and  relief.   The  scrollbar command returns its pathName
       argument.  At the time this command is invoked, there must
       not  exist  a window named pathName, but pathName's parent
       must exist.

       A scrollbar is a widget that displays two arrows,  one  at
       each end of the scrollbar, and a slider in the middle por-
       tion of the scrollbar.  It provides information about what
       is  visible in an associated window that displays an docu-
       ment of some sort (such as a file being edited or a  draw-
       ing).   The position and size of the slider indicate which
       portion of the document is visible in the associated  win-
       dow.   For  example, if the slider in a vertical scrollbar
       covers the top third of the area between the  two  arrows,
       it means that the associated window displays the top third
       of its document.

       Scrollbars can be used to adjust the view in  the  associ-
       ated  window  by clicking or dragging with the mouse.  See
       the BINDINGS section below for details.


ELEMENTS
       A scrollbar displays five elements, which are referred  to
       in the widget commands for the scrollbar:

       arrow1    The top or left arrow in the scrollbar.

       trough1   The region between the slider and arrow1.

       slider    The  rectangle that indicates what is visible in
                 the associated widget.

       trough2   The region between the slider and arrow2.
       arrow2    The bottom or right arrow in the scrollbar.


WIDGET COMMAND
       The scrollbar command creates a new Tcl command whose name
       is  pathName.   This command may be used to invoke various
       operations on the widget.  It has  the  following  general
       form:
              pathName option ?arg arg ...?
       Option  and  the  args determine the exact behavior of the
       command.  The following commands are possible for  scroll-
       bar widgets:

       pathName activate ?element?
              Marks  the  element indicated by element as active,
              which causes it to be displayed as specified by the
              activeBackground  and  activeRelief  options.   The
              only element values understood by this command  are
              arrow1,  slider,  or arrow2.  If any other value is
              specified then no element of the scrollbar will  be
              active.   If  element is not specified, the command
              returns the name of the element that  is  currently
              active, or an empty string if no element is active.

       pathName cget option
              Returns the  current  value  of  the  configuration
              option given by option.  Option may have any of the
              values accepted by the scrollbar command.

       pathName configure ?option? ?value option value ...?
              Query or modify the configuration  options  of  the
              widget.   If no option is specified, returns a list
              describing all of the available options  for  path-
              Name  (see  Tk_ConfigureInfo for information on the
              format of this list).  If option is specified  with
              no  value, then the command returns a list describ-
              ing the one named option (this list will be identi-
              cal  to  the  corresponding  sublist  of  the value
              returned if no option is  specified).   If  one  or
              more  option-value  pairs  are  specified, then the
              command modifies the given widget option(s) to have
              the  given  value(s);   in  this  case  the command
              returns an empty string.  Option may  have  any  of
              the values accepted by the scrollbar command.

       pathName delta deltaX deltaY
              Returns  a  real  number  indicating the fractional
              change in the scrollbar setting that corresponds to
              a given change in slider position.  For example, if
              the scrollbar is horizontal, the  result  indicates
              how  much the scrollbar setting must change to move
              the slider deltaX pixels to the  right  (deltaY  is
              ignored  in this case).  If the scrollbar is verti-
              cal, the result indicates how  much  the  scrollbar
              setting  must change to move the slider deltaY pix-
              els down.  The arguments and the result may be zero
              or negative.

       pathName fraction x y
              Returns  a  real  number between 0 and 1 indicating
              where the point given by x and y lies in the trough
              area  of the scrollbar.  The value 0 corresponds to
              the top or left of the trough, the value  1  corre-
              sponds  to  the bottom or right, 0.5 corresponds to
              the middle, and so on.  X and y must be pixel coor-
              dinates relative to the scrollbar widget.  If x and
              y refer to a point outside the trough, the  closest
              point in the trough is used.

       pathName get
              Returns  the  scrollbar  settings  in the form of a
              list whose elements are the arguments to  the  most
              recent set widget command.

       pathName identify x y
              Returns  the  name  of  the element under the point
              given by x and y (such  as  arrow1),  or  an  empty
              string  if the point does not lie in any element of
              the scrollbar.  X and y must be  pixel  coordinates
              relative to the scrollbar widget.

       pathName set first last
              This  command is invoked by the scrollbar's associ-
              ated widget to tell the scrollbar about the current
              view  in  the  widget.  The command takes two argu-
              ments, each of which is a real fraction  between  0
              and  1.   The  fractions  describe the range of the
              document that is visible in the associated  widget.
              For  example,  if  first is 0.2 and last is 0.4, it
              means that the first part of the  document  visible
              in  the  window is 20% of the way through the docu-
              ment, and the last visible part is 40% of  the  way
              through.


SCROLLING COMMANDS
       When the user interacts with the scrollbar, for example by
       dragging the slider, the scrollbar notifies the associated
       widget  that it must change its view.  The scrollbar makes
       the notification by evaluating  a  Tcl  command  generated
       from  the  scrollbar's  -command  option.  The command may
       take any of the following forms.  In each case, prefix  is
       the  contents  of the -command option, which usually has a
       form like .t yview

       prefix moveto fraction
              Fraction is a real number between  0  and  1.   The
              widget  should  adjust  its  view so that the point
              given by fraction appears at the beginning  of  the
              widget.   If  fraction is 0 it refers to the begin-
              ning of the document.  1.0 refers to the end of the
              document,  0.333 refers to a point one-third of the
              way through the document, and so on.

       prefix scroll number units
              The widget should adjust its view by number  units.
              The  units  are defined in whatever way makes sense
              for the widget, such as characters or  lines  in  a
              text  widget.   Number is either 1, which means one
              unit should scroll off the top or left of the  win-
              dow, or -1, which means that one unit should scroll
              off the bottom or right of the window.

       prefix scroll number pages
              The widget should adjust its view by number  pages.
              It  is  up to the widget to define the meaning of a
              page;  typically it is slightly less than what fits
              in  the  window,  so that there is a slight overlap
              between the old and new views.  Number is either 1,
              which means the next page should become visible, or
              -1, which  means  that  the  previous  page  should
              become visible.


OLD COMMAND SYNTAX
       In  versions of Tk before 4.0, the set and get widget com-
       mands used a different form.  This form is still supported
       for  backward compatibility, but it is deprecated.  In the
       old command syntax, the set widget command has the follow-
       ing form:

       pathName set totalUnits windowUnits firstUnit lastUnit
              In  this  form  the  arguments  are  all  integers.
              TotalUnits gives the total size of the object being
              displayed in the associated widget.  The meaning of
              one unit depends on  the  associated  widget;   for
              example, in a text editor widget units might corre-
              spond to lines of text.  WindowUnits indicates  the
              total  number  of units that can fit in the associ-
              ated window at one time.   FirstUnit  and  lastUnit
              give  the  indices of the first and last units cur-
              rently visible in the associated window (zero  cor-
              responds to the first unit of the object).

       Under the old syntax the get widget command returns a list
       of four integers, consisting of the  totalUnits,  windowU-
       nits,  firstUnit,  and  lastUnit  values from the last set
       widget command.

       The commands generated by scrollbars also have a different
       form when the old syntax is being used:
       prefix unit
              Unit  is  an  integer  that  indicates  what should
              appear at the top or left of  the  associated  wid-
              get's  window.   It  has  the  same  meaning as the
              firstUnit and lastUnit arguments to the set  widget
              command.

       The  most  recent set widget command determines whether or
       not to use the old syntax.  If it is given two real  argu-
       ments  then the new syntax will be used in the future, and
       if it is given four integer arguments then the old  syntax
       will be used.


BINDINGS
       Tk  automatically  creates  class  bindings for scrollbars
       that give them the following  default  behavior.   If  the
       behavior  is different for vertical and horizontal scroll-
       bars, the horizontal behavior is described in parentheses.


       [1]    Pressing  button  1  over arrow1 causes the view in
              the associated widget to shift  up  (left)  by  one
              unit  so  that  the  document  appears to move down
              (right) one unit.  If the button is held down,  the
              action auto-repeats.

       [2]    Pressing  button  1 over trough1 causes the view in
              the associated widget to shift  up  (left)  by  one
              screenful so that the document appears to move down
              (right) one screenful.  If the button is held down,
              the action auto-repeats.

       [3]    Pressing  button  1  over  the  slider and dragging
              causes the view to drag with the  slider.   If  the
              jump  option  is  true,  then the view doesn't drag
              along with the slider;  it changes  only  when  the
              mouse button is released.

       [4]    Pressing  button  1 over trough2 causes the view in
              the associated widget to shift down (right) by  one
              screenful  so  that the document appears to move up
              (left) one screenful.  If the button is held  down,
              the action auto-repeats.

       [5]    Pressing  button  1  over arrow2 causes the view in
              the associated widget to shift down (right) by  one
              unit so that the document appears to move up (left)
              one unit.  If the button is held down,  the  action
              auto-repeats.

       [6]    If  button  2  is  pressed  over  the trough or the
              slider, it sets the view to correspond to the mouse
              position;   dragging  the  mouse with button 2 down
              causes the view to drag with the mouse.  If  button
              2  is pressed over one of the arrows, it causes the
              same behavior as pressing button 1.

       [7]    If button 1 is pressed with the Control  key  down,
              then  if  the  mouse  is over arrow1 or trough1 the
              view changes to the very top (left)  of  the  docu-
              ment;   if  the mouse is over arrow2 or trough2 the
              view changes to the very bottom (right) of the doc-
              ument;  if the mouse is anywhere else then the but-
              ton press has no effect.

       [8]    In vertical scrollbars the Up and  Down  keys  have
              the  same  behavior as mouse clicks over arrow1 and
              arrow2,  respectively.   In  horizontal  scrollbars
              these keys have no effect.

       [9]    In  vertical scrollbars Control-Up and Control-Down
              have the same behavior as mouse clicks over trough1
              and  trough2,  respectively.  In horizontal scroll-
              bars these keys have no effect.

       [10]   In horizontal scrollbars the Up and Down keys  have
              the  same  behavior as mouse clicks over arrow1 and
              arrow2, respectively.  In vertical scrollbars these
              keys have no effect.

       [11]   In  horizontal  scrollbars  Control-Up and Control-
              Down have the same behavior as  mouse  clicks  over
              trough1  and  trough2,  respectively.   In vertical
              scrollbars these keys have no effect.

       [12]   The Prior and Next keys have the same  behavior  as
              mouse  clicks  over  trough1  and  trough2, respec-
              tively.

       [13]   The Home key adjusts the  view  to  the  top  (left
              edge) of the document.

       [14]   The  End  key adjusts the view to the bottom (right
              edge) of the document.


KEYWORDS
       scrollbar, widget
