tk4.2 User Commands - scale






NAME

     scale - Create and manipulate scale widgets


SYNOPSIS

     scale pathName ?options?


STANDARD OPTIONS

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

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


WIDGET-SPECIFIC OPTIONS

     Command-Line Name:-bigincrement
     Database Name:  bigIncrement
     Database Class: 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-Line Name:-command
     Database Name:  command
     Database Class: Command

          Specifies the prefix of a Tcl command to  invoke  when-
          ever 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.

     Command-Line Name:-digits
     Database Name:  digits
     Database Class: 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.

     Command-Line Name:-from
     Database Name:  from
     Database Class: From
          A real value corresponding to the left or  top  end  of
          the scale.

     Command-Line Name:-label
     Database Name:  label
     Database Class: 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.

     Command-Line Name:-length
     Database Name:  length
     Database Class: 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.

     Command-Line Name:-resolution
     Database Name:  resolution
     Database Class: 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).

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

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

     Command-Line Name:-sliderlength
     Database Name:  sliderLength
     Database Class: 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.


     Command-Line Name:-sliderrelief
     Database Name:  sliderRelief
     Database Class: SliderRelief

          Specifies the relief to use when  drawing  the  slider,
          such as raised or sunken.

     Command-Line Name:-state
     Database Name:  state
     Database Class: 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.

     Command-Line Name:-tickinterval
     Database Name:  tickInterval
     Database Class: 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.

     Command-Line Name:-to
     Database Name:  to
     Database Class: 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.

     Command-Line Name:-variable
     Database Name:  variable
     Database Class: 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.

     Command-Line Name:-width
     Database Name:  width
     Database Class: 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.  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  addi-
     tion, 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 opera-
     tions on the widget.  It has the following general form:
          pathName option ?arg arg ...?
     Option and the args determine the exact behavior of the com-
     mand.   The  following commands are possible for scale widg-
     ets:

     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  correspond-
          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 values accepted by the scale command.

     pathName coords ?value?
          Returns a list whose elements are the x and  y  coordi-
          nates  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  bind-
     ings for individual widgets or by redefining the class bind-
     ings.



KEYWORDS

     scale, slider, trough, widget