The scrollutil::scrollarea Command

For Scrollutil Version 1.0

by

Csaba Nemethi

csaba.nemethi@t-online.de

Contents

Start page


Quick Reference

NAME
scrollutil::scrollarea – Create and manipulate scrollarea widgets
SYNOPSIS
scrollutil::scrollarea pathName ?options?
STANDARD OPTIONS
-background   -highlightbackground  -relief
-borderwidth  -highlightcolor
-cursor       -highlightthickness
WIDGET-SPECIFIC OPTIONS
-lockinterval milliseconds
-respectheader boolean
-respecttitlecolumns boolean
-xscrollbarmode static|dynamic|none
-yscrollbarmode static|dynamic|none
DESCRIPTION
WIDGET COMMAND
pathName cget option
pathName configure ?option? ?value option value ...?
pathName setwidget widget
pathName widget
BINDINGS
KEYWORDS
scrollarea, widget, scrollbar

Contents     Start page


Detailed Reference

NAME
scrollutil::scrollarea – Create and manipulate scrollarea widgets
SYNOPSIS
scrollutil::scrollarea pathName ?options?
STANDARD OPTIONS
-background   -highlightbackground  -relief
-borderwidth  -highlightcolor
-cursor       -highlightthickness
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 1 -cursor "" -relief sunken
REMARK:  When configuring the -borderwidth or -relief option, if as a result of this action the scrollarea has a positive -borderwidth value (e.g., the default 1) and a -relief value other than flat (e.g., the default sunken), then the -borderwidth option of the widget embedded into the scrollarea via the setwidget subcommand of the associated Tcl command will automatically be set to 0, provided that the embedded widget supports this option.
WIDGET-SPECIFIC OPTIONS
Command-Line Name:  -lockinterval
Database Name:  lockInterval
Database Class:  LockInterval

Specifies the time interval in milliseconds for which the scrollbars having the display mode dynamic (see the -xscrollbarmode and -yscrollbarmode options) will be protected from being unmapped after being mapped, in order to avoid any shimmering effects.  Without this locking mechanism, under some rare circumstances a dynamic scrollbar could get mapped and unmapped in an endless loop, thus giving rise to an annoying and often dangerous flickering effect.  The same problem can arise due to a too small -lockinterval value.  The default is 1, which works as expected in the vast majority of cases.  Should you experience any shimmering in one of your scrollarea widgets, just set this option for that scrollarea to a sufficiently large value (e.g., 100).

Command-Line Name:  -respectheader
Database Name:  respectHeader
Database Class:  RespectHeader

This option is only relevant if the widget embedded into the scrollarea with the aid of the setwidget subcommand of the associated Tcl command is a tablelist and the Tablelist version being used is 6.5 or later.  Its value must be a boolean specifying whether the vertical scrollbar should appear below the tablelist widget's header, thus respecting the native look & feel on Mac OS X Aqua and on many modern Linux systems.  The default is 1 on the windowing systems aqua and x11, and 0 on win32.

Command-Line Name:  -respecttitlecolumns
Database Name:  respectTitleColumns
Database Class:  RespectTitleColumns

This option is only relevant if the widget embedded into the scrollarea with the aid of the setwidget subcommand of the associated Tcl command is a tablelist and the Tablelist version being used is 6.5 or later.  Its value must be a boolean specifying whether the horizontal scrollbar should start to the right of the tablelist widget's non-scrollable title column area if the value of the -titlecolumns tablelist option is positive.  The default is 1.

Command-Line Name:  -xscrollbarmode
Database Name:  xScrollbarMode
Database Class:  ScrollbarMode

Specifies the display mode to be used for the horizontal scrollbar.  The allowed values are static, dynamic, and none.  In static mode the scrollbar is displayed at all times.  In dynamic mode (which is the default) the scrollbar is mapped and unmapped as needed.  The display mode none disables the scrollbar display.

Command-Line Name:  -yscrollbarmode
Database Name:  yScrollbarMode
Database Class:  ScrollbarMode

