<section ID="chapter.widgets.scrollbar">
  <TITLE>Tdscrollbar and lrscrollbar widgets</TITLE>

<subsection> <TITLE>Description</TITLE>

<P>
A scrollbar is a widget that displays two arrows, one at each end of the scrollbar, and a slider in the middle portion of the scrollbar. <<tdscrollbar>> displays a vertical scrollbar while <<lrscrollbar>> displays an horizontal one. It provides information about what is visible in an associated window that displays an document of some sort (such as a file being edited or a drawing). The position and size of the slider indicate which portion of the document is visible in the associated window. For example, if the slider in a vertical scrollbar covers the top third of the area between the two arrows, it means that the associated window displays the top third of its document. 
</P>
<P>
Scrollbars can be used to adjust the view in the associated window by clicking or dragging with the mouse.
</P>
<P>
Note that some widgets have <<tdscrollbar>> and <<lrscrollbar>> parameters that avoids to explicitly create scrollbar widgets.
</P>
<P>
<EM>ELEMENTS</EM>
</P>
<P>
A scrollbar displays five elements, which are referred to in the widget commands for the scrollbar: 
<LIST>
<ITEM> <<arrow1>> : The top or left arrow in the scrollbar. 
<ITEM> <<trough1>> : The region between the <<slider>> and <<arrow1>>. 
<ITEM> <<slider>> :  The rectangle that indicates what is visible in the associated widget. 
<ITEM> <<trough2>> : The region between the<< slider>> and <<arrow2>>. 
<ITEM> <<arrow2>> : The bottom or right arrow in the scrollbar. 
</LIST>

<subsection> <TITLE>Parameters</TITLE>

<P>
<LIST>

&param_activebackground;
&param_background;
&param_borderwidth;
&param_cursor;;
&param_highlightbackground;
&param_highlightcolor;
&param_highlightthickness;

<ITEM> <<jump:B>> : Specifies when notifications are made about changes in the value. If the value is <<false>>, updates are made continuously as the slider is dragged. If the value is <<true>>, updates are delayed until the mouse button is released to end the drag; at that point a single notification is made (the value ``jumps'' rather than changing smoothly). <<B>> must be a boolean.

&param_relief;
&param_repeatdelay;
&param_repeatinterval;
&param_takefocus;
&param_throughcolor;

<ITEM> <<activerelief:A>> : Specifies the relief to use when displaying the element that is active, if any. Elements other than the active element are always displayed with a raised relief. Must be one of these atoms : <<raised>>, <<sunken>>, <<flat>>, <<ridge>>, <<solid>> or <<groove>>.

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

<ITEM> <<elementborderwidth:P>> : Specifies the width of borders drawn around the internal elements of the scrollbar (the two arrows
    and the slider).If this value is less than zero, the value of the <<borderwidth>> option is used in its place. <<P>> must be a valid screen distance (see <ptr to="misc.distance">).

<ITEM> <<width:P>> : Specifies the desired narrow dimension of the scrollbar window, not including 3-D border, if any. For vertical scrollbars this will be the width and for horizontal scrollbars this will be the height. <<P>> must be a valid screen distance (see <ptr to="misc.distance">).
    
&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;

<ITEM> <<delta(X Y V)>> : Binds <<V>> to  a real number indicating the fractional change in the scrollbar setting that corresponds to a given change in slider position. For example, if the scrollbar is horizontal, the result indicates how much the scrollbar setting must change to move the slider <<X>> pixels to the right (<<Y>> is ignored in this case). If the scrollbar is vertical, the result indicates how much the scrollbar setting must change to move the slider <<Y>> pixels down.

<ITEM> <<fraction(X Y V)>>: Binds <<V>> to a real number between 0 and 1 indicating where the point given by <<X>> and <<Y>> lies in the trough area of the scrollbar. The value 0 corresponds to the top or left of the trough, the value 1 corresponds to the bottom or right, 0.5 corresponds to the middle, and so on. <<X>> and <<Y>> must be pixel coordinates relative to the scrollbar widget. If <<X>> and <<Y>> refer to a point outside the trough, the closest point in the trough is used. 

<ITEM> <<identify(X Y V)>>: Binds <<V>> to the name of the element under the point given by <<X>> and <<Y>> (such as <<arrow1>>), or an empty string if the point does not lie in any element of the scrollbar. <<X>> and <<y>> must be pixel coordinates relative to the scrollbar widget. 

</LIST>

</section>
