NAME
       scrollbar - Create and manipulate scrollbar widgets

SYNOPSIS
       scrollbar pathName ?options?

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

       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.

       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 unit
              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 page
              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
              document;  if the mouse is over arrow2  or  trough2
              the  view changes to the very bottom (right) of the
              document;  if the mouse is anywhere else  then  the
              button 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
