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