387 lines
18 KiB
HTML
387 lines
18 KiB
HTML
<HTML><HEAD><TITLE>Tk Built-In Commands - scrollbar manual page</TITLE></HEAD>
|
|
<BR>
|
|
<BODY bgcolor = #c3c3ff>
|
|
<H2><IMG ALIGN=BOTTOM SRC="./Img/ManPageBlue.gif"> scrollbar</H2>
|
|
<I>Create and manipulate scrollbar widgets</I><P><IMG ALIGN=TOP SRC="./Img/line-red.gif">
|
|
<H3><A NAME="M2">SYNOPSIS</A></H3>
|
|
(<B>scrollbar</B><I> widget-name </I>?<I>options</I>?)<BR>
|
|
<H3><A NAME="M3">STANDARD OPTIONS</A></H3>
|
|
<PRE>
|
|
<B><A HREF="options.n.html#M:activebackground">:activebackground</A></B> <B><A HREF="options.n.html#M:background">:background</A></B>
|
|
<B><A HREF="options.n.html#M:borderwidth">:borderwidth</A></B> <B><A HREF="options.n.html#M:cursor">:cursor</A></B>
|
|
<B><A HREF="options.n.html#M:highlightbackground">:highlightbackground</A></B> <B><A HREF="options.n.html#M:highlightcolor">:highlightcolor</A></B>
|
|
<B><A HREF="options.n.html#M:highlightthickness">:highlightthickness</A></B> <B><A HREF="options.n.html#M:jump">:jump</A></B>
|
|
<B><A HREF="options.n.html#M:orient">:orient</A></B> <B><A HREF="options.n.html#M:relief">:relief</A></B>
|
|
<B><A HREF="options.n.html#M:repeatdelay">:repeatdelay</A></B> <B><A HREF="options.n.html#M:repeatinterval">:repeatinterval</A></B>
|
|
<B><A HREF="options.n.html#M:takefocus">:takefocus</A></B> <B><A HREF="options.n.html#M:troughcolor">:troughcolor</A></B>
|
|
</PRE>
|
|
<H3><A NAME="M18">WIDGET-SPECIFIC OPTIONS</A></H3>
|
|
<DL>
|
|
<P>
|
|
<DT><I>Name</I>: <B>activeRelief</B>
|
|
<DT><I>Class</I>: <B>ActiveRelief</B>
|
|
<DT><I>Option keyword</I>: <B><A NAME="M19">:activerelief</A></B>
|
|
<DT><I>STklos slot name</I>: <B>active-relief</B>
|
|
<DD>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.
|
|
<P>
|
|
<P>
|
|
<DT><I>Name</I>: <B>command</B>
|
|
<DT><I>Class</I>: <B>Command</B>
|
|
<DT><I>Option keyword</I>: <B><A NAME="M20">:command</A></B>
|
|
<DT><I>STklos slot name</I>: <B>command</B>
|
|
<DD>Specifies a STk procedure to invoke to change the view
|
|
in the widget associated with the scrollbar. When a user requests
|
|
a view change by manipulating the scrollbar, the procedure is
|
|
invoked. The parameters given to this
|
|
procedure are described later.
|
|
<P>
|
|
<P>
|
|
<DT><I>Name</I>: <B>elementBorderWidth</B>
|
|
<DT><I>Class</I>: <B>BorderWidth</B>
|
|
<DT><I>Option keyword</I>: <B><A NAME="M21">:elementborderwidth</A></B>
|
|
<DT><I>STklos slot name</I>: <B>element-border-width</B>
|
|
<DD>Specifies the width of borders drawn around the internal elements
|
|
of the scrollbar (the two arrows and the slider). The value may
|
|
have any of the forms acceptable to <B>Tk_GetPixels</B>.
|
|
If this value is less than zero, the value of the <B>borderWidth</B>
|
|
option is used in its place.
|
|
<P>
|
|
<P>
|
|
<DT><I>Name</I>: <B>width</B>
|
|
<DT><I>Class</I>: <B>Width</B>
|
|
<DT><I>Option keyword</I>: <B><A NAME="M22">:width</A></B>
|
|
<DT><I>STklos slot name</I>: <B>width</B>
|
|
<DD>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.
|
|
The value may have any of the forms acceptable to <B>Tk_GetPixels</B>.
|
|
<P>
|
|
</DL>
|
|
<H3><A NAME="M23">DESCRIPTION</A></H3>
|
|
The <B>scrollbar</B> procedure creates a new window (given by the
|
|
<I>widget-name</I> argument) and makes it into a scrollbar widget.
|
|
Additional options, described above, may be specified on the procedure
|
|
line or in the option database to configure aspects of the scrollbar
|
|
such as its colors, orientation, and relief.
|
|
The <B>scrollbar</B> procedure returns its <I>widget-name</I> argument.
|
|
At the time this procedure is invoked, there must not exist a window
|
|
named <I>widget-name</I>, but <I>widget-name</I>'s parent must exist.
|
|
<P>
|
|
A scrollbar is a widget that displays two arrows, one at each end of
|
|
the scrollbar, and a <I>slider</I> in the middle portion of the
|
|
scrollbar.
|
|
It provides information about what is visible in an <I>associated window</I>
|
|
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>
|
|
Scrollbars can be used to adjust the view in the associated window
|
|
by clicking or dragging with the mouse. See the BINDINGS section
|
|
below for details.
|
|
|
|
<H3><A NAME="M24">ELEMENTS</A></H3>
|
|
A scrollbar displays five elements, which are referred to in the
|
|
widget procedures for the scrollbar:
|
|
<P>
|
|
<DL>
|
|
<DT><A NAME="M25"><B>arrow1</B></A><DD>
|
|
The top or left arrow in the scrollbar.
|
|
<P>
|
|
<DT><A NAME="M26"><B>trough1</B></A><DD>
|
|
The region between the slider and <B>arrow1</B>.
|
|
<P>
|
|
<DT><A NAME="M27"><B>slider</B></A><DD>
|
|
The rectangle that indicates what is visible in the associated widget.
|
|
<P>
|
|
<DT><A NAME="M28"><B>trough2</B></A><DD>
|
|
The region between the slider and <B>arrow2</B>.
|
|
<P>
|
|
<DT><A NAME="M29"><B>arrow2</B></A><DD>
|
|
The bottom or right arrow in the scrollbar.
|
|
|
|
<P>
|
|
</DL>
|
|
<H3><A NAME="M30">WIDGET PROCEDURE</A></H3>
|
|
The <B>scrollbar</B> procedure creates a new STk procedure whose
|
|
name is <I>widget-name</I>. This
|
|
procedure may be used to invoke various
|
|
operations on the widget. It has the following general form:
|
|
<PRE>(<I>widget-name option </I>?<I>arg arg ...</I>?)</PRE>
|
|
<I>Option</I> and the <I>arg</I>s
|
|
determine the exact behavior of the procedure. The following
|
|
procedures are possible for scrollbar widgets:
|
|
<P>
|
|
<DL>
|
|
<DT><A NAME="M31">(<I>widget-name '</I><B>activate </B>)</A><DD>
|
|
<DT><A NAME="M32">(<I>widget-name '</I><B>activate </B><I>element</I>)</A><DD>
|
|
Marks the element indicated by <I>element</I> as active, which
|
|
causes it to be displayed as specified by the <B>activeBackground</B>
|
|
and <B>activeRelief</B> options.
|
|
The only element values understood by this procedure are <B>arrow1</B>,
|
|
<B>slider</B>, or <B>arrow2</B>.
|
|
If any other value is specified then no element of the scrollbar
|
|
will be active.
|
|
If <I>element</I> is not specified, the procedure returns
|
|
the name of the element that is currently active, or an empty list
|
|
if no element is active.
|
|
<P>
|
|
<DT><A NAME="M33">(<I>widget-name '</I><B>cget</B> <I>option</I>)</A><DD>
|
|
Returns the current value of the configuration option given
|
|
by <I>option</I>.
|
|
<I>Option</I> may have any of the values accepted by the <B>scrollbar</B>
|
|
procedure.
|
|
<P>
|
|
<DT><A NAME="M34">(<I>widget-name '</I><B>configure</B> ?<I>option</I>? ?<I>value option value ...</I>?)</A><DD>
|
|
Query or modify the configuration options of the widget.
|
|
If no <I>option</I> is specified, returns a list describing all of
|
|
the available options for <I>widget-name</I> (see <B>Tk_ConfigureInfo</B> for
|
|
information on the format of this list). If <I>option</I> is specified
|
|
with no <I>value</I>, then the procedure returns a list describing the
|
|
one named option (this list will be identical to the corresponding
|
|
sublist of the value returned if no <I>option</I> is specified). If
|
|
one or more <I>option-value</I> pairs are specified, then the procedure
|
|
modifies the given widget option(s) to have the given value(s); in
|
|
this case the procedure returns an empty string.
|
|
<I>Option</I> may have any of the values accepted by the <B>scrollbar</B>
|
|
procedure.
|
|
<P>
|
|
<DT><A NAME="M35">(<I>widget-name '</I><B>delta </B><I>deltaX deltaY</I>)</A><DD>
|
|
Returns 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 <I>deltaX</I> pixels to the right (<I>deltaY</I> is
|
|
ignored in this case).
|
|
If the scrollbar is vertical, the result indicates how much the
|
|
scrollbar setting must change to move the slider <I>deltaY</I> pixels
|
|
down. The arguments and the result may be zero or negative.
|
|
<P>
|
|
<DT><A NAME="M36">(<I>widget-name '</I><B>fraction </B><I>x y</I>)</A><DD>
|
|
Returns a real number between 0 and 1 indicating where the point
|
|
given by <I>x</I> and <I>y</I> 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.
|
|
<I>X</I> and <I>y</I> must be pixel coordinates relative to the scrollbar
|
|
widget.
|
|
If <I>x</I> and <I>y</I> refer to a point outside the trough, the closest
|
|
point in the trough is used.
|
|
<P>
|
|
<DT><A NAME="M37">(<I>widget-name '</I><B>get</B>)</A><DD>
|
|
Returns the scrollbar settings in the form of a list whose
|
|
elements are the arguments to the most recent <B>set</B> widget procedure.
|
|
<P>
|
|
<DT><A NAME="M38">(<I>widget-name '</I><B>identify</B> <I>x y</I>)</A><DD>
|
|
Returns the name of the element under the point given by <I>x</I> and
|
|
<I>y</I> (such as <B>"arrow1"</B>), or <B>#f</B>if the point does
|
|
not lie in any element of the scrollbar.
|
|
<I>X</I> and <I>y</I> must be pixel coordinates relative to the scrollbar
|
|
widget.
|
|
<P>
|
|
<DT><A NAME="M39">(<I>widget-name '</I><B>set</B> <I>first last</I>)</A><DD>
|
|
This procedure is invoked by the scrollbar's associated widget to
|
|
tell the scrollbar about the current view in the widget.
|
|
The procedure takes two arguments, each of which is a real fraction
|
|
between 0 and 1.
|
|
The fractions describe the range of the document that is visible in
|
|
the associated widget.
|
|
For example, if <I>first</I> is 0.2 and <I>last</I> is 0.4, it means
|
|
that the first part of the document visible in the window is 20%
|
|
of the way through the document, and the last visible part is 40%
|
|
of the way through.
|
|
|
|
<P>
|
|
</DL>
|
|
<H3><A NAME="M40">SCROLLING PROCEDURES</A></H3>
|
|
When the user interacts with the scrollbar, for example by dragging
|
|
the slider, the scrollbar notifies the associated widget that it
|
|
must change its view.
|
|
The scrollbar makes the notification by calling the STk procedure
|
|
given to the scrollbar's \fB\:command\fR option. The parameters
|
|
passed to the procedure may take any of the following forms:
|
|
<P>
|
|
<DL>
|
|
<DT><A NAME="M41">'<B>moveto </B><I>fraction</I></A><DD>
|
|
<I>Fraction</I> is a real number between 0 and 1.
|
|
The widget should adjust its view so that the point given
|
|
by <I>fraction</I> appears at the beginning of the widget.
|
|
If <I>fraction</I> is 0 it refers to the beginning of the
|
|
document. 1.0 refers to the end of the document, 0.333
|
|
refers to a point one-third of the way through the document,
|
|
and so on.
|
|
<P>
|
|
<DT><A NAME="M42">'<B>scroll </B><I>number '</I><B>units</B></A><DD>
|
|
The widget should adjust its view by <I>number</I> units.
|
|
The units are defined in whatever way makes sense for the widget,
|
|
such as characters or lines in a text widget.
|
|
<I>Number</I> is either 1, which means one unit should scroll off
|
|
the top or left of the window, or -1, which means that one unit
|
|
should scroll off the bottom or right of the window.
|
|
<P>
|
|
<DT><A NAME="M43">'<B>scroll </B><I>number '</I><B>pages</B></A><DD>
|
|
The widget should adjust its view by <I>number</I> pages.
|
|
It is up to the widget to define the meaning of a page; typically
|
|
it is slightly less than what fits in the window, so that there
|
|
is a slight overlap between the old and new views.
|
|
<I>Number</I> is either 1, which means the next page should
|
|
become visible, or -1, which means that the previous page should
|
|
become visible.
|
|
|
|
<P>
|
|
</DL>
|
|
<H3><A NAME="M44">OLD PROCEDURE SYNTAX</A></H3>
|
|
In versions of Tk before 4.0, the <B>set</B> and <B>get</B> widget
|
|
procedures used a different form.
|
|
This form is still supported for backward compatibility, but it
|
|
is deprecated.
|
|
In the old procedure syntax, the <B>set</B> widget procedure has the
|
|
following form:
|
|
<P>
|
|
<DL>
|
|
<DT><A NAME="M45">(<I>widget-name '</I><B>set</B> <I>totalUnits windowUnits firstUnit lastUnit</I>)</A><DD>
|
|
In this form the arguments are all integers.
|
|
<I>TotalUnits</I> gives the total size of the object being displayed in the
|
|
associated widget. The meaning of one unit depends on the associated
|
|
widget; for example, in a text editor widget units might
|
|
correspond to lines of
|
|
text. <I>WindowUnits</I> indicates the total number of units that
|
|
can fit in the associated window at one time. <I>FirstUnit</I>
|
|
and <I>lastUnit</I> give the indices of the first and last units
|
|
currently visible in the associated window (zero corresponds to the
|
|
first unit of the object).
|
|
<P>
|
|
</DL>
|
|
<P>
|
|
Under the old syntax the <B>get</B> widget procedure returns a list
|
|
of four integers, consisting of the <I>totalUnits</I>, <I>windowUnits</I>,
|
|
<I>firstUnit</I>, and <I>lastUnit</I> values from the last <B>set</B>
|
|
widget procedure.
|
|
<P>
|
|
The procedures generated by scrollbars also have a different form
|
|
when the old syntax is being used: a single parameter is passed to
|
|
the procedure given to the <B>:command</B> option. This integer
|
|
indicates what should appear at
|
|
the top or left of the associated widget's window.
|
|
It has the same meaning as the <I>firstUnit</I> and <I>lastUnit</I>
|
|
arguments to the <B>set</B> widget procedure.
|
|
<P>
|
|
The most recent <B>set</B> widget procedure determines whether or not
|
|
to use the old syntax.
|
|
If it is given two real arguments then the new syntax will be
|
|
used in the future, and if it is given four integer arguments then
|
|
the old syntax will be used.
|
|
|
|
<H3><A NAME="M46">EXAMPLE</A></H3>
|
|
The following example shows a procedure which is compatible with
|
|
the old and new syntax for procedure scrolling discussed earlier:
|
|
<PRE>.;; Create list box and scrollbar
|
|
(listbox '.l :height 5
|
|
:yscroll (lambda l (apply .s 'set l)))
|
|
(scrollbar '.s :command (lambda l (apply .l 'yview l)))
|
|
|
|
;; Set some elements in the listbox
|
|
(.l 'insert 0 'one 'two 'three 'four 'five 'six 'seven 'eight)
|
|
|
|
;; Pack elements
|
|
(pack .l :side "left" :expand #t :fill "both")
|
|
(pack .s :side "right" :expand #f :fill "y")</PRE>
|
|
Using apply and a variable length list of parameters for the scrollbar
|
|
procedure is compatible with old and new scrollbar procedure syntax.
|
|
|
|
<H3><A NAME="M47">BINDINGS</A></H3>
|
|
Tk automatically creates class bindings for scrollbars that give them
|
|
the following default behavior.
|
|
If the behavior is different for vertical and horizontal scrollbars,
|
|
the horizontal behavior is described in parentheses.
|
|
|
|
<P>
|
|
<DL>
|
|
<DT><A NAME="M48">{[1]}</A><DD>
|
|
Pressing button 1 over <B>arrow1</B> causes the view in the
|
|
associated widget to shift up (left) by one unit so that the
|
|
document appears to move down (right) one unit.
|
|
If the button is held down, the action auto-repeats.
|
|
<P>
|
|
<DT><A NAME="M49">{[2]}</A><DD>
|
|
Pressing button 1 over <B>trough1</B> causes the view in the
|
|
associated widget to shift up (left) by one screenful so that the
|
|
document appears to move down (right) one screenful.
|
|
If the button is held down, the action auto-repeats.
|
|
<P>
|
|
<DT><A NAME="M50">{[3]}</A><DD>
|
|
Pressing button 1 over the slider and dragging causes the view
|
|
to drag with the slider.
|
|
If the <B>jump</B> option is true, then the view doesn't drag along
|
|
with the slider; it changes only when the mouse button is released.
|
|
<P>
|
|
<DT><A NAME="M51">{[4]}</A><DD>
|
|
Pressing button 1 over <B>trough2</B> causes the view in the
|
|
associated widget to shift down (right) by one screenful so that the
|
|
document appears to move up (left) one screenful.
|
|
If the button is held down, the action auto-repeats.
|
|
<P>
|
|
<DT><A NAME="M52">{[5]}</A><DD>
|
|
Pressing button 1 over <B>arrow2</B> causes the view in the
|
|
associated widget to shift down (right) by one unit so that the
|
|
document appears to move up (left) one unit.
|
|
If the button is held down, the action auto-repeats.
|
|
<P>
|
|
<DT><A NAME="M53">{[6]}</A><DD>
|
|
If button 2 is pressed over the trough or the slider, it sets
|
|
the view to correspond to the mouse position; dragging the
|
|
mouse with button 2 down causes the view to drag with the mouse.
|
|
If button 2 is pressed over one of the arrows, it causes the
|
|
same behavior as pressing button 1.
|
|
<P>
|
|
<DT><A NAME="M54">{[7]}</A><DD>
|
|
If button 1 is pressed with the Control key down, then if the
|
|
mouse is over <B>arrow1</B> or <B>trough1</B> the view changes
|
|
to the very top (left) of the document; if the mouse is over
|
|
<B>arrow2</B> or <B>trough2</B> the view changes
|
|
to the very bottom (right) of the document; if the mouse is
|
|
anywhere else then the button press has no effect.
|
|
<P>
|
|
<DT><A NAME="M55">{[8]}</A><DD>
|
|
In vertical scrollbars the Up and Down keys have the same behavior
|
|
as mouse clicks over <B>arrow1</B> and <B>arrow2</B>, respectively.
|
|
In horizontal scrollbars these keys have no effect.
|
|
<P>
|
|
<DT><A NAME="M56">{[9]}</A><DD>
|
|
In vertical scrollbars Control-Up and Control-Down have the same
|
|
behavior as mouse clicks over <B>trough1</B> and <B>trough2</B>, respectively.
|
|
In horizontal scrollbars these keys have no effect.
|
|
<P>
|
|
<DT><A NAME="M57">{[10]}</A><DD>
|
|
In horizontal scrollbars the Up and Down keys have the same behavior
|
|
as mouse clicks over <B>arrow1</B> and <B>arrow2</B>, respectively.
|
|
In vertical scrollbars these keys have no effect.
|
|
<P>
|
|
<DT><A NAME="M58">{[11]}</A><DD>
|
|
In horizontal scrollbars Control-Up and Control-Down have the same
|
|
behavior as mouse clicks over <B>trough1</B> and <B>trough2</B>, respectively.
|
|
In vertical scrollbars these keys have no effect.
|
|
<P>
|
|
<DT><A NAME="M59">{[12]}</A><DD>
|
|
The Prior and Next keys have the same behavior
|
|
as mouse clicks over <B>trough1</B> and <B>trough2</B>, respectively.
|
|
<P>
|
|
<DT><A NAME="M60">{[13]}</A><DD>
|
|
The Home key adjusts the view to the top (left edge) of the document.
|
|
<P>
|
|
<DT><A NAME="M61">{[14]}</A><DD>
|
|
The End key adjusts the view to the bottom (right edge) of the document.
|
|
|
|
<P>
|
|
</DL>
|
|
<P><IMG ALIGN=TOP SRC="./Img/line-red.gif"><P>
|
|
<A HREF=./STk-hlp.html><IMG ALIGN=BOTTOM SRC="./Img/RefBookBlue.gif"> Back to the <B>STk</B> main page</A>
|
|
</BODY></HTML>
|