The scrollutil::scrollableframe Command

For Scrollutil Version 1.5

by

Csaba Nemethi

csaba.nemethi@t-online.de

Contents

Start page

Quick Reference

NAME
scrollutil::scrollableframe – Create and manipulate scrollableframe widgets
SYNOPSIS
scrollutil::scrollableframe pathName ?options?
DESCRIPTION
STANDARD OPTIONS
-background   -highlightbackground  -relief
-borderwidth  -highlightcolor       -xscrollcommand
-cursor       -highlightthickness   -yscrollcommand
WIDGET-SPECIFIC OPTIONS
-contentheight screenDistance
-contentwidth screenDistance
-fitcontentheight boolean
-fitcontentwidth boolean
-height screenDistance
-takefocus 0|1|""|command
-width screenDistance
-xscrollincrement screenDistance
-yscrollincrement screenDistance
WIDGET COMMAND
pathName cget option
pathName configure ?option? ?value option value ...?
pathName contentframe
pathName scan option args
pathName scan mark x y
pathName scan dragto x y ?gain?
pathName see widget ?nw|ne|sw|se?
pathName xview ?args?
pathName xview
pathName xview moveto fraction
pathName xview scroll number units|pages
pathName yview ?args?
pathName yview
pathName yview moveto fraction
pathName yview scroll number units|pages
BINDINGS
KEYWORDS
scrollableframe, widget, frame, scrollable

Contents     Start page

Detailed Reference

NAME
scrollutil::scrollableframe – Create and manipulate scrollableframe widgets
SYNOPSIS
scrollutil::scrollableframe pathName ?options?
DESCRIPTION
The scrollutil::scrollableframe command creates a new window named pathName and of the class Scrollableframe, and makes it into a scrollableframe widget.  Additional options, described below, may be specified on the command line or in the option database to configure aspects of the scrollableframe widget such as its width, height, and scrolling increments.  The scrollutil::scrollableframe command returns its pathName argument.  At the time this command is invoked, there must not exist a window named pathName, but pathName's parent must exist.
A scrollableframe is a mega-widget containing a content frame, whose dimensions may be larger than those of the widget itself.  Arbitrary regions of this frame can be brought into view by scrolling, being that the scrollableframe widget supports the -xscrollcommand and -yscrollcommand configuration options and the associated Tcl command has the xview and yview subcommands.  The content frame may contain any number of arbitrary widgets.  In other words, the scrollutil::scrollableframe command implements a scrollable widget container.
In the Scrollutil package both the scrollableframe widget and its content frame are implemented as Tk core frames, while in Scrollutil_tile they are ttk::frame widgets.  The content frame can be accessed by means of the contentframe subcommand.  Individual widgets contained in it can be made visible in the scrollableframe window with the aid of the see subcommand.  In addition to scrolling, scrollableframe widgets also support scanning, with the aid of appropriate mouse event bindings that invoke the scan subcommand.
A scrollableframe widget is typically created within a scrollarea, like in the following example: 
set sa [scrollutil::scrollarea ...]
set sf [scrollutil::scrollableframe $sa.sf ...]
$sa setwidget $sf

set cf [$sf contentframe]
<populate the content frame>

update idletasks
$sf configure -width [winfo reqwidth $cf] -height ... -yscrollincrement ...

pack $sa -expand yes -fill both
STANDARD OPTIONS
-background   -highlightbackground  -relief
-borderwidth  -highlightcolor       -xscrollcommand
-cursor       -highlightthickness   -yscrollcommand
See the options manual entry for details on the standard Tk widget options.  The -background, -highlightbackground, -highlightcolor, and -highlightthickness options are only supported by the Scrollutil package, but not by Scrollutil_tile.  They have the same default values as the options of the same names for Tk frame widgets.  The default values of the remaining standard options are:
-borderwidth 0 -cursor "" -relief flat -xscrollcommand "" -yscrollcommand ""
WIDGET-SPECIFIC OPTIONS
Command-Line Name:  -contentheight
Database Name:  contentHeight
Database Class:  ContentHeight

Specifies the desired height for the content frame in any of the forms acceptable to Tk_GetPixels.  If the option's value is less than or equal to zero then the content frame's height is made just large enough to hold all its children.  This option is only relevant if the value of the -fitcontentheight option is false; otherwise the content frame will have the same height as the scrollableframe window, regardless of the value of the -contentheight option.  The default is 0, which is suitable for the vast majority of applications.

Command-Line Name:  -contentwidth
Database Name:  contentWidth
Database Class:  ContentWidth

Specifies the desired width for the content frame in any of the forms acceptable to Tk_GetPixels.  If the option's value is less than or equal to zero then the content frame's width is made just large enough to hold all its children.  This option is only relevant if the value of the -fitcontentwidth option is false; otherwise the content frame will have the same width as the scrollableframe window, regardless of the value of the -contentwidth option.  The default is 0, which is suitable for the vast majority of applications.

Command-Line Name:  -fitcontentheight
Database Name:  fitContentHeight
Database Class:  FitContentHeight

Specifies a boolean value indicating whether or not the content frame should have the same height as the scrollableframe window.  If true then the content frame's height will be kept in sync with that of the widget and the value of the -contentheight option will be ignored.  The default is 0.

Command-Line Name:  -fitcontentwidth
Database Name:  fitContentWidth
Database Class:  FitContentWidth

Specifies a boolean value indicating whether or not the content frame should have the same width as the scrollableframe window.  If true then the content frame's width will be kept in sync with that of the widget and the value of the -contentwidth option will be ignored.  The default is 0.

Command-Line Name:  -height
Database Name:  height
Database Class:  Height

Specifies the desired height for the scrollableframe widget in any of the forms acceptable to Tk_GetPixels.  Note that this sets the inner height, excluding the border and highlight rectangle (if any) drawn around the outside of the widget.  The default is 100, which should be overridden with a suitable application-specific value.

Command-Line Name:  -takefocus
Database Name:  takeFocus
Database Class:  TakeFocus

This option determines whether the scrollableframe widget accepts the focus during keyboard traversal.  It is almost identical to the standard option of the same name (see the options manual entry for details).  The only difference is that not the scrollableframe widget itself but its content frame will receive the focus during keyboard traversal with the standard keys (Tab and Shift-Tab).  The default is 0, being that a scrollableframe widget is esentially a frame used as a view for its content frame component.

Command-Line Name:  -width
Database Name:  width
Database Class:  Width

Specifies the desired width for the scrollableframe widget in any of the forms acceptable to Tk_GetPixels.  Note that this sets the inner width, excluding the border and highlight rectangle (if any) drawn around the outside of the widget.  The default is 100, which should be overridden with a suitable application-specific value.

Command-Line Name:  -xscrollincrement
Database Name:  xScrollIncrement
Database Class:  ScrollIncrement

Specifies an increment for horizontal scrolling, in any of the forms acceptable to Tk_GetPixels.  If the value of this option is greater than zero then the horizontal view in the window will be constrained so that the x coordinate within the content frame at the left edge of the window is always an even multiple of xScrollIncrement; furthermore, the units for horizontal scrolling (see the xview subcommad) will also be xScrollIncrement.  If the value is less than or equal to zero then the horizontal scrolling is unconstrained.  The default is 0.

Command-Line Name:  -yscrollincrement
Database Name:  yScrollIncrement
Database Class:  ScrollIncrement

Specifies an increment for vertical scrolling, in any of the forms acceptable to Tk_GetPixels.  If the value of this option is greater than zero then the vertical view in the window will be constrained so that the y coordinate within the content frame at the top edge of the window is always an even multiple of yScrollIncrement; furthermore, the units for vertical scrolling (see the yview subcommad) will also be yScrollIncrement.  If the value is less than or equal to zero then the vertical scrolling is unconstrained.  The default is 0.

WIDGET COMMAND
The scrollutil::scrollableframe command creates a new Tcl command whose name is pathName.  This command may be used to invoke various operations on the widget.  It has the following general form: 
pathName option ?arg arg ...?
option and the args determine the exact behavior of the command.  The following commands are possible for scrollableframe widgets:
pathName cget option
Returns the current value of the configuration option given by option, which may have any of the values accepted by the scrollutil::scrollableframe command.
pathName configure ?option? ?value option value ...?
Queries or modifies the configuration options of the widget.  If no option is specified, the command returns a list describing all of the available options for pathName (see Tk_ConfigureInfo for information on the format of this list).  If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified).  If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the return value is an empty string.  option may have any of the values accepted by the scrollutil::scrollableframe command.
pathName contentframe
Returns the path name of the widget's content frame.
pathName scan option args
This command is used to implement scanning on scrollableframe widgets.  It has two forms, depending on option:
pathName scan mark x y
Records x and y and the current view in the scrollableframe window; used in conjunction with later  scan dragto  commands.  Typically this command is associated with a mouse button press in the widget and x and y are the coordinates of the mouse.  It returns an empty string.
pathName scan dragto x y ?gain?
This command computes the difference between its x and y arguments (which are typically mouse coordinates) and the x and y arguments to the last  scan mark  command for the widget.  It then adjusts the view by gain times the difference in coordinates, where gain defaults to 10.  This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the content frame at high speed through the window.  The return value is an empty string.
pathName see widget ?corner?
This command adjusts the view in the scrollableframe's window so that widget becomes visible in it.  The specified widget must be a descendant of the content frame and must have the same toplevel.  In addition, it must be managed by some geometry manager (such as grid, pack, place, text, or canvas).  The optional corner argument specifies which corner of widget should become visible if it is too large to fit into the window.  The possible values are nw (north-west), ne (north-east), sw (south-west), and se (south-east).  The default corner is nw.
REMARK:  By using this subcommand you can make the keyboard navigation in the content frame more user-friendly, like in the following example, in which $w is a descendant of the content frame of the scrollableframe widget $sf (it is assumed that $sf doesn't contain % characters):
bind $w <<TraverseIn>> [list $sf see %W]
If the widget $w was embedded into a scrollarea via the latter's setwidget subcommand, and the scrollarea in turn is a descendant of the content frame, then it is more user-friendly to bring the scrollarea into view rather than just the widget:
bind $w <<TraverseIn>> [list seeScrollarea $sf %W]

proc seeScrollarea {sf w} { $sf see [scrollutil::getscrollarea $w] }
pathName xview ?args?
This command is used to query and change the horizontal position of the information displayed in the widget's window.  It can take any of the following forms:
pathName xview
Returns a list containing two elements.  Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window.  For example, if the first element is 0.2 and the second element is 0.6 then 20% of the content frame is off-screen to the left, the middle 40% is visible in the window, and 40% of the content frame is off-screen to the right.  These are the same values passed to scrollbars via the -xscrollcommand option.
pathName xview moveto fraction
Adjusts the view in the window so that fraction of the total width of the content frame is off-screen to the left.  fraction must be a fraction between 0 and 1.
pathName xview scroll number what
This command shifts the view in the window left or right according to number and what.  number must be an integer.  what must be either units or pages or an abbreviation of one of these.  If what is units, the view adjusts left or right in units of the xScrollIncrement option if it is greater than zero, or in units of one-tenth the window's width otherwise.  If what is pages then the view adjusts in units of nine-tenths the window's width.  If number is negative then information farther to the left becomes visible; if it is positive then information farther to the right becomes visible.
pathName yview ?args?
This command is used to query and change the vertical position of the information displayed in the widget's window.  It can take any of the following forms:
pathName yview
Returns a list containing two elements.  Each element is a real fraction between 0 and 1; together they describe the vertical span that is visible in the window.  For example, if the first element is 0.2 and the second element is 0.6 then 20% of the content frame is off-screen to the top, the middle 40% is visible in the window, and 40% of the content frame is off-screen to the bottom.  These are the same values passed to scrollbars via the -yscrollcommand option.
pathName yview moveto fraction
Adjusts the view in the window so that fraction of the total height of the content frame is off-screen to the top.  fraction must be a fraction between 0 and 1.
pathName yview scroll number what
This command shifts the view in the window up or down according to number and what.  number must be an integer.  what must be either units or pages or an abbreviation of one of these.  If what is units, the view adjusts up or down in units of the yScrollIncrement option if it is greater than zero, or in units of one-tenth the window's height otherwise.  If what is pages then the view adjusts in units of nine-tenths the window's height.  If number is negative then higher information becomes visible; if it is positive then lower information becomes visible.
BINDINGS
Mouse button 1 may be used for scanning.  If it is pressed and dragged over the scrollableframe window, the content frame drags at high speed in the direction the mouse moves.  For the duration of the scan the cursor is set to one having the shape of a pointing hand.
KEYWORDS
scrollableframe, widget, frame, scrollable

Contents     Start page

Comparison with BWidget ScrollableFrame and iwidgets::scrolledframe

The scrollutil::scrollableframe widget was designed as a lightweight, theme-able, and full-featured replacement for BWidget ScrollableFrame and iwidgets::scrolledframe.  The following table contains a comparison of the options and commands provided by the three widgets:

scrollutil::scrollableframe BWidget ScrollableFrame iwidgets::scrolledframe
-background -background -background
-borderwidth -borderwidth
-cursor -cursor
-contentheight -areaheight [pathName component canvas] \
itemconfigure frameTag -height ...
-contentwidth -areawidth [pathName component canvas] \
itemconfigure frameTag -width ...
-fitcontentheight -constrainedheight bind [pathName component canvas] <Configure> \
{ %W itemconfigure frameTag -height %h }
-fitcontentwidth -constrainedwidth bind [pathName component canvas] <Configure> \
{ %W itemconfigure frameTag -width %w }
-height  (sets the inner height, excluding
the border and highlight rectangle, if any)		 -height  (inner height = total height) -height  (sets the total height, including
the border and horizontal scrollbar, if any)
-highlightbackground
-highlightcolor
-highlightthickness
-relief -relief
-takefocus
-width  (sets the inner width, excluding
the border and highlight rectangle, if any)		 -width  (inner width = total width) -width  (sets the total width, including
the border and vertical scrollbar, if any)
-xscrollcommand -xscrollcommand
-xscrollincrement -xscrollincrement -xscrollincrement for [pathName component canvas]
-yscrollcommand -yscrollcommand
-yscrollincrement -yscrollincrement -yscrollincrement for [pathName component canvas]
cget cget cget
configure configure configure
contentframe getframe childsite
scan  (with mouse event bindings)
see widget ?nw|ne|sw|se? see widget ?top|bottom ?left|right??
xview xview xview
yview yview yview
xview|yview moveto 0|1 xview|yview moveto 0|1 justify left|right|top|bottom
(shortcut for  xview|yview moveto 0|1)

REMARK 1:  For the see command provided by the BWidget ScrollableFrame widget one cannot specify the horizontal side without the vertical one.  More annoying is, however, that in the presence of a positive -xscrollincrement or -yscrollincrement value, widgets that are small enough to fit into the window are quite often just partially brought into view.  In addition, the command works only for direct children of the ScrollableFrame widget's content frame.

REMARK 2:  The iwidgets::scrolledframe widget has no equivalents of the scrollutil::scrollableframe options -contentheight, -contentwidth, -fitcontentheight, and -fitcontentwidth, but these can be emulated (using undocumented internal information!) as shown above.  It provides a justify command, which is, however, just a shortcut for  xview|yview moveto 0|1.  What this widget is really missing, is a see command for making individual widgets visible in the window (which is important for user-friendly keyboard navigation).

Contents     Start page