Specifies the display mode to be used for the vertical scrollbar.  The allowed values are static, dynamic, and none.  In static mode the scrollbar is displayed at all times.  In dynamic mode (which is the default) the scrollbar is mapped and unmapped as needed.  The display mode none disables the scrollbar display.

DESCRIPTION
The scrollutil::scrollarea command creates a new window named pathName and of the class Scrollarea, and makes it into a scrollarea widget.  Additional options, described above, may be specified on the command line or in the option database to configure aspects of the scrollarea such as its borderwidth, relief, and display mode to be used for the scrollbars.  The scrollutil::scrollarea 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 scrollarea is a mega-widget consisting of a scrollable widget specified with the aid of the setwidget subcommand of the associated Tcl command as well as two scrollbars connected with that widget.  These components are managed within the scrollarea using grid.  The scrollbars, named hsb (with  -orient horizontal)  and vsb (with  -orient vertical)  are direct children of the scrollarea.  The display mode of each scrollbar can be static, dynamic, or none (see the -xscrollbarmode and -yscrollbarmode configuration options).  The -takefocus option of both scrollbars is set to 0.  In the Scrollutil_tile package the scrollbars are created as tk::scrollbar widgets, except on Mac OS X, where the native ttk::scrollbar widget of the aqua theme doesn't look as expected.
If the widget embedded into the scrollarea via setwidget is a tablelist and Tablelist version 6.5 or later is being used then the scrollarea can also contain siblings of the tablelist widget above the vertical scrollbar and/or to the left of the horizontal one, causing the vertical scrollbar to be displayed below the tablelist's header and/or the horizontal scrollbar to appear to the right of the tablelist's title column area, depending on the values of the -respectheader and -respecttitlecolumns configuration options.
WIDGET COMMAND
The scrollutil::scrollarea 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 scrollarea 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::scrollarea 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::scrollarea command.
pathName setwidget widget
The widget argument must be the path name of an existing widget or an empty string.  In the first case, the command manages the widget to fill the top-left part of the scrollarea and connects it with the scrollbars by setting its -xscrollcommand and -yscrollcommand options to appropriate wrappers for the set command of the two scrollbars and setting the -command option of the scrollbars to  [list widget xview]  and  [list widget yview],  respectively.  If widget is an empty string then the widget passed to the most recent setwidget invocation (if any) is unmanaged and unconnected from the scrollbars.  The subcommand returns its widget argument.
REMARK 1:  If widget is nonempty and the value of the -xscrollbarmode option is different from none then widget must be a horizontally scrollable widget, meaning that it must support the -xscrollcommand configuration option and the associated Tcl command must have the xview subcommand.  Similarly, if widget is nonempty and the value of the -yscrollbarmode option is different from none then widget must be a vertically scrollable widget, meaning that it must support the -yscrollcommand configuration option and the associated Tcl command must have the yview subcommand.  Consequently, if widget is an entry or ttk::entry then this subcommand will only be successful if the -yscrollbarmode option was previously set to none.
REMARK 2:  The widget identified by the widget argument must be a child of the scrollarea or of one of the latter's ascendants.
REMARK 3:  When the widget whose path name was passed to setwidget gets destroyed, this subcommand is automatically invoked with an empty string as argument.
REMARK 4:  This subcommand sets the -highlightthickness option of widget to 0 if widget supports this configuration option.  In addition, if the scrollarea has a positive -borderwidth value (e.g., the default 1) and a -relief value other than flat (e.g., the default sunken) then this subcommand sets the -borderwidth option of widget to 0, provided that widget supports this option.
pathName widget
Returns the argument passed to the most recent invocation of the setwidget subcommand, or an empty string if there was no invocation of that subcommand.
BINDINGS
When a new scrollarea is created, it has no default event bindings: scrollareas are not intended to be interactive.
KEYWORDS
scrollarea, widget, scrollbar

Contents     Start page