OpenCores
URL https://opencores.org/ocsvn/or1k/or1k/trunk

Subversion Repositories or1k

[/] [or1k/] [trunk/] [insight/] [tk/] [doc/] [scrollbar.n] - Blame information for rev 1765

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 578 markom
'\"
2
'\" Copyright (c) 1990-1994 The Regents of the University of California.
3
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
4
'\"
5
'\" See the file "license.terms" for information on usage and redistribution
6
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7
'\"
8
'\" RCS: @(#) $Id: scrollbar.n,v 1.1.1.1 2002-01-16 10:25:49 markom Exp $
9
'\"
10
.so man.macros
11
.TH scrollbar n 4.1 Tk "Tk Built-In Commands"
12
.BS
13
'\" Note:  do not modify the .SH NAME line immediately below!
14
.SH NAME
15
scrollbar \- Create and manipulate scrollbar widgets
16
.SH SYNOPSIS
17
\fBscrollbar\fR \fIpathName \fR?\fIoptions\fR?
18
.SO
19
\-activebackground      \-highlightbackground   \-orient        \-takefocus
20
\-background    \-highlightcolor        \-relief        \-troughcolor
21
\-borderwidth   \-highlightthickness    \-repeatdelay
22
\-cursor        \-jump  \-repeatinterval
23
.SE
24
.SH "WIDGET-SPECIFIC OPTIONS"
25
.OP \-activerelief activeRelief ActiveRelief
26
Specifies the relief to use when displaying the element that is
27
active, if any.
28
Elements other than the active element are always displayed with
29
a raised relief.
30
.OP \-command command Command
31
Specifies the prefix of a Tcl command to invoke to change the view
32
in the widget associated with the scrollbar.  When a user requests
33
a view change by manipulating the scrollbar, a Tcl command is
34
invoked.  The actual command consists of this option followed by
35
additional information as described later.  This option almost always has
36
a value such as \fB.t xview\fR or \fB.t yview\fR, consisting of the
37
name of a widget and either \fBxview\fR (if the scrollbar is for
38
horizontal scrolling) or \fByview\fR (for vertical scrolling).
39
All scrollable widgets have \fBxview\fR and \fByview\fR commands
40
that take exactly the additional arguments appended by the scrollbar
41
as described in SCROLLING COMMANDS below.
42
.OP \-elementborderwidth elementBorderWidth BorderWidth
43
Specifies the width of borders drawn around the internal elements
44
of the scrollbar (the two arrows and the slider).  The value may
45
have any of the forms acceptable to \fBTk_GetPixels\fR.
46
If this value is less than zero, the value of the \fBborderWidth\fR
47
option is used in its place.
48
.OP \-width width Width
49
Specifies the desired narrow dimension of the scrollbar window,
50
not including 3-D border, if any.  For vertical
51
scrollbars this will be the width and for horizontal scrollbars
52
this will be the height.
53
The value may have any of the forms acceptable to \fBTk_GetPixels\fR.
54
.BE
55
 
56
.SH DESCRIPTION
57
.PP
58
The \fBscrollbar\fR command creates a new window (given by the
59
\fIpathName\fR argument) and makes it into a scrollbar widget.
60
Additional options, described above, may be specified on the command
61
line or in the option database to configure aspects of the scrollbar
62
such as its colors, orientation, and relief.
63
The \fBscrollbar\fR command returns its \fIpathName\fR argument.
64
At the time this command is invoked, there must not exist a window
65
named \fIpathName\fR, but \fIpathName\fR's parent must exist.
66
.PP
67
A scrollbar is a widget that displays two arrows, one at each end of
68
the scrollbar, and a \fIslider\fR in the middle portion of the
69
scrollbar.
70
It provides information about what is visible in an \fIassociated window\fR
71
that displays an document of some sort (such as a file being edited or
72
a drawing).
73
The position and size of the slider indicate which portion of the
74
document is visible in the associated window.  For example, if the
75
slider in a vertical scrollbar covers the top third of the area
76
between the two arrows, it means that the associated window displays
77
the top third of its document.
78
.PP
79
Scrollbars can be used to adjust the view in the associated window
80
by clicking or dragging with the mouse.  See the BINDINGS section
81
below for details.
82
 
