summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Tk/Scrollbar.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/Scrollbar.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Scrollbar.pod429
1 files changed, 429 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/Scrollbar.pod b/Master/tlpkg/tlperl/lib/Tk/Scrollbar.pod
new file mode 100644
index 00000000000..838eb97e666
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Tk/Scrollbar.pod
@@ -0,0 +1,429 @@
+# Copyright (c) 1990-1994 The Regents of the University of California.
+# Copyright (c) 1994-1996 Sun Microsystems, Inc.
+# See the file "license.terms" for information on usage and redistribution
+# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+#
+#
+
+=head1 NAME
+
+Tk::Scrollbar - Create and manipulate Scrollbar widgets
+
+=for category Tk Widget Classes
+
+=head1 SYNOPSIS
+
+I<$scrollbar> = I<$parent>-E<gt>B<Scrollbar>(?I<options>?);
+
+=head1 STANDARD OPTIONS
+
+B<-activebackground> B<-highlightbackground> B<-orient> B<-takefocus>
+B<-background> B<-highlightcolor> B<-relief> B<-troughcolor>
+B<-borderwidth> B<-highlightthickness> B<-repeatdelay>
+B<-cursor> B<-jump> B<-repeatinterval>
+
+See L<Tk::options> for details of the standard options.
+
+=head1 WIDGET-SPECIFIC OPTIONS
+
+=over 4
+
+=item Name: B<activeRelief>
+
+=item Class: B<ActiveRelief>
+
+=item Switch: B<-activerelief>
+
+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.
+
+=item Name: B<command>
+
+=item Class: B<Command>
+
+=item Switch: B<-command>
+
+Specifies a callback 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 callback is
+invoked. The callback is passed
+additional arguments as described later. This option almost always has
+a value such as B<[xview =E<gt> $widget]> or B<[yview =E<gt> $widget]>, consisting of the
+a widget object and either B<xview> (if the scrollbar is for
+horizontal scrolling) or B<yview> (for vertical scrolling).
+All scrollable widgets have B<xview> and B<yview> methods
+that take exactly the additional arguments appended by the scrollbar
+as described in L<"SCROLLING COMMANDS"> below.
+
+=item Name: B<elementBorderWidth>
+
+=item Class: B<BorderWidth>
+
+=item Switch: B<-elementborderwidth>
+
+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>.
+If this value is less than zero, the value of the B<borderWidth>
+option is used in its place.
+
+=item Name: B<width>
+
+=item Class: B<Width>
+
+=item Switch: B<-width>
+
+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>.
+
+=back
+
+=head1 DESCRIPTION
+
+The B<Scrollbar> method creates a new window (given by the
+$widget argument) and makes it into a scrollbar widget.
+Additional options, described above, may be specified on the command
+line or in the option database to configure aspects of the scrollbar
+such as its colors, orientation, and relief.
+The B<scrollbar> command returns its $widget argument.
+At the time this command is invoked, there must not exist a window
+named $widget, but $widget's parent must exist.
+
+A scrollbar is a widget that displays two arrows, one at each end of
+the scrollbar, and a I<slider> in the middle portion of the
+scrollbar.
+It provides information about what is visible in an I<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.
+
+Scrollbars can be used to adjust the view in the associated window
+by clicking or dragging with the mouse.
+See L<"BINDINGS"> below for details.
+
+=head1 ELEMENTS
+
+A scrollbar displays five elements, which are referred to in the
+methods for the scrollbar:
+
+=over 4
+
+=item B<arrow1>
+
+The top or left arrow in the scrollbar.
+
+=item B<trough1>
+
+The region between the slider and B<arrow1>.
+
+=item B<slider>
+
+The rectangle that indicates what is visible in the associated widget.
+
+=item B<trough2>
+
+The region between the slider and B<arrow2>.
+
+=item B<arrow2>
+
+The bottom or right arrow in the scrollbar.
+
+=back
+
+=head1 WIDGET METHODS
+
+The B<Scrollbar> method creates a widget object.
+This object supports the B<configure> and B<cget> methods
+described in L<Tk::options> which can be used to enquire and
+modify the options described above.
+The widget also inherits all the methods provided by the generic
+L<Tk::Widget|Tk::Widget> class.
+
+The following additional methods are available for scrollbar widgets:
+
+=over 4
+
+=item I<$scrollbar>-E<gt>B<activate>(?I<element>?)
+
+Marks the element indicated by I<element> as active, which
+causes it to be displayed as specified by the B<activeBackground>
+and B<activeRelief> options.
+The only element values understood by this command are B<arrow1>,
+B<slider>, or B<arrow2>.
+If any other value is specified then no element of the scrollbar
+will be active.
+If I<element> is not specified, the command returns
+the name of the element that is currently active, or an empty string
+if no element is active.
+
+=item I<$scrollbar>-E<gt>B<delta>(I<deltaX, deltaY>)
+
+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> pixels to the right (I<deltaY> 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> pixels
+down. The arguments and the result may be zero or negative.
+
+=item I<$scrollbar>-E<gt>B<fraction>(I<x, y>)
+
+Returns a real number between 0 and 1 indicating where the point
+given by I<x> and I<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.
+I<X> and I<y> must be pixel coordinates relative to the scrollbar
+widget.
+If I<x> and I<y> refer to a point outside the trough, the closest
+point in the trough is used.
+
+=item I<$scrollbar>-E<gt>B<get>
+
+Returns the scrollbar settings in the form of a list whose
+elements are the arguments to the most recent B<set> method.
+
+=item I<$scrollbar>-E<gt>B<identify>(I<x, y>)
+
+Returns the name of the element under the point given by I<x> and
+I<y> (such as B<arrow1>), or an empty string if the point does
+not lie in any element of the scrollbar.
+I<X> and I<y> must be pixel coordinates relative to the scrollbar
+widget.
+
+=item I<$scrollbar>-E<gt>B<set>(I<first, last>)
+
+This command is invoked by the scrollbar's associated widget to
+tell the scrollbar about the current view in the widget.
+The command 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> is 0.2 and I<last> 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.
+
+=back
+
+=head1 SCROLLING COMMANDS
+
+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 evaluating a callback
+specified as the scrollbar's B<-command> option.
+The callback may take several forms.
+In each case, the intial arguments passed are those
+specified in the B<-command> callback itself,
+which usually has a form like [B<yview> =E<gt> I<$widget>].
+(Which will invoke I<$widget>-E<gt>B<yview>(...) where
+the ... part is as below. See L<Tk::callbacks> for details.)
+The callback is passed additional arguments as follows:
+
+=over 4
+
+=item B<moveto>,I<fraction>
+
+I<Fraction> is a real number between 0 and 1.
+The widget should adjust its view so that the point given
+by I<fraction> appears at the beginning of the widget.
+If I<fraction> 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.
+
+=item B<scroll,>I<number,>B<units>
+
+The widget should adjust its view by I<number> units.
+The units are defined in whatever way makes sense for the widget,
+such as characters or lines in a text widget.
+I<Number> 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.
+
+=item B<scroll>,I<number>,B<page>
+
+The widget should adjust its view by I<number> 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> is either 1, which means the next page should
+become visible, or -1, which means that the previous page should
+become visible.
+
+=back
+
+=head1 OLD COMMAND SYNTAX
+
+In versions of Tk before 4.0, the B<set> and B<get> widget
+commands used a different form.
+This form is still supported for backward compatibility, but it
+is deprecated.
+In the old command syntax, the B<set> method has the
+following form:
+
+=over 4
+
+=item I<$scrollbar>-E<gt>B<set>(I<totalUnits, windowUnits, firstUnit, lastUnit>)
+
+In this form the arguments are all integers.
+I<TotalUnits> 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> indicates the total number of units that
+can fit in the associated window at one time. I<FirstUnit>
+and I<lastUnit> give the indices of the first and last units
+currently visible in the associated window (zero corresponds to the
+first unit of the object).
+
+=back
+
+Under the old syntax the B<get> method returns a list
+of four integers, consisting of the I<totalUnits>, I<windowUnits>,
+I<firstUnit>, and I<lastUnit> values from the last B<set>
+method.
+
+The callbacks generated by scrollbars also have a different form
+when the old syntax is being used, the callback is passed a single argument:
+
+=over 4
+
+=item I<unit>
+
+I<Unit> is an integer that indicates what should appear at
+the top or left of the associated widget's window.
+It has the same meaning as the I<firstUnit> and I<lastUnit>
+arguments to the B<set> method.
+
+=back
+
+The most recent B<set> method 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.
+
+=head1 BINDINGS
+
+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.
+
+=over 4
+
+=item [1]
+
+Pressing button 1 over B<arrow1> 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.
+
+=item [2]
+
+Pressing button 1 over B<trough1> 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.
+
+=item [3]
+
+Pressing button 1 over the slider and dragging causes the view
+to drag with the slider.
+If the B<jump> option is true, then the view doesn't drag along
+with the slider; it changes only when the mouse button is released.
+
+=item [4]
+
+Pressing button 1 over B<trough2> 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.
+
+=item [5]
+
+Pressing button 1 over B<arrow2> 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.
+
+=item [6]
+
+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.
+
+=item [7]
+
+If button 1 is pressed with the Control key down, then if the
+mouse is over B<arrow1> or B<trough1> the view changes
+to the very top (left) of the document; if the mouse is over
+B<arrow2> or B<trough2> the view changes
+to the very bottom (right) of the document; if the mouse is
+anywhere else then the button press has no effect.
+
+=item [8]
+
+In vertical scrollbars the Up and Down keys have the same behavior
+as mouse clicks over B<arrow1> and B<arrow2>, respectively.
+In horizontal scrollbars these keys have no effect.
+
+=item [9]
+
+In vertical scrollbars Control-Up and Control-Down have the same
+behavior as mouse clicks over B<trough1> and B<trough2>, respectively.
+In horizontal scrollbars these keys have no effect.
+
+=item [10]
+
+In horizontal scrollbars the Up and Down keys have the same behavior
+as mouse clicks over B<arrow1> and B<arrow2>, respectively.
+In vertical scrollbars these keys have no effect.
+
+=item [11]
+
+In horizontal scrollbars Control-Up and Control-Down have the same
+behavior as mouse clicks over B<trough1> and B<trough2>, respectively.
+In vertical scrollbars these keys have no effect.
+
+=item [12]
+
+The Prior and Next keys have the same behavior
+as mouse clicks over B<trough1> and B<trough2>, respectively.
+
+=item [13]
+
+The Home key adjusts the view to the top (left edge) of the document.
+
+=item [14]
+
+The End key adjusts the view to the bottom (right edge) of the document.
+
+=back
+
+=head1 SEE ALSO
+
+L<Tk::callbacks|Tk::callbacks>
+L<Tk::Scrolled|Tk::Scrolled>
+
+=head1 KEYWORDS
+
+scrollbar, widget
+
+=cut
+