Provided by: tk8.4-doc_8.4.19-4_all bug

NAME

       scale - Create and manipulate scale widgets

SYNOPSIS

       scale pathName ?options?

STANDARD OPTIONS

       -activebackground     -foreground          -relief
       -background           -highlightbackground -repeatdelay
       -borderwidth          -highlightcolor      -repeatinterval
       -cursor               -highlightthickness  -takefocus
       -font                 -orient              -troughcolor

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

WIDGET-SPECIFIC OPTIONS

       [-bigincrement bigIncrement] Some interactions with the scale cause its value to change by
       ``large'' increments;  this option  specifies  the  size  of  the  large  increments.   If
       specified   as  0,  the  large  increments  default  to  1/10  the  range  of  the  scale.
       [-command 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  indicating  the  new  value  of  the  scale.
       [-digits 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.  [-from from] A real  value  corresponding  to  the
       left  or  top  end  of  the  scale.  [-label 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.   [-length 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.   [-resolution 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).  [-showvalue showValue] Specifies a
       boolean value indicating whether or not the current value of the scale is to be displayed.
       [-sliderlength sliderLength]  Specifies  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.  [-sliderrelief sliderRelief] Specifies the relief to use when
       drawing the slider, such as raised or  sunken.   [-state state]  Specifies  one  of  three
       states  for  the  scale:   normal, active, or disabled.  If the scale is disabled 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.
       [-tickinterval 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.  [-to 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.
       [-variable variable] Specifies the name of  a  global  variable  to  link  to  the  scale.
       Whenever  the  value of the variable changes, the scale will update to reflect this value.
       Whenever the scale is manipulated interactively, the variable will be modified to  reflect
       the  scale's  new  value.   [-width 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 pathName argument) and makes it into
       a scale widget.  Additional 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.

       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 particular 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 pathName (see
              Tk_ConfigureInfo  for  information  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 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 scale command.

       pathName coords ?value?
              Returns  a  list  whose elements are the x and y coordinates 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 button 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 Control key down, the slider moves
              all the way to the end of its range, in the direction towards the mouse cursor.

       [4]    If button 2 is pressed, the scale's value is set to the  mouse  position.   If  the
              mouse is dragged with button 2 down, the scale's value changes with the drag.

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

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

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

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

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

       [10]   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