<section ID="chapter.widgets.scale">
  <TITLE>Tdscale and lrscale widgets</TITLE>

<subsection> <TITLE>Description</TITLE>

<P>
A scale is a widget that displays a rectangular trough and a small slider. <<tdscale>> displays a vertical slider while <<lrscale>> displays an horizontal one. 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. Whenever the scale's value is changed, an Oz command is invoked (using the <<action>> option) to notify other interested widgets of
the change. 
</P>
<P>
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. 

<subsection> <TITLE>Parameters</TITLE>

<P>
<LIST>

<ITEM> <<1:R>> : Specifies the value of the scale. Valid with the <<set()>> and <<get()>> methods only. <<R>> must be a real.

<ITEM> <<init:R>> : Specifies the value of the scale. Valid at creation time only. <<R>> must be a real.

<ITEM> <<return:V>> : Binds <<V>> to the value of the scale when the window is closed. <<V>> must be a free variable.

&param_activebackground;
&param_background;
&param_borderwidth;
&param_cursor;
&param_font;
&param_foreground;
&param_highlightbackground;
&param_highlightcolor;
&param_highlightthickness;
&param_relief;
&param_repeatdelay;
&param_repeatinterval;
&param_takefocus;
&param_throughcolor;

<ITEM> <<bigincrement:F>> : 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. <<F>> must be a float.

<ITEM> <<digits:I>> : 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. 

<ITEM> <<'from':F>> : A real value corresponding to the left or top end of the scale. 

<ITEM> <<label:VS>> : 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. 

<ITEM> <<length:P>> : Specifies the desired long dimension of the scale. For vertical scales this is the scale's height; for horizontal scales it is the scale's width. <<P>> must be a valid screen distance (see <ptr to="misc.distance">).

<ITEM> <<resolution:F>> : 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). 

<ITEM> <<showvalue:B>> : Specifies a boolean value indicating whether or not the current value of the scale is to be displayed. 

<ITEM> <<sliderlength:P>> : Specifies the size of the slider, measured in screen units along the slider's long dimension. <<P>> must be a valid screen distance (see <ptr to="misc.distance">).

<ITEM> <<sliderrelief:A>> : Specifies the relief to use when drawing the slider. Must be one of these atoms : <<raised>>, <<sunken>>, <<flat>>, <<ridge>>, <<solid>> or <<groove>>.

<ITEM> <<state:A>> : Specifies one of three states for the button: <<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. 

<ITEM> <<tickinterval:F>> : 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. 

<ITEM> <<to:F>> : 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. 

<ITEM> <<width:P>> : Specifies the desired narrow dimension of the trough. For vertical scales this is the trough's width; for horizontal scales this is the trough's height. <<P>> must be a valid screen distance (see <ptr to="misc.distance">).

<ITEM> <<action:C>> : Specifies an action to execute juste after the user modified the position of the slider of the scale. <<C>> can take several different forms (see <ptr to="basics.events">).

&param_glue;
&param_padx;
&param_pady;
&param_feature;
&param_handle;
&param_tooltips;


</LIST>

</P>

<subsection> <TITLE>Interface</TITLE>

<P>
The object you get by an handle on the widget implements the following methods :

<LIST>

&interface_set;
&interface_get;
&interface_bind;
&interface_getFocus;
&interface_setGrab;
&interface_releaseGrab;
&interface_getGrabStatus;
&interface_raise;
&interface_lower;
&interface_winfo;

</LIST>

</section>