83
.SH "ELEMENTS"
84
.PP
85
A scrollbar displays five elements, which are referred to in the
86
widget commands for the scrollbar:
87
.TP 10
88
\fBarrow1\fR
89
The top or left arrow in the scrollbar.
90
.TP 10
91
\fBtrough1\fR
92
The region between the slider and \fBarrow1\fR.
93
.TP 10
94
\fBslider\fR
95
The rectangle that indicates what is visible in the associated widget.
96
.TP 10
97
\fBtrough2\fR
98
The region between the slider and \fBarrow2\fR.
99
.TP 10
100
\fBarrow2\fR
101
The bottom or right arrow in the scrollbar.
102
 
103
.SH "WIDGET COMMAND"
104
.PP
105
The \fBscrollbar\fR command creates a new Tcl command whose
106
name is \fIpathName\fR.  This
107
command may be used to invoke various
108
operations on the widget.  It has the following general form:
109
.CS
110
\fIpathName option \fR?\fIarg arg ...\fR?
111
.CE
112
\fIOption\fR and the \fIarg\fRs
113
determine the exact behavior of the command.  The following
114
commands are possible for scrollbar widgets:
115
.TP
116
\fIpathName \fBactivate \fR?\fIelement\fR?
117
Marks the element indicated by \fIelement\fR as active, which
118
causes it to be displayed as specified by the \fBactiveBackground\fR
119
and \fBactiveRelief\fR options.
120
The only element values understood by this command are \fBarrow1\fR,
121
\fBslider\fR, or \fBarrow2\fR.
122
If any other value is specified then no element of the scrollbar
123
will be active.
124
If \fIelement\fR is not specified, the command returns
125
the name of the element that is currently active, or an empty string
126
if no element is active.
127
.TP
128
\fIpathName \fBcget\fR \fIoption\fR
129
Returns the current value of the configuration option given
130
by \fIoption\fR.
131
\fIOption\fR may have any of the values accepted by the \fBscrollbar\fR
132
command.
133
.TP
134
\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
135
Query or modify the configuration options of the widget.
136
If no \fIoption\fR is specified, returns a list describing all of
137
the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for
138
information on the format of this list).  If \fIoption\fR is specified
139
with no \fIvalue\fR, then the command returns a list describing the
140
one named option (this list will be identical to the corresponding
141
sublist of the value returned if no \fIoption\fR is specified).  If
142
one or more \fIoption\-value\fR pairs are specified, then the command
143
modifies the given widget option(s) to have the given value(s);  in
144
this case the command returns an empty string.
145
\fIOption\fR may have any of the values accepted by the \fBscrollbar\fR
146
command.
147
.TP
148
\fIpathName \fBdelta \fIdeltaX deltaY\fR
149
Returns a real number indicating the fractional change in
150
the scrollbar setting that corresponds to a given change
151
in slider position.  For example, if the scrollbar is horizontal,
152
the result indicates how much the scrollbar setting must change
153
to move the slider \fIdeltaX\fR pixels to the right (\fIdeltaY\fR is
154
ignored in this case).
155
If the scrollbar is vertical, the result indicates how much the
156
scrollbar setting must change to move the slider \fIdeltaY\fR pixels
157
down.  The arguments and the result may be zero or negative.
158
.TP
159
\fIpathName \fBfraction \fIx y\fR
160
Returns a real number between 0 and 1 indicating where the point
161
given by \fIx\fR and \fIy\fR lies in the trough area of the scrollbar.
162
The value 0 corresponds to the top or left of the trough, the
163
value 1 corresponds to the bottom or right, 0.5 corresponds to
164
the middle, and so on.
165
\fIX\fR and \fIy\fR must be pixel coordinates relative to the scrollbar
166
widget.
167
If \fIx\fR and \fIy\fR refer to a point outside the trough, the closest
168
point in the trough is used.
169
.TP
170
\fIpathName \fBget\fR
171
Returns the scrollbar settings in the form of a list whose
172
elements are the arguments to the most recent \fBset\fR widget command.
173
.TP
174
\fIpathName \fBidentify\fR \fIx y\fR
175
Returns the name of the element under the point given by \fIx\fR and
176
\fIy\fR (such as \fBarrow1\fR), or an empty string if the point does
177
not lie in any element of the scrollbar.
178
\fIX\fR and \fIy\fR must be pixel coordinates relative to the scrollbar
179
widget.
180
.TP
181
\fIpathName \fBset\fR \fIfirst last\fR
182
This command is invoked by the scrollbar's associated widget to
183
tell the scrollbar about the current view in the widget.
184
The command takes two arguments, each of which is a real fraction
185
between 0 and 1.
186
The fractions describe the range of the document that is visible in
187
the associated widget.
188
For example, if \fIfirst\fR is 0.2 and \fIlast\fR is 0.4, it means
189
that the first part of the document visible in the window is 20%
190
of the way through the document, and the last visible part is 40%
191
of the way through.
192
 
