Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Scrollbar(3)	      User Contributed Perl Documentation	  Scrollbar(3)

NAME
       Tk::Scrollbar - Create and manipulate Scrollbar widgets

SYNOPSIS
       $scrollbar = $parent->Scrollbar(?options?);

STANDARD OPTIONS
       -activebackground   -highlightbackground	    -orient   -takefocus
       -background    -highlightcolor	  -relief   -troughcolor
       -borderwidth   -highlightthickness -repeatdelay
       -cursor	 -jump	   -repeatinterval

       See Tk::options for details of the standard options.

WIDGET-SPECIFIC	OPTIONS
       Name:	 activeRelief
       Class:	 ActiveRelief
       Switch:	 -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.

       Name:	 command
       Class:	 Command
       Switch:	 -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 [xview => $widget] or
	   [yview => $widget], consisting of the a widget object and either
	   xview (if the scrollbar is for horizontal scrolling)	or yview (for
	   vertical scrolling).	 All scrollable	widgets	have xview and yview
	   methods that	take exactly the additional arguments appended by the
	   scrollbar as	described in "SCROLLING	COMMANDS" below.

       Name:	 elementBorderWidth
       Class:	 BorderWidth
       Switch:	 -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 Tk_GetPixels.  If this value is
	   less	than zero, the value of	the borderWidth	option is used in its
	   place.

       Name:	 width
       Class:	 Width
       Switch:	 -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 Tk_GetPixels.

DESCRIPTION
       The 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 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 slider in the middle portion of the	scrollbar.  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.

       Scrollbars can be used to adjust	the view in the	associated window by
       clicking	or dragging with the mouse.  See "BINDINGS" below for details.

ELEMENTS
       A scrollbar displays five elements, which are referred to in the
       methods for the scrollbar:

       arrow1
	   The top or left arrow in the	scrollbar.

       trough1
	   The region between the slider and arrow1.

       slider
	   The rectangle that indicates	what is	visible	in the associated
	   widget.

       trough2
	   The region between the slider and arrow2.

       arrow2
	   The bottom or right arrow in	the scrollbar.

WIDGET METHODS
       The Scrollbar method creates a widget object.  This object supports the
       configure and cget methods described in 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	Tk::Widget class.

       The following additional	methods	are available for scrollbar widgets:

       $scrollbar->activate(?element?)
	   Marks the element indicated by element as active, which causes it
	   to be displayed as specified	by the activeBackground	and
	   activeRelief	options.  The only element values understood by	this
	   command are arrow1, slider, or arrow2.  If any other	value is
	   specified then no element of	the scrollbar will be active.  If
	   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.

       $scrollbar->delta(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 deltaX pixels	to the right (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 deltaY pixels
	   down.  The arguments	and the	result may be zero or negative.

       $scrollbar->fraction(x, y)
	   Returns 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.

       $scrollbar->get
	   Returns the scrollbar settings in the form of a list	whose elements
	   are the arguments to	the most recent	set method.

       $scrollbar->identify(x, y)
	   Returns 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.

       $scrollbar->set(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 first is
	   0.2 and 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.

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 -command option.  The callback
       may take	several	forms.	In each	case, the intial arguments passed are
       those specified in the -command callback	itself,	which usually has a
       form like [yview	=> $widget].  (Which will invoke $widget->yview(...)
       where the ... part is as	below. See Tk::callbacks for details.)	The
       callback	is passed additional arguments as follows:

       moveto,fraction
	   Fraction is a real number between 0 and 1.  The widget should
	   adjust its view so that the point given by fraction appears at the
	   beginning of	the widget.  If	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.

       scroll,number,units
	   The widget should adjust its	view by	number units.  The units are
	   defined in whatever way makes sense for the widget, such as
	   characters or lines in a text widget.  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.

       scroll,number,page
	   The widget should adjust its	view by	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.  Number is either 1, which
	   means the next page should become visible, or -1, which means that
	   the previous	page should become visible.

OLD COMMAND SYNTAX
       In versions of Tk before	4.0, the set and 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
       set method has the following form:

       $scrollbar->set(totalUnits, windowUnits,	firstUnit, lastUnit)
	   In this form	the arguments are all integers.	 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.  WindowUnits indicates	the total number of units that can fit
	   in the associated window at one time.  FirstUnit and	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).

       Under the old syntax the	get method returns a list of four integers,
       consisting of the totalUnits, windowUnits, firstUnit, and lastUnit
       values from the last 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:

       unit
	   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 firstUnit and lastUnit arguments	to the set method.

       The most	recent 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.

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.

       [1] Pressing button 1 over 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.

       [2] Pressing button 1 over 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.

       [3] Pressing button 1 over the slider and dragging causes the view to
	   drag	with the slider.  If the jump option is	true, then the view
	   doesn't drag	along with the slider;	it changes only	when the mouse
	   button is released.

       [4] Pressing button 1 over 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.

       [5] Pressing button 1 over 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.

       [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.

       [7] If button 1 is pressed with the Control key down, then if the mouse
	   is over arrow1 or trough1 the view changes to the very top (left)
	   of the document;  if	the mouse is over arrow2 or 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.

       [8] In vertical scrollbars the Up and Down keys have the	same behavior
	   as mouse clicks over	arrow1 and arrow2, respectively.  In
	   horizontal scrollbars these keys have no effect.

       [9] In vertical scrollbars Control-Up and Control-Down have the same
	   behavior as mouse clicks over trough1 and trough2, respectively.
	   In horizontal scrollbars these keys have no effect.

       [10]
	   In horizontal scrollbars the	Up and Down keys have the same
	   behavior as mouse clicks over arrow1	and arrow2, respectively.  In
	   vertical scrollbars these keys have no effect.

       [11]
	   In horizontal scrollbars Control-Up and Control-Down	have the same
	   behavior as mouse clicks over trough1 and trough2, respectively.
	   In vertical scrollbars these	keys have no effect.

       [12]
	   The Prior and Next keys have	the same behavior as mouse clicks over
	   trough1 and trough2,	respectively.

       [13]
	   The Home key	adjusts	the view to the	top (left edge)	of the
	   document.

       [14]
	   The End key adjusts the view	to the bottom (right edge) of the
	   document.

SEE ALSO
       Tk::callbacks Tk::Scrolled

KEYWORDS
       scrollbar, widget

perl v5.24.1			  2013-11-15			  Scrollbar(3)

NAME | SYNOPSIS | STANDARD OPTIONS | WIDGET-SPECIFIC OPTIONS | DESCRIPTION | ELEMENTS | WIDGET METHODS | SCROLLING COMMANDS | OLD COMMAND SYNTAX | BINDINGS | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tk::Scrollbar&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help