Mac Developer Library Developer
Search

 

This manual page is for Mac OS X version 10.9

If you are running a different version of Mac OS X, view the documentation locally:

  • In Terminal, using the man(1) command

Reading manual pages

Manual pages are intended as a quick reference for people who already understand a technology.

  • To learn how the manual is organized or to learn about command syntax, read the manual page for manpages(5).

  • For more information about this technology, look for other documentation in the Apple Developer Library.

  • For general information about writing shell scripts, read Shell Scripting Primer.



scrollbar(n)                                Tk Built-In Commands                                scrollbar(n)



____________________________________________________________________________________________________________

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  infor-mation information
              mation  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 portion 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 posi-tion position
       tion and size of the slider indicate which portion of the document is visible in the associated  win-dow. window.
       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 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 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 scrollbar 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 pathName (see Tk_ConfigureInfo for informa-tion information
              tion on the format of this list).  If option is specified with  no  value,  then  the  command
              returns a list describing the one named option (this list will be identical to the correspond-ing corresponding
              ing 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  val-ues values
              ues accepted by the scrollbar command.

       pathName delta deltaX deltaY
              Returns  a  real  number indicating the fractional change in the scrollbar setting that corre-sponds corresponds
              sponds 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 vertical, the result indi-cates indicates
              cates  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 bottom 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 out-side outside
              side 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 coor-dinates coordinates
              dinates relative to the scrollbar widget.

       pathName set first last
              This  command  is invoked by the scrollbar's associated widget to tell the scrollbar about the
              current view in the widget.  The command takes two arguments, 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 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  noti-fies notifies
       fies  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 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 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 window, 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 mean-ing meaning
              ing 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 commands 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 following 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 correspond to lines of text.  Win-dowUnits WindowUnits
              dowUnits indicates the total number of units that can fit in  the  associated  window  at  one
              time.   FirstUnit  and lastUnit give the indices of the first and last units currently visible
              in the associated window (zero corresponds 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, windowUnits, 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 widget's
              get's window.  It has the same meaning as the firstUnit and lastUnit arguments to the set wid-get widget
              get command.

       The  most  recent set widget command determines whether or not to use the old syntax.  If it is given
       two real arguments 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  scrollbars,  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 does not 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 scrollbars 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,
              respectively.

       [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.

EXAMPLE
       Create a window with a scrollable text widget:
              toplevel .tl
              text .tl.t -yscrollcommand {.tl.s set}
              scrollbar .tl.s -command {.tl.t yview}
              grid .tl.t .tl.s -sticky nsew
              grid columnconfigure .tl 0 -weight 1
              grid rowconfigure .tl 0 -weight 1

SEE ALSO
       ttk:scrollbar(n)

KEYWORDS
       scrollbar, widget



Tk                                                   4.1                                        scrollbar(n)

Reporting Problems

The way to report a problem with this manual page depends on the type of problem:

Content errors
Report errors in the content of this documentation to the Tk project.
Bug reports
Report bugs in the functionality of the described tool or API to Apple through Bug Reporter and to the Tk project through their bug reporting page.
Formatting problems
Report formatting mistakes in the online version of these pages with the feedback links below.

Feedback