193
.SH "SCROLLING COMMANDS"
194
.PP
195
When the user interacts with the scrollbar, for example by dragging
196
the slider, the scrollbar notifies the associated widget that it
197
must change its view.
198
The scrollbar makes the notification by evaluating a Tcl command
199
generated from the scrollbar's \fB\-command\fR option.
200
The command may take any of the following forms.
201
In each case, \fIprefix\fR is the contents of the
202
\fB\-command\fR option, which usually has a form like \fB.t yview\fR
203
.TP
204
\fIprefix \fBmoveto \fIfraction\fR
205
\fIFraction\fR is a real number between 0 and 1.
206
The widget should adjust its view so that the point given
207
by \fIfraction\fR appears at the beginning of the widget.
208
If \fIfraction\fR is 0 it refers to the beginning of the
209
document.  1.0 refers to the end of the document, 0.333
210
refers to a point one-third of the way through the document,
211
and so on.
212
.TP
213
\fIprefix \fBscroll \fInumber \fBunits\fR
214
The widget should adjust its view by \fInumber\fR units.
215
The units are defined in whatever way makes sense for the widget,
216
such as characters or lines in a text widget.
217
\fINumber\fR is either 1, which means one unit should scroll off
218
the top or left of the window, or \-1, which means that one unit
219
should scroll off the bottom or right of the window.
220
.TP
221
\fIprefix \fBscroll \fInumber \fBpages\fR
222
The widget should adjust its view by \fInumber\fR pages.
223
It is up to the widget to define the meaning of a page;  typically
224
it is slightly less than what fits in the window, so that there
225
is a slight overlap between the old and new views.
226
\fINumber\fR is either 1, which means the next page should
227
become visible, or \-1, which means that the previous page should
228
become visible.
229
 
230
.SH "OLD COMMAND SYNTAX"
231
.PP
232
In versions of Tk before 4.0, the \fBset\fR and \fBget\fR widget
233
commands used a different form.
234
This form is still supported for backward compatibility, but it
235
is deprecated.
236
In the old command syntax, the \fBset\fR widget command has the
237
following form:
238
.TP
239
\fIpathName \fBset\fR \fItotalUnits windowUnits firstUnit lastUnit\fR
240
In this form the arguments are all integers.
241
\fITotalUnits\fR gives the total size of the object being displayed in the
242
associated widget.  The meaning of one unit depends on the associated
243
widget;  for example, in a text editor widget units might
244
correspond to lines of
245
text.  \fIWindowUnits\fR indicates the total number of units that
246
can fit in the associated window at one time.  \fIFirstUnit\fR
247
and \fIlastUnit\fR give the indices of the first and last units
248
currently visible in the associated window (zero corresponds to the
249
first unit of the object).
250
.LP
251
Under the old syntax the \fBget\fR widget command returns a list
252
of four integers, consisting of the \fItotalUnits\fR, \fIwindowUnits\fR,
253
\fIfirstUnit\fR, and \fIlastUnit\fR values from the last \fBset\fR
254
widget command.
255
.PP
256
The commands generated by scrollbars also have a different form
257
when the old syntax is being used:
258
.TP
259
\fIprefix\fR \fIunit\fR
260
\fIUnit\fR is an integer that indicates what should appear at
261
the top or left of the associated widget's window.
262
It has the same meaning as the \fIfirstUnit\fR and \fIlastUnit\fR
263
arguments to the \fBset\fR widget command.
264
.LP
265
The most recent \fBset\fR widget command determines whether or not
266
to use the old syntax.
267
If it is given two real arguments then the new syntax will be
268
used in the future, and if it is given four integer arguments then
269
the old syntax will be used.
270
 
