tk/doc/scale.n

   1 '\"
   2 '\" Copyright (c) 1990-1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 '\" RCS: @(#) $Id$
   9 '\"
  10 .so man.macros
  11 .TH scale n 4.1 Tk "Tk Built-In Commands"
  12 .BS
  13 '\" Note:  do not modify the .SH NAME line immediately below!
  14 .SH NAME
  15 scale \- Create and manipulate scale widgets
  16 .SH SYNOPSIS
  17 \fBscale\fR \fIpathName \fR?\fIoptions\fR?
  18 .SO
  19 \-activebackground      \-foreground    \-relief
  20 \-background    \-highlightbackground   \-repeatdelay
  21 \-borderwidth   \-highlightcolor        \-repeatinterval
  22 \-cursor        \-highlightthickness    \-takefocus
  23 \-font  \-orient        \-troughcolor
  24 .SE
  25 .SH "WIDGET-SPECIFIC OPTIONS"
  26 .OP \-bigincrement bigIncrement BigIncrement
  27 Some interactions with the scale cause its value to change by
  28 ``large'' increments;  this option specifies the size of the
  29 large increments.  If specified as 0, the large increments default
  30 to 1/10 the range of the scale.
  31 .OP \-command command Command
  32 Specifies the prefix of a Tcl command to invoke whenever the scale's
  33 value is changed via a widget command.
  34 The actual command consists
  35 of this option followed by a space and a real number indicating the
  36 new value of the scale.
  37 .OP \-digits digits Digits
  38 An integer specifying how many significant digits should be retained
  39 when converting the value of the scale to a string.
  40 If the number is less than or equal to zero, then the scale picks
  41 the smallest value that guarantees that every possible slider
  42 position prints as a different string.
  43 .OP \-from from From
  44 A real value corresponding to the left or top end of the scale.
  45 .OP \-label label Label
  46 A string to display as a label for the scale.  For
  47 vertical scales the label is displayed just to the right of the
  48 top end of the scale.  For horizontal scales the label is displayed
  49 just above the left end of the scale.  If the option is specified
  50 as an empty string, no label is displayed.
  51 .OP \-length length Length
  52 Specifies the desired long dimension of the scale in screen units
  53 (i.e. any of the forms acceptable to \fBTk_GetPixels\fR).
  54 For vertical scales this is the scale's height;  for horizontal scales
  55 it is the scale's width.
  56 .OP \-resolution resolution Resolution
  57 A real value specifying the resolution for the scale.
  58 If this value is greater than zero then the scale's value will always be
  59 rounded to an even multiple of this value, as will tick marks and
  60 the endpoints of the scale.  If the value is less than zero then no
  61 rounding occurs.  Defaults to 1 (i.e., the value will be integral).
  62 .OP \-showvalue showValue ShowValue
  63 Specifies a boolean value indicating whether or not the current
  64 value of the scale is to be displayed.
  65 .OP \-sliderlength sliderLength SliderLength
  66 Specfies the size of the slider, measured in screen units along the slider's
  67 long dimension.  The value may be specified in any of the forms acceptable
  68 to \fBTk_GetPixels\fR.
  69 .OP \-sliderrelief sliderRelief SliderRelief
  70 Specifies the relief to use when drawing the slider, such as \fBraised\fR
  71 or \fBsunken\fR.
  72 .OP \-state state State
  73 Specifies one of three states for the scale:  \fBnormal\fR,
  74 \fBactive\fR, or \fBdisabled\fR.
  75 If the scale is disabled then the value may not be changed and the scale
  76 won't activate.
  77 If the scale is active, the slider is displayed using the color
  78 specified by the \fBactiveBackground\fR option.
  79 .OP \-tickinterval tickInterval TickInterval
  80 Must be a real value.
  81 Determines the spacing between numerical
  82 tick marks displayed below or to the left of the slider.
  83 If 0, no tick marks will be displayed.
  84 .OP \-to to To
  85 Specifies a real value corresponding
  86 to the right or bottom end of the scale.
  87 This value may be either less than or greater than the \fBfrom\fR option.
  88 .OP \-variable variable Variable
  89 Specifies the name of a global variable to link to the scale.  Whenever the
  90 value of the variable changes, the scale will update to reflect this
  91 value.
  92 Whenever the scale is manipulated interactively, the variable
  93 will be modified to reflect the scale's new value.
  94 .OP \-width width Width
  95 Specifies the desired narrow dimension of the trough in screen units
  96 (i.e. any of the forms acceptable to \fBTk_GetPixels\fR).
  97 For vertical scales this is the trough's width;  for horizontal scales
  98 this is the trough's height.
  99 .BE
 100
 101 .SH DESCRIPTION
 102 .PP
 103 The \fBscale\fR command creates a new window (given by the
 104 \fIpathName\fR argument) and makes it into a scale widget.
 105 Additional
 106 options, described above, may be specified on the command line
 107 or in the option database
 108 to configure aspects of the scale such as its colors, orientation,
 109 and relief.  The \fBscale\fR command returns its
 110 \fIpathName\fR argument.  At the time this command is invoked,
 111 there must not exist a window named \fIpathName\fR, but
 112 \fIpathName\fR's parent must exist.
 113 .PP
 114 A scale is a widget that displays a rectangular \fItrough\fR and a
 115 small \fIslider\fR.  The trough corresponds to a range
 116 of real values (determined by the \fBfrom\fR, \fBto\fR, and
 117 \fBresolution\fR options),
 118 and the position of the slider selects a particular real value.
 119 The slider's position (and hence the scale's value) may be adjusted
 120 with the mouse or keyboard as described in the BINDINGS
 121 section below.  Whenever the scale's value is changed, a Tcl
 122 command is invoked (using the \fBcommand\fR option) to notify
 123 other interested widgets of the change.
 124 In addition, the value
 125 of the scale can be linked to a Tcl variable (using the \fBvariable\fR
 126 option), so that changes in either are reflected in the other.
 127 .PP
 128 Three annotations may be displayed in a scale widget:  a label
 129 appearing at the top right of the widget (top left for horizontal
 130 scales), a number displayed just to the left of the slider
 131 (just above the slider for horizontal scales), and a collection
 132 of numerical tick marks just to the left of the current value
 133 (just below the trough for horizontal scales).  Each of these three
 134 annotations may be enabled or disabled using the
 135 configuration options.
 136
 137 .SH "WIDGET COMMAND"
 138 .PP
 139 The \fBscale\fR command creates a new Tcl command whose
 140 name is \fIpathName\fR.  This
 141 command may be used to invoke various
 142 operations on the widget.  It has the following general form:
 143 .CS
 144 \fIpathName option \fR?\fIarg arg ...\fR?
 145 .CE
 146 \fIOption\fR and the \fIarg\fRs
 147 determine the exact behavior of the command.  The following
 148 commands are possible for scale widgets:
 149 .TP
 150 \fIpathName \fBcget\fR \fIoption\fR
 151 Returns the current value of the configuration option given
 152 by \fIoption\fR.
 153 \fIOption\fR may have any of the values accepted by the \fBscale\fR
 154 command.
 155 .TP
 156 \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
 157 Query or modify the configuration options of the widget.
 158 If no \fIoption\fR is specified, returns a list describing all of
 159 the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for
 160 information on the format of this list).  If \fIoption\fR is specified
 161 with no \fIvalue\fR, then the command returns a list describing the
 162 one named option (this list will be identical to the corresponding
 163 sublist of the value returned if no \fIoption\fR is specified).  If
 164 one or more \fIoption\-value\fR pairs are specified, then the command
 165 modifies the given widget option(s) to have the given value(s);  in
 166 this case the command returns an empty string.
 167 \fIOption\fR may have any of the values accepted by the \fBscale\fR
 168 command.
 169 .TP
 170 \fIpathName \fBcoords \fR?\fIvalue\fR?
 171 Returns a list whose elements are the x and y coordinates of
 172 the point along the centerline of the trough that corresponds
 173 to \fIvalue\fR.
 174 If \fIvalue\fR is omitted then the scale's current value is used.
 175 .TP
 176 \fIpathName \fBget\fR ?\fIx y\fR?
 177 If \fIx\fR and \fIy\fR are omitted, returns the current value
 178 of the scale.  If \fIx\fR and \fIy\fR are specified, they give
 179 pixel coordinates within the widget;  the command returns
 180 the scale value corresponding to the given pixel.
 181 Only one of \fIx\fR or \fIy\fR is used:  for horizontal scales
 182 \fIy\fR is ignored, and for vertical scales \fIx\fR is ignored.
 183 .TP
 184 \fIpathName \fBidentify\fR \fIx y\fR
 185 Returns a string indicating what part of the scale lies under
 186 the coordinates given by \fIx\fR and \fIy\fR.
 187 A return value of \fBslider\fR means that the point is over
 188 the slider;  \fBtrough1\fR means that the point is over the
 189 portion of the slider above  or to the left of the slider;
 190 and \fBtrough2\fR means that the point is over the portion
 191 of the slider below or to the right of the slider.
 192 If the point isn't over one of these elements, an empty string
 193 is returned.
 194 .TP
 195 \fIpathName \fBset\fR \fIvalue\fR
 196 This command is invoked to change the current value of the scale,
 197 and hence the position at which the slider is displayed.  \fIValue\fR
 198 gives the new value for the scale.
 199 The command has no effect if the scale is disabled.
 200
 201 .SH BINDINGS
 202 .PP
 203 Tk automatically creates class bindings for scales that give them
 204 the following default behavior.
 205 Where the behavior is different for vertical and horizontal scales,
 206 the horizontal behavior is described in parentheses.
 207 .IP [1]
 208 If button 1 is pressed in the trough, the scale's value will
 209 be incremented or decremented by the value of the \fBresolution\fR
 210 option so that the slider moves in the direction of the cursor.
 211 If the button is held down, the action auto-repeats.
 212 .IP [2]
 213 If button 1 is pressed over the slider, the slider can be dragged
 214 with the mouse.
 215 .IP [3]
 216 If button 1 is pressed in the trough with the Control key down,
 217 the slider moves all the way to the end of its range, in the
 218 direction towards the mouse cursor.
 219 .IP [4]
 220 If button 2 is pressed, the scale's value is set to the mouse
 221 position.  If the mouse is dragged with button 2 down, the scale's
 222 value changes with the drag.
 223 .IP [5]
 224 The Up and Left keys move the slider up (left) by the value
 225 of the \fBresolution\fR option.
 226 .IP [6]
 227 The Down and Right keys move the slider down (right) by the value
 228 of the \fBresolution\fR option.
 229 .IP [7]
 230 Control-Up and Control-Left move the slider up (left) by the
 231 value of the \fBbigIncrement\fR option.
 232 .IP [8]
 233 Control-Down and Control-Right move the slider down (right) by the
 234 value of the \fBbigIncrement\fR option.
 235 .IP [9]
 236 Home moves the slider to the top (left) end of its range.
 237 .IP [10]
 238 End moves the slider to the bottom (right) end of its range.
 239 .PP
 240 If the scale is disabled using the \fBstate\fR option then
 241 none of the above bindings have any effect.
 242 .PP
 243 The behavior of scales can be changed by defining new bindings for
 244 individual widgets or by redefining the class bindings.
 245
 246 .SH KEYWORDS
 247 scale, slider, trough, widget