Initial commit of OpenSPARC T2 design and verification files.
[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / Tk::Scale.3
CommitLineData
86530b38
AT
1.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sh \" Subsection heading
6.br
7.if t .Sp
8.ne 5
9.PP
10\fB\\$1\fR
11.PP
12..
13.de Sp \" Vertical space (when we can't use .PP)
14.if t .sp .5v
15.if n .sp
16..
17.de Vb \" Begin verbatim text
18.ft CW
19.nf
20.ne \\$1
21..
22.de Ve \" End verbatim text
23.ft R
24.fi
25..
26.\" Set up some character translations and predefined strings. \*(-- will
27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28.\" double quote, and \*(R" will give a right double quote. | will give a
29.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31.\" expand to `' in nroff, nothing in troff, for use with C<>.
32.tr \(*W-|\(bv\*(Tr
33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34.ie n \{\
35. ds -- \(*W-
36. ds PI pi
37. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39. ds L" ""
40. ds R" ""
41. ds C` ""
42. ds C' ""
43'br\}
44.el\{\
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
49'br\}
50.\"
51.\" If the F register is turned on, we'll generate index entries on stderr for
52.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53.\" entries marked with X<> in POD. Of course, you'll have to process the
54.\" output yourself in some meaningful fashion.
55.if \nF \{\
56. de IX
57. tm Index:\\$1\t\\n%\t"\\$2"
58..
59. nr % 0
60. rr F
61.\}
62.\"
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
66.if n .na
67.\"
68.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69.\" Fear. Run. Save yourself. No user-serviceable parts.
70. \" fudge factors for nroff and troff
71.if n \{\
72. ds #H 0
73. ds #V .8m
74. ds #F .3m
75. ds #[ \f1
76. ds #] \fP
77.\}
78.if t \{\
79. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80. ds #V .6m
81. ds #F 0
82. ds #[ \&
83. ds #] \&
84.\}
85. \" simple accents for nroff and troff
86.if n \{\
87. ds ' \&
88. ds ` \&
89. ds ^ \&
90. ds , \&
91. ds ~ ~
92. ds /
93.\}
94.if t \{\
95. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
101.\}
102. \" troff and (daisy-wheel) nroff accents
103.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110.ds ae a\h'-(\w'a'u*4/10)'e
111.ds Ae A\h'-(\w'A'u*4/10)'E
112. \" corrections for vroff
113.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115. \" for low resolution devices (crt and lpr)
116.if \n(.H>23 .if \n(.V>19 \
117\{\
118. ds : e
119. ds 8 ss
120. ds o a
121. ds d- d\h'-1'\(ga
122. ds D- D\h'-1'\(hy
123. ds th \o'bp'
124. ds Th \o'LP'
125. ds ae ae
126. ds Ae AE
127.\}
128.rm #[ #] #H #V #F C
129.\" ========================================================================
130.\"
131.IX Title "SCALE 1"
132.TH SCALE 1 "2000-12-30" "perl v5.8.0" "User Contributed Perl Documentation"
133.SH "NAME"
134Tk::Scale \- Create and manipulate Scale widgets
135.SH "SYNOPSIS"
136.IX Header "SYNOPSIS"
137\&\fI$scale\fR = \fI$parent\fR\->\fBScale\fR(?\fIoptions\fR?);
138.SH "STANDARD OPTIONS"
139.IX Header "STANDARD OPTIONS"
140\&\fB\-activebackground\fR \fB\-font\fR \fB\-highlightthickness\fR \fB\-repeatinterval\fR
141\&\fB\-background\fR \fB\-foreground\fR \fB\-orient\fR \fB\-takefocus\fR
142\&\fB\-borderwidth\fR \fB\-highlightbackground\fR \fB\-relief\fR \fB\-troughcolor\fR
143\&\fB\-cursor\fR \fB\-highlightcolor\fR \fB\-repeatdelay\fR
144.PP
145See Tk::options for details of the standard options.
146.SH "WIDGET-SPECIFIC OPTIONS"
147.IX Header "WIDGET-SPECIFIC OPTIONS"
148.IP "Name: \fBbigIncrement\fR" 4
149.IX Item "Name: bigIncrement"
150.PD 0
151.IP "Class: \fBBigIncrement\fR" 4
152.IX Item "Class: BigIncrement"
153.IP "Switch: \fB\-bigincrement\fR" 4
154.IX Item "Switch: -bigincrement"
155.PD
156Some interactions with the scale cause its value to change by
157``large'' increments; this option specifies the size of the
158large increments. If specified as 0, the large increments default
159to 1/10 the range of the scale.
160.IP "Name: \fBcommand\fR" 4
161.IX Item "Name: command"
162.PD 0
163.IP "Class: \fBCommand\fR" 4
164.IX Item "Class: Command"
165.IP "Switch: \fB\-command\fR" 4
166.IX Item "Switch: -command"
167.PD
168Specifies the prefix of a perl/Tk callback to invoke whenever the scale's
169value is changed via a method.
170The actual command consists
171of this option followed by a space and a real number indicating the
172new value of the scale.
173.IP "Name: \fBdigits\fR" 4
174.IX Item "Name: digits"
175.PD 0
176.IP "Class: \fBDigits\fR" 4
177.IX Item "Class: Digits"
178.IP "Switch: \fB\-digits\fR" 4
179.IX Item "Switch: -digits"
180.PD
181An integer specifying how many significant digits should be retained
182when converting the value of the scale to a string.
183If the number is less than or equal to zero, then the scale picks
184the smallest value that guarantees that every possible slider
185position prints as a different string.
186.IP "Name: \fBfrom\fR" 4
187.IX Item "Name: from"
188.PD 0
189.IP "Class: \fBFrom\fR" 4
190.IX Item "Class: From"
191.IP "Switch: \fB\-from\fR" 4
192.IX Item "Switch: -from"
193.PD
194A real value corresponding to the left or top end of the scale.
195.IP "Name: \fBlabel\fR" 4
196.IX Item "Name: label"
197.PD 0
198.IP "Class: \fBLabel\fR" 4
199.IX Item "Class: Label"
200.IP "Switch: \fB\-label\fR" 4
201.IX Item "Switch: -label"
202.PD
203A string to display as a label for the scale. For
204vertical scales the label is displayed just to the right of the
205top end of the scale. For horizontal scales the label is displayed
206just above the left end of the scale. If the option is specified
207as an empty string, no label is displayed.
208.IP "Name: \fBlength\fR" 4
209.IX Item "Name: length"
210.PD 0
211.IP "Class: \fBLength\fR" 4
212.IX Item "Class: Length"
213.IP "Switch: \fB\-length\fR" 4
214.IX Item "Switch: -length"
215.PD
216Specifies the desired long dimension of the scale in screen units
217(i.e. any of the forms acceptable to \fBTk_GetPixels\fR).
218For vertical scales this is the scale's height; for horizontal scales
219it is the scale's width.
220.IP "Name: \fBresolution\fR" 4
221.IX Item "Name: resolution"
222.PD 0
223.IP "Class: \fBResolution\fR" 4
224.IX Item "Class: Resolution"
225.IP "Switch: \fB\-resolution\fR" 4
226.IX Item "Switch: -resolution"
227.PD
228A real value specifying the resolution for the scale.
229If this value is greater than zero then the scale's value will always be
230rounded to an even multiple of this value, as will tick marks and
231the endpoints of the scale. If the value is less than zero then no
232rounding occurs. Defaults to 1 (i.e., the value will be integral).
233.IP "Name: \fBshowValue\fR" 4
234.IX Item "Name: showValue"
235.PD 0
236.IP "Class: \fBShowValue\fR" 4
237.IX Item "Class: ShowValue"
238.IP "Switch: \fB\-showvalue\fR" 4
239.IX Item "Switch: -showvalue"
240.PD
241Specifies a boolean value indicating whether or not the current
242value of the scale is to be displayed.
243.IP "Name: \fBsliderLength\fR" 4
244.IX Item "Name: sliderLength"
245.PD 0
246.IP "Class: \fBSliderLength\fR" 4
247.IX Item "Class: SliderLength"
248.IP "Switch: \fB\-sliderlength\fR" 4
249.IX Item "Switch: -sliderlength"
250.PD
251Specfies the size of the slider, measured in screen units along the slider's
252long dimension. The value may be specified in any of the forms acceptable
253to \fBTk_GetPixels\fR.
254.IP "Name: \fBsliderRelief\fR" 4
255.IX Item "Name: sliderRelief"
256.PD 0
257.IP "Class: \fBSliderRelief\fR" 4
258.IX Item "Class: SliderRelief"
259.IP "Switch: \fB\-sliderrelief\fR" 4
260.IX Item "Switch: -sliderrelief"
261.PD
262Specifies the relief to use when drawing the slider, such as \fBraised\fR
263or \fBsunken\fR.
264.IP "Name: \fBstate\fR" 4
265.IX Item "Name: state"
266.PD 0
267.IP "Class: \fBState\fR" 4
268.IX Item "Class: State"
269.IP "Switch: \fB\-state\fR" 4
270.IX Item "Switch: -state"
271.PD
272Specifies one of three states for the scale: \fBnormal\fR,
273\&\fBactive\fR, or \fBdisabled\fR.
274If the scale is disabled then the value may not be changed and the scale
275won't activate.
276If the scale is active, the slider is displayed using the color
277specified by the \fBactiveBackground\fR option.
278.IP "Name: \fBtickInterval\fR" 4
279.IX Item "Name: tickInterval"
280.PD 0
281.IP "Class: \fBTickInterval\fR" 4
282.IX Item "Class: TickInterval"
283.IP "Switch: \fB\-tickinterval\fR" 4
284.IX Item "Switch: -tickinterval"
285.PD
286Must be a real value.
287Determines the spacing between numerical
288tick marks displayed below or to the left of the slider.
289If 0, no tick marks will be displayed.
290.IP "Name: \fBto\fR" 4
291.IX Item "Name: to"
292.PD 0
293.IP "Class: \fBTo\fR" 4
294.IX Item "Class: To"
295.IP "Switch: \fB\-to\fR" 4
296.IX Item "Switch: -to"
297.PD
298Specifies a real value corresponding
299to the right or bottom end of the scale.
300This value may be either less than or greater than the \fBfrom\fR option.
301.IP "Name: \fBvariable\fR" 4
302.IX Item "Name: variable"
303.PD 0
304.IP "Class: \fBVariable\fR" 4
305.IX Item "Class: Variable"
306.IP "Switch: \fB\-variable\fR" 4
307.IX Item "Switch: -variable"
308.PD
309Specifies the name of a global variable to link to the scale. Whenever the
310value of the variable changes, the scale will update to reflect this
311value.
312Whenever the scale is manipulated interactively, the variable
313will be modified to reflect the scale's new value.
314.IP "Name: \fBwidth\fR" 4
315.IX Item "Name: width"
316.PD 0
317.IP "Class: \fBWidth\fR" 4
318.IX Item "Class: Width"
319.IP "Switch: \fB\-width\fR" 4
320.IX Item "Switch: -width"
321.PD
322Specifies the desired narrow dimension of the trough in screen units
323(i.e. any of the forms acceptable to \fBTk_GetPixels\fR).
324For vertical scales this is the trough's width; for horizontal scales
325this is the trough's height.
326.SH "DESCRIPTION"
327.IX Header "DESCRIPTION"
328The \fBScale\fR method creates a new window (given by the
329\&\f(CW$widget\fR argument) and makes it into a scale widget.
330Additional
331options, described above, may be specified on the command line
332or in the option database
333to configure aspects of the scale such as its colors, orientation,
334and relief. The \fBscale\fR command returns its
335\&\f(CW$widget\fR argument. At the time this command is invoked,
336there must not exist a window named \f(CW$widget\fR, but
337\&\f(CW$widget\fR's parent must exist.
338.PP
339A scale is a widget that displays a rectangular \fItrough\fR and a
340small \fIslider\fR. The trough corresponds to a range
341of real values (determined by the \fBfrom\fR, \fBto\fR, and
342\&\fBresolution\fR options),
343and the position of the slider selects a particular real value.
344The slider's position (and hence the scale's value) may be adjusted
345with the mouse or keyboard as described in
346the \*(L"\s-1BINDINGS\s0\*(R" section below. Whenever the scale's value is changed, a Tcl
347command is invoked (using the \fBcommand\fR option) to notify
348other interested widgets of the change.
349In addition, the value
350of the scale can be linked to a Tcl variable (using the \fBvariable\fR
351option), so that changes in either are reflected in the other.
352.PP
353Three annotations may be displayed in a scale widget: a label
354appearing at the top right of the widget (top left for horizontal
355scales), a number displayed just to the left of the slider
356(just above the slider for horizontal scales), and a collection
357of numerical tick marks just to the left of the current value
358(just below the trough for horizontal scales). Each of these three
359annotations may be enabled or disabled using the
360configuration options.
361.SH "WIDGET METHODS"
362.IX Header "WIDGET METHODS"
363The \fBScale\fR method creates a widget object.
364This object supports the \fBconfigure\fR and \fBcget\fR methods
365described in Tk::options which can be used to enquire and
366modify the options described above.
367The widget also inherits all the methods provided by the generic
368Tk::Widget class.
369.PP
370The following additional methods are available for scale widgets:
371.IP "\fI$scale\fR\->\fBcoords\fR(?\fIvalue\fR?)" 4
372.IX Item "$scale->coords(?value?)"
373Returns a list whose elements are the x and y coordinates of
374the point along the centerline of the trough that corresponds
375to \fIvalue\fR.
376If \fIvalue\fR is omitted then the scale's current value is used.
377.IP "\fI$scale\fR\->\fBget\fR(?\fIx, y\fR?)" 4
378.IX Item "$scale->get(?x, y?)"
379If \fIx\fR and \fIy\fR are omitted, returns the current value
380of the scale. If \fIx\fR and \fIy\fR are specified, they give
381pixel coordinates within the widget; the command returns
382the scale value corresponding to the given pixel.
383Only one of \fIx\fR or \fIy\fR is used: for horizontal scales
384\&\fIy\fR is ignored, and for vertical scales \fIx\fR is ignored.
385.IP "\fI$scale\fR\->\fBidentify\fR(\fIx, y\fR)" 4
386.IX Item "$scale->identify(x, y)"
387Returns a string indicating what part of the scale lies under
388the coordinates given by \fIx\fR and \fIy\fR.
389A return value of \fBslider\fR means that the point is over
390the slider; \fBtrough1\fR means that the point is over the
391portion of the slider above or to the left of the slider;
392and \fBtrough2\fR means that the point is over the portion
393of the slider below or to the right of the slider.
394If the point isn't over one of these elements, an empty string
395is returned.
396.IP "\fI$scale\fR\->\fBset\fR(\fIvalue\fR)" 4
397.IX Item "$scale->set(value)"
398This command is invoked to change the current value of the scale,
399and hence the position at which the slider is displayed. \fIValue\fR
400gives the new value for the scale.
401The command has no effect if the scale is disabled.
402.SH "BINDINGS"
403.IX Header "BINDINGS"
404Tk automatically creates class bindings for scales that give them
405the following default behavior.
406Where the behavior is different for vertical and horizontal scales,
407the horizontal behavior is described in parentheses.
408.IP "[1]" 4
409.IX Item "[1]"
410If button 1 is pressed in the trough, the scale's value will
411be incremented or decremented by the value of the \fBresolution\fR
412option so that the slider moves in the direction of the cursor.
413If the button is held down, the action auto\-repeats.
414.IP "[2]" 4
415.IX Item "[2]"
416If button 1 is pressed over the slider, the slider can be dragged
417with the mouse.
418.IP "[3]" 4
419.IX Item "[3]"
420If button 1 is pressed in the trough with the Control key down,
421the slider moves all the way to the end of its range, in the
422direction towards the mouse cursor.
423.IP "[4]" 4
424.IX Item "[4]"
425If button 2 is pressed, the scale's value is set to the mouse
426position. If the mouse is dragged with button 2 down, the scale's
427value changes with the drag.
428.IP "[5]" 4
429.IX Item "[5]"
430The Up and Left keys move the slider up (left) by the value
431of the \fBresolution\fR option.
432.IP "[6]" 4
433.IX Item "[6]"
434The Down and Right keys move the slider down (right) by the value
435of the \fBresolution\fR option.
436.IP "[7]" 4
437.IX Item "[7]"
438Control-Up and Control-Left move the slider up (left) by the
439value of the \fBbigIncrement\fR option.
440.IP "[8]" 4
441.IX Item "[8]"
442Control-Down and Control-Right move the slider down (right) by the
443value of the \fBbigIncrement\fR option.
444.IP "[9]" 4
445.IX Item "[9]"
446Home moves the slider to the top (left) end of its range.
447.IP "[10]" 4
448.IX Item "[10]"
449End moves the slider to the bottom (right) end of its range.
450.Sp
451If the scale is disabled using the \fBstate\fR option then
452none of the above bindings have any effect.
453.Sp
454The behavior of scales can be changed by defining new bindings for
455individual widgets or by redefining the class bindings.
456.SH "KEYWORDS"
457.IX Header "KEYWORDS"
458scale, slider, trough, widget