


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


NAME
       scale - Create and manipulate scale widgets

SYNOPSIS
       scale pathName ?options?

STANDARD OPTIONS
       activeBackground               font            highlightThicknessrepeatInterval
       background      foreground     orient          takeFocus
       borderWidth     highlightBackground            relieftroughColor
       cursor          highlightColor repeatDelay

       See  the ``options'' manual entry for details on the stan-
       dard options.

WIDGET-SPECIFIC OPTIONS
       Name:           bigIncrement
       Class:          BigIncrement
       Command-Line Switch:-bigincrement

              Some interactions with the scale cause its value to
              change by ``large'' increments;  this option speci-
              fies the size of the large increments.   If  speci-
              fied as 0, the large increments default to 1/10 the
              range of the scale.

       Name:           command
       Class:          Command
       Command-Line Switch:-command

              Specifies the prefix of a  Tcl  command  to  invoke
              whenever  the scale's value is changed via a widget
              command.   The  actual  command  consists  of  this
              option  followed by a space and a real number indi-
              cating the new value of the scale.

       Name:           digits
       Class:          Digits
       Command-Line Switch:-digits

              An integer specifying how many  significant  digits
              should be retained when converting the value of the
              scale to a string.  If the number is less  than  or
              equal  to  zero,  then the scale picks the smallest
              value that guarantees that  every  possible  slider
              position prints as a different string.

       Name:           from
       Class:          From
       Command-Line Switch:-from

              A  real  value corresponding to the left or top end
              of the scale.




Tk                             4.0                              1





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


       Name:           label
       Class:          Label
       Command-Line Switch:-label

              A string to display as a label for the scale.   For
              vertical  scales the label is displayed just to the
              right of the top end of the scale.  For  horizontal
              scales  the  label is displayed just above the left
              end of the scale.  If the option is specified as an
              empty string, no label is displayed.

       Name:           length
       Class:          Length
       Command-Line Switch:-length

              Specifies  the  desired long dimension of the scale
              in screen units (i.e. any of the  forms  acceptable
              to  Tk_GetPixels).  For vertical scales this is the
              scale's height;  for horizontal scales  it  is  the
              scale's width.

       Name:           resolution
       Class:          Resolution
       Command-Line Switch:-resolution

              A  real  value  specifying  the  resolution for the
              scale.  If this value is greater than zero then the
              scale's  value  will  always  be rounded to an even
              multiple of this value, as will tick marks and  the
              endpoints  of the scale.  If the value is less than
              zero then no rounding occurs.  Defaults to 1 (i.e.,
              the value will be integral).

       Name:           showValue
       Class:          ShowValue
       Command-Line Switch:-showvalue

              Specifies a boolean value indicating whether or not
              the current value of the scale is to be  displayed.

       Name:           sliderLength
       Class:          SliderLength
       Command-Line Switch:-sliderlength

              Specfies the size of the slider, measured in screen
              units along the slider's long dimension.  The value
              may  be specified in any of the forms acceptable to
              Tk_GetPixels.

       Name:           state
       Class:          State
       Command-Line Switch:-state

              Specifies  one  of  three  states  for  the  scale:



Tk                             4.0                              2





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


              normal,  active, or disabled.  If the scale is dis-
              abled then the value may not  be  changed  and  the
              scale  won't activate.  If the scale is active, the
              slider is displayed using the  color  specified  by
              the activeBackground option.

       Name:           tickInterval
       Class:          TickInterval
       Command-Line Switch:-tickinterval

              Must  be  a  real  value.   Determines  the spacing
              between numerical tick marks displayed below or  to
              the  left  of the slider.  If 0, no tick marks will
              be displayed.

       Name:           to
       Class:          To
       Command-Line Switch:-to

              Specifies a real value corresponding to  the  right
              or  bottom  end  of  the  scale.  This value may be
              either less than or greater than the from option.

       Name:           variable
       Class:          Variable
       Command-Line Switch:-variable

              Specifies the name of a global variable to link  to
              the  scale.   Whenever  the  value  of the variable
              changes, the  scale  will  upate  to  reflect  this
              value.   Whenever the scale is manipulated interac-
              tively, the variable will be  modified  to  reflect
              the scale's new value.

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

              Specifies  the  desired  narrow  dimension  of  the
              trough in screen  units  (i.e.  any  of  the  forms
              acceptable  to  Tk_GetPixels).  For vertical scales
              this is the trough's width;  for horizontal  scales
              this is the trough's height.


DESCRIPTION
       The scale command creates a new window (given by the path-
       Name argument) and makes it into a  scale  widget.   Addi-
       tional  options,  described above, may be specified on the
       command line  or  in  the  option  database  to  configure
       aspects  of the scale such as its colors, orientation, and
       relief.  The scale 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.



Tk                             4.0                              3





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


       A scale is a widget that displays a rectangular trough and
       a small slider.  The trough corresponds to a range of real
       values   (determined  by  the  from,  to,  and  resolution
       options), and the position of the slider selects a partic-
       ular  real  value.   The  slider's position (and hence the
       scale's value) may be adjusted with the mouse or  keyboard
       as  described in the BINDINGS section below.  Whenever the
       scale's value is changed, a Tcl command is invoked  (using
       the  command option) to notify other interested widgets of
       the change.  In addition, the value of the  scale  can  be
       linked  to  a Tcl variable (using the variable option), so
       that changes in either are reflected in the other.

       Three annotations may be displayed in a scale  widget:   a
       label  appearing  at the top right of the widget (top left
       for horizontal scales), a number  displayed  just  to  the
       left  of  the slider (just above the slider for horizontal
       scales), and a collection of numerical tick marks just  to
       the  left  of the current value (just below the trough for
       horizontal scales).  Each of these three  annotations  may
       be enabled or disabled using the configuration options.


WIDGET COMMAND
       The  scale 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 scale
       widgets:

       pathName cget option
              Returns the  current  value  of  the  configuration
              option given by option.  Option may have any of the
              values accepted by the scale 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



Tk                             4.0                              4





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


              the values accepted by the scale command.

       pathName coords ?value?
              Returns a list whose elements are the x and y coor-
              dinates of the point along the  centerline  of  the
              trough  that  corresponds  to  value.   If value is
              omitted then the scale's current value is used.

       pathName get ?x y?
              If x and y are omitted, returns the  current  value
              of  the scale.  If x and y are specified, they give
              pixel coordinates within the widget;   the  command
              returns  the scale value corresponding to the given
              pixel.  Only one of x or y is used:  for horizontal
              scales  y  is ignored, and for vertical scales x is
              ignored.

       pathName identify x y
              Returns a string indicating what part of the  scale
              lies  under  the  coordinates  given by x and y.  A
              return value of slider means that the point is over
              the  slider;   trough1 means that the point is over
              the portion of the slider above  or to the left  of
              the  slider;  and  trough2  means that the point is
              over the portion of the  slider  below  or  to  the
              right  of  the slider.  If the point isn't over one
              of these elements, an empty string is returned.

       pathName set value
              This command is invoked to change the current value
              of  the  scale, and hence the position at which the
              slider is displayed.  Value gives the new value for
              the  scale.  The command has no effect if the scale
              is disabled.


BINDINGS
       Tk automatically creates class bindings  for  scales  that
       give  them  the  following  default  behavior.   Where the
       behavior is different for vertical and horizontal  scales,
       the horizontal behavior is described in parentheses.

       [1]    If  button  1 is pressed in the trough, the scale's
              value will be incremented  or  decremented  by  the
              value  of  the resolution option so that the slider
              moves in the direction of the cursor.  If the  but-
              ton is held down, the action auto-repeats.

       [2]    If  button 1 is pressed over the slider, the slider
              can be dragged with the mouse.

       [3]    If button 1 is pressed in the trough with the  Con-
              trol  key down, the slider moves all the way to the
              end of its range,  in  the  direction  towards  the



Tk                             4.0                              5





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


              mouse cursor.

       [4]    The  Up  and Left keys move the slider up (left) by
              the value of the resolution option.

       [5]    The Down  and  Right  keys  move  the  slider  down
              (right) by the value of the resolution option.

       [6]    Control-Up  and  Control-Left  move  the  slider up
              (left) by the value of the bigIncrement option.

       [7]    Control-Down and Control-Right move the slider down
              (right) by the value of the bigIncrement option.

       [8]    Home  moves the slider to the top (left) end of its
              range.

       [9]    End moves the slider to the bottom (right)  end  of
              its range.

       If  the scale is disabled using the state option then none
       of the above bindings have any effect.

       The behavior of scales can  be  changed  by  defining  new
       bindings for individual widgets or by redefining the class
       bindings.


KEYWORDS
       scale, slider, trough, widget