271
.SH BINDINGS
272
Tk automatically creates class bindings for scrollbars that give them
273
the following default behavior.
274
If the behavior is different for vertical and horizontal scrollbars,
275
the horizontal behavior is described in parentheses.
276
 
277
.IP [1]
278
Pressing button 1 over \fBarrow1\fR causes the view in the
279
associated widget to shift up (left) by one unit so that the
280
document appears to move down (right) one unit.
281
If the button is held down, the action auto-repeats.
282
.IP [2]
283
Pressing button 1 over \fBtrough1\fR causes the view in the
284
associated widget to shift up (left) by one screenful so that the
285
document appears to move down (right) one screenful.
286
If the button is held down, the action auto-repeats.
287
.IP [3]
288
Pressing button 1 over the slider and dragging causes the view
289
to drag with the slider.
290
If the \fBjump\fR option is true, then the view doesn't drag along
291
with the slider;  it changes only when the mouse button is released.
292
.IP [4]
293
Pressing button 1 over \fBtrough2\fR causes the view in the
294
associated widget to shift down (right) by one screenful so that the
295
document appears to move up (left) one screenful.
296
If the button is held down, the action auto-repeats.
297
.IP [5]
298
Pressing button 1 over \fBarrow2\fR causes the view in the
299
associated widget to shift down (right) by one unit so that the
300
document appears to move up (left) one unit.
301
If the button is held down, the action auto-repeats.
302
.IP [6]
303
If button 2 is pressed over the trough or the slider, it sets
304
the view to correspond to the mouse position;  dragging the
305
mouse with button 2 down causes the view to drag with the mouse.
306
If button 2 is pressed over one of the arrows, it causes the
307
same behavior as pressing button 1.
308
.IP [7]
309
If button 1 is pressed with the Control key down, then if the
310
mouse is over \fBarrow1\fR or \fBtrough1\fR the view changes
311
to the very top (left) of the document;  if the mouse is over
312
\fBarrow2\fR or \fBtrough2\fR the view changes
313
to the very bottom (right) of the document;  if the mouse is
314
anywhere else then the button press has no effect.
315
.IP [8]
316
In vertical scrollbars the Up and Down keys have the same behavior
317
as mouse clicks over \fBarrow1\fR and \fBarrow2\fR, respectively.
318
In horizontal scrollbars these keys have no effect.
319
.IP [9]
320
In vertical scrollbars Control-Up and Control-Down have the same
321
behavior as mouse clicks over \fBtrough1\fR and \fBtrough2\fR, respectively.
322
In horizontal scrollbars these keys have no effect.
323
.IP [10]
324
In horizontal scrollbars the Up and Down keys have the same behavior
325
as mouse clicks over \fBarrow1\fR and \fBarrow2\fR, respectively.
326
In vertical scrollbars these keys have no effect.
327
.IP [11]
328
In horizontal scrollbars Control-Up and Control-Down have the same
329
behavior as mouse clicks over \fBtrough1\fR and \fBtrough2\fR, respectively.
330
In vertical scrollbars these keys have no effect.
331
.IP [12]
332
The Prior and Next keys have the same behavior
333
as mouse clicks over \fBtrough1\fR and \fBtrough2\fR, respectively.
334
.IP [13]
335
The Home key adjusts the view to the top (left edge) of the document.
336
.IP [14]
337
The End key adjusts the view to the bottom (right edge) of the document.
338
 
339
.SH KEYWORDS
340
scrollbar, widget

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.