Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # Copyright (c) 1990-1994 The Regents of the University of California. |
2 | # Copyright (c) 1994-1996 Sun Microsystems, Inc. | |
3 | # See the file "license.terms" for information on usage and redistribution | |
4 | # of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
5 | # | |
6 | # | |
7 | ||
8 | =head1 NAME | |
9 | ||
10 | Tk::Scale - Create and manipulate Scale widgets | |
11 | ||
12 | =for category Tk Widget Classes | |
13 | ||
14 | =head1 SYNOPSIS | |
15 | ||
16 | I<$scale> = I<$parent>-E<gt>B<Scale>(?I<options>?); | |
17 | ||
18 | =head1 STANDARD OPTIONS | |
19 | ||
20 | B<-activebackground> B<-font> B<-highlightthickness> B<-repeatinterval> | |
21 | B<-background> B<-foreground> B<-orient> B<-takefocus> | |
22 | B<-borderwidth> B<-highlightbackground> B<-relief> B<-troughcolor> | |
23 | B<-cursor> B<-highlightcolor> B<-repeatdelay> | |
24 | ||
25 | See L<Tk::options> for details of the standard options. | |
26 | ||
27 | =head1 WIDGET-SPECIFIC OPTIONS | |
28 | ||
29 | =over 4 | |
30 | ||
31 | =item Name: B<bigIncrement> | |
32 | ||
33 | =item Class: B<BigIncrement> | |
34 | ||
35 | =item Switch: B<-bigincrement> | |
36 | ||
37 | Some interactions with the scale cause its value to change by | |
38 | ``large'' increments; this option specifies the size of the | |
39 | large increments. If specified as 0, the large increments default | |
40 | to 1/10 the range of the scale. | |
41 | ||
42 | =item Name: B<command> | |
43 | ||
44 | =item Class: B<Command> | |
45 | ||
46 | =item Switch: B<-command> | |
47 | ||
48 | Specifies the prefix of a L<perl/Tk callback|Tk::callbacks> to invoke whenever the scale's | |
49 | value is changed via a method. | |
50 | The actual command consists | |
51 | of this option followed by a space and a real number indicating the | |
52 | new value of the scale. | |
53 | ||
54 | =item Name: B<digits> | |
55 | ||
56 | =item Class: B<Digits> | |
57 | ||
58 | =item Switch: B<-digits> | |
59 | ||
60 | An integer specifying how many significant digits should be retained | |
61 | when converting the value of the scale to a string. | |
62 | If the number is less than or equal to zero, then the scale picks | |
63 | the smallest value that guarantees that every possible slider | |
64 | position prints as a different string. | |
65 | ||
66 | =item Name: B<from> | |
67 | ||
68 | =item Class: B<From> | |
69 | ||
70 | =item Switch: B<-from> | |
71 | ||
72 | A real value corresponding to the left or top end of the scale. | |
73 | ||
74 | =item Name: B<label> | |
75 | ||
76 | =item Class: B<Label> | |
77 | ||
78 | =item Switch: B<-label> | |
79 | ||
80 | A string to display as a label for the scale. For | |
81 | vertical scales the label is displayed just to the right of the | |
82 | top end of the scale. For horizontal scales the label is displayed | |
83 | just above the left end of the scale. If the option is specified | |
84 | as an empty string, no label is displayed. | |
85 | ||
86 | =item Name: B<length> | |
87 | ||
88 | =item Class: B<Length> | |
89 | ||
90 | =item Switch: B<-length> | |
91 | ||
92 | Specifies the desired long dimension of the scale in screen units | |
93 | (i.e. any of the forms acceptable to B<Tk_GetPixels>). | |
94 | For vertical scales this is the scale's height; for horizontal scales | |
95 | it is the scale's width. | |
96 | ||
97 | =item Name: B<resolution> | |
98 | ||
99 | =item Class: B<Resolution> | |
100 | ||
101 | =item Switch: B<-resolution> | |
102 | ||
103 | A real value specifying the resolution for the scale. | |
104 | If this value is greater than zero then the scale's value will always be | |
105 | rounded to an even multiple of this value, as will tick marks and | |
106 | the endpoints of the scale. If the value is less than zero then no | |
107 | rounding occurs. Defaults to 1 (i.e., the value will be integral). | |
108 | ||
109 | =item Name: B<showValue> | |
110 | ||
111 | =item Class: B<ShowValue> | |
112 | ||
113 | =item Switch: B<-showvalue> | |
114 | ||
115 | Specifies a boolean value indicating whether or not the current | |
116 | value of the scale is to be displayed. | |
117 | ||
118 | =item Name: B<sliderLength> | |
119 | ||
120 | =item Class: B<SliderLength> | |
121 | ||
122 | =item Switch: B<-sliderlength> | |
123 | ||
124 | Specfies the size of the slider, measured in screen units along the slider's | |
125 | long dimension. The value may be specified in any of the forms acceptable | |
126 | to B<Tk_GetPixels>. | |
127 | ||
128 | =item Name: B<sliderRelief> | |
129 | ||
130 | =item Class: B<SliderRelief> | |
131 | ||
132 | =item Switch: B<-sliderrelief> | |
133 | ||
134 | Specifies the relief to use when drawing the slider, such as B<raised> | |
135 | or B<sunken>. | |
136 | ||
137 | =item Name: B<state> | |
138 | ||
139 | =item Class: B<State> | |
140 | ||
141 | =item Switch: B<-state> | |
142 | ||
143 | Specifies one of three states for the scale: B<normal>, | |
144 | B<active>, or B<disabled>. | |
145 | If the scale is disabled then the value may not be changed and the scale | |
146 | won't activate. | |
147 | If the scale is active, the slider is displayed using the color | |
148 | specified by the B<activeBackground> option. | |
149 | ||
150 | =item Name: B<tickInterval> | |
151 | ||
152 | =item Class: B<TickInterval> | |
153 | ||
154 | =item Switch: B<-tickinterval> | |
155 | ||
156 | Must be a real value. | |
157 | Determines the spacing between numerical | |
158 | tick marks displayed below or to the left of the slider. | |
159 | If 0, no tick marks will be displayed. | |
160 | ||
161 | =item Name: B<to> | |
162 | ||
163 | =item Class: B<To> | |
164 | ||
165 | =item Switch: B<-to> | |
166 | ||
167 | Specifies a real value corresponding | |
168 | to the right or bottom end of the scale. | |
169 | This value may be either less than or greater than the B<from> option. | |
170 | ||
171 | =item Name: B<variable> | |
172 | ||
173 | =item Class: B<Variable> | |
174 | ||
175 | =item Switch: B<-variable> | |
176 | ||
177 | Specifies the name of a global variable to link to the scale. Whenever the | |
178 | value of the variable changes, the scale will update to reflect this | |
179 | value. | |
180 | Whenever the scale is manipulated interactively, the variable | |
181 | will be modified to reflect the scale's new value. | |
182 | ||
183 | =item Name: B<width> | |
184 | ||
185 | =item Class: B<Width> | |
186 | ||
187 | =item Switch: B<-width> | |
188 | ||
189 | Specifies the desired narrow dimension of the trough in screen units | |
190 | (i.e. any of the forms acceptable to B<Tk_GetPixels>). | |
191 | For vertical scales this is the trough's width; for horizontal scales | |
192 | this is the trough's height. | |
193 | ||
194 | =back | |
195 | ||
196 | =head1 DESCRIPTION | |
197 | ||
198 | The B<Scale> method creates a new window (given by the | |
199 | $widget argument) and makes it into a scale widget. | |
200 | Additional | |
201 | options, described above, may be specified on the command line | |
202 | or in the option database | |
203 | to configure aspects of the scale such as its colors, orientation, | |
204 | and relief. The B<scale> command returns its | |
205 | $widget argument. At the time this command is invoked, | |
206 | there must not exist a window named $widget, but | |
207 | $widget's parent must exist. | |
208 | ||
209 | A scale is a widget that displays a rectangular I<trough> and a | |
210 | small I<slider>. The trough corresponds to a range | |
211 | of real values (determined by the B<from>, B<to>, and | |
212 | B<resolution> options), | |
213 | and the position of the slider selects a particular real value. | |
214 | The slider's position (and hence the scale's value) may be adjusted | |
215 | with the mouse or keyboard as described in | |
216 | the L<"BINDINGS"> section below. Whenever the scale's value is changed, a Tcl | |
217 | command is invoked (using the B<command> option) to notify | |
218 | other interested widgets of the change. | |
219 | In addition, the value | |
220 | of the scale can be linked to a Tcl variable (using the B<variable> | |
221 | option), so that changes in either are reflected in the other. | |
222 | ||
223 | Three annotations may be displayed in a scale widget: a label | |
224 | appearing at the top right of the widget (top left for horizontal | |
225 | scales), a number displayed just to the left of the slider | |
226 | (just above the slider for horizontal scales), and a collection | |
227 | of numerical tick marks just to the left of the current value | |
228 | (just below the trough for horizontal scales). Each of these three | |
229 | annotations may be enabled or disabled using the | |
230 | configuration options. | |
231 | ||
232 | =head1 WIDGET METHODS | |
233 | ||
234 | The B<Scale> method creates a widget object. | |
235 | This object supports the B<configure> and B<cget> methods | |
236 | described in L<Tk::options> which can be used to enquire and | |
237 | modify the options described above. | |
238 | The widget also inherits all the methods provided by the generic | |
239 | L<Tk::Widget|Tk::Widget> class. | |
240 | ||
241 | The following additional methods are available for scale widgets: | |
242 | ||
243 | =over 4 | |
244 | ||
245 | =item I<$scale>-E<gt>B<coords>(?I<value>?) | |
246 | ||
247 | Returns a list whose elements are the x and y coordinates of | |
248 | the point along the centerline of the trough that corresponds | |
249 | to I<value>. | |
250 | If I<value> is omitted then the scale's current value is used. | |
251 | ||
252 | =item I<$scale>-E<gt>B<get>(?I<x, y>?) | |
253 | ||
254 | If I<x> and I<y> are omitted, returns the current value | |
255 | of the scale. If I<x> and I<y> are specified, they give | |
256 | pixel coordinates within the widget; the command returns | |
257 | the scale value corresponding to the given pixel. | |
258 | Only one of I<x> or I<y> is used: for horizontal scales | |
259 | I<y> is ignored, and for vertical scales I<x> is ignored. | |
260 | ||
261 | =item I<$scale>-E<gt>B<identify>(I<x, y>) | |
262 | ||
263 | Returns a string indicating what part of the scale lies under | |
264 | the coordinates given by I<x> and I<y>. | |
265 | A return value of B<slider> means that the point is over | |
266 | the slider; B<trough1> means that the point is over the | |
267 | portion of the slider above or to the left of the slider; | |
268 | and B<trough2> means that the point is over the portion | |
269 | of the slider below or to the right of the slider. | |
270 | If the point isn't over one of these elements, an empty string | |
271 | is returned. | |
272 | ||
273 | =item I<$scale>-E<gt>B<set>(I<value>) | |
274 | ||
275 | This command is invoked to change the current value of the scale, | |
276 | and hence the position at which the slider is displayed. I<Value> | |
277 | gives the new value for the scale. | |
278 | The command has no effect if the scale is disabled. | |
279 | ||
280 | =back | |
281 | ||
282 | =head1 BINDINGS | |
283 | ||
284 | Tk automatically creates class bindings for scales that give them | |
285 | the following default behavior. | |
286 | Where the behavior is different for vertical and horizontal scales, | |
287 | the horizontal behavior is described in parentheses. | |
288 | ||
289 | =over 4 | |
290 | ||
291 | =item [1] | |
292 | ||
293 | If button 1 is pressed in the trough, the scale's value will | |
294 | be incremented or decremented by the value of the B<resolution> | |
295 | option so that the slider moves in the direction of the cursor. | |
296 | If the button is held down, the action auto-repeats. | |
297 | ||
298 | =item [2] | |
299 | ||
300 | If button 1 is pressed over the slider, the slider can be dragged | |
301 | with the mouse. | |
302 | ||
303 | =item [3] | |
304 | ||
305 | If button 1 is pressed in the trough with the Control key down, | |
306 | the slider moves all the way to the end of its range, in the | |
307 | direction towards the mouse cursor. | |
308 | ||
309 | =item [4] | |
310 | ||
311 | If button 2 is pressed, the scale's value is set to the mouse | |
312 | position. If the mouse is dragged with button 2 down, the scale's | |
313 | value changes with the drag. | |
314 | ||
315 | =item [5] | |
316 | ||
317 | The Up and Left keys move the slider up (left) by the value | |
318 | of the B<resolution> option. | |
319 | ||
320 | =item [6] | |
321 | ||
322 | The Down and Right keys move the slider down (right) by the value | |
323 | of the B<resolution> option. | |
324 | ||
325 | =item [7] | |
326 | ||
327 | Control-Up and Control-Left move the slider up (left) by the | |
328 | value of the B<bigIncrement> option. | |
329 | ||
330 | =item [8] | |
331 | ||
332 | Control-Down and Control-Right move the slider down (right) by the | |
333 | value of the B<bigIncrement> option. | |
334 | ||
335 | =item [9] | |
336 | ||
337 | Home moves the slider to the top (left) end of its range. | |
338 | ||
339 | =item [10] | |
340 | ||
341 | End moves the slider to the bottom (right) end of its range. | |
342 | ||
343 | If the scale is disabled using the B<state> option then | |
344 | none of the above bindings have any effect. | |
345 | ||
346 | The behavior of scales can be changed by defining new bindings for | |
347 | individual widgets or by redefining the class bindings. | |
348 | ||
349 | =back | |
350 | ||
351 | =head1 KEYWORDS | |
352 | ||
353 | scale, slider, trough, widget | |
354 | ||
355 | =cut | |
356 |