SCROLLBAR(9)                                         SCROLLBAR(9)

     NAME
          scrollbar - Create and manipulate scrollbar widgets

     SYNOPSIS
          scrollbar pathName ?options?

     STANDARD OPTIONS
          -activebackground -borderwidth      -orient
          -background       -jump             -relief

     WIDGET-SPECIFIC OPTIONS
          -activerelief relief
               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 command
               Specifies the prefix of a Tk 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 Tk 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 addi-
               tional arguments appended by the scrollbar as described
               in SCROLLING COMMANDS below.

          -height dist
               Specifies a desired height for the scrollbar.  If this
               option isn't specified, a suitable default height is
               chosen.

          -width dist
               Specifies a desired width for the scrollbar.  If this
               option isn't specified, a suitable default width is
               chosen.

     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 to configure aspects of the scrollbar such as
          its colours, 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.

     Page 1                       Plan 9             (printed 3/28/24)

     SCROLLBAR(9)                                         SCROLLBAR(9)

          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 a document
          of some sort (such as a file being edited or a drawing).
          The position and size of the slider indicate which portion
          of the document is visible in the associated window.  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 docu-
          ment.

          Scrollbars can be used to adjust the view in the associated
          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 Tk command whose name is
          pathName.  This command may be used to invoke various opera-
          tions on the widget.  It has the following general form:
               pathName option ?arg arg ...?
          Option and the args determine the exact behaviour of the
          command.  The following commands are possible for scrollbar
          widgets:

          pathName activate ?element?
               Marks the element indicated by element as active, which
               causes it to be displayed as specified by the active-
               background option.  The only element values understood
               by this command are arrow1, slider, or arrow2.  If any
               other value is specified then no element of the scroll-
               bar will be active.  If element is not specified, the
               command returns the name of the element that is cur-
               rently active, or an empty string if no element is
               active.

     Page 2                       Plan 9             (printed 3/28/24)

     SCROLLBAR(9)                                         SCROLLBAR(9)

          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 wid-
               get.  If no option is specified, returns a list of all
               of the available options for pathName.  If one or more
               option-value pairs are specified, then the command mod-
               ifies 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 scroll-
               bar 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 vertical, the result indicates how
               much the scrollbar setting must change to move the
               slider deltaY pixels 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 corresponds to the bot-
               tom or right, 0.5 corresponds to the middle, and so on.
               X and y must be pixel coordinates 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 scroll-
               bar widget.

          pathName set first last
               This command is invoked by the scrollbar's associated
               widget to tell the scrollbar about the current view in

     Page 3                       Plan 9             (printed 3/28/24)

     SCROLLBAR(9)                                         SCROLLBAR(9)

               the widget.  The command takes two arguments, each of
               which is a real fraction between 0 and 1.  The frac-
               tions describe the range of the document that is visi-
               ble 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 document, 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 Tk command generated from
          the scrollbar's -command option.  The command may take any
          of the following forms.  In each case, prefix is the con-
          tents 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 frac-
               tion appears at the beginning of the widget.  If frac-
               tion is 0 it refers to the beginning 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 window, 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.

     BINDINGS
          Tk automatically creates bindings for scrollbars that give
          them the following default behaviour.  If the behaviour is
          different for vertical and horizontal scrollbars, the

     Page 4                       Plan 9             (printed 3/28/24)

     SCROLLBAR(9)                                         SCROLLBAR(9)

          horizontal behaviour 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.

          [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 screen-
               ful so that the document appears to move up (left) one
               screenful.

          [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 behaviour as
               pressing button 1.

     SEE ALSO
          options(9), types(9)

     Page 5                       Plan 9             (printed 3/28/24)