On the scrollarea Widget
and
Scrollable Widget Containers

by

Csaba Nemethi

Abstract
The scrollutil::scrollarea Widget
Demo Scripts Related to the scrollutil::scrollarea Widget
Short History of the Mouse Wheel and Its Support in Tk
Mouse Wheel Event Handling in Scrollable Widget Containers
A Demo Script Using the Scrollutil Package and a BWidget ScrollableFrame
A Demo Script Using Scrollutil and Two BWidget ScrollableFrame Widgets

1. Abstract

This is a presentation of the new Scrollutil package, which contains:

the implementation of the scrollarea mega-widget;
commands for user-friendly mouse wheel event handling in scrollable widget containers like BWidget ScrollableFrame and iwidgets::scrolledframe;
demo scripts illustrating the use of the Scrollutil package in connection with various scrollable widgets and the above-mentioned scrollable widget containers;
a programmer's manual and reference pages, in HTML format.

The talk shows by means of a series of demo scripts how the scrollutil::scrollarea widget is distinct from all similar widgets, and how to use the mouse wheel event handling provided by the Scrollutil package in BWidget ScrollableFrame widgets.

2. The scrollutil::scrollarea Widget

2.1 Description

The scrollutil::scrollarea mega-widget greatly simplifies the creation of arbitrary scrolled widgets. It consists of a scrollable widget and two scrollbars connected with that widget. The display mode of each scrollbar can be static, dynamic, or none. This widget also respects the header component and title columns of tablelist widgets (this is freely configurable).

Similar widgets and packages:

BWidget ScrolledWindow;
its snit-based equivalent widget::scrolledwindow by Jeff Hobbs;
the snit-based scrodget package by Aldo Buratti;
its TclOO-based equivalent scrolledwidget by Johann Oberdorfer.

What makes the scrollutil::scrollarea widget distinct from all the above?

full tablelist support (see section 3.1);
support for widgets that are scrollable in one direction only (see section 3.2);
free from the shimmering problem in connection with text widgets (see section 3.3);
implemented in pure Tcl code and free from external dependencies like BWidget, snit, or (for Tcl 8.5) TclOO.

2.2 Quick Reference

Synopsis

package require scrollutil(_tile) ?version?

scrollutil::scrollarea pathName ?options?

Standard options

-background   -highlightbackground  -relief
-borderwidth  -highlightcolor
-cursor       -highlightthickness

Widget-specific options

-respectheader boolean
-respecttitlecolumns boolean
-xscrollbarmode static|dynamic|none
-yscrollbarmode static|dynamic|none

Widget command

pathName cget option
pathName configure ?option? ?value option value ...?
pathName setwidget widget
pathName widget

3. Demo Scripts Related to the scrollutil::scrollarea Widget

3.1 A Scrolled tablelist Widget

Live presentation and review of the following scripts:

ScrolledTablelist1.tcl
ScrolledTablelist2.tcl

The first script contains traditional scrollbar management:

package require tablelist_tile 6.3

wm title . "Scrolled Tablelist"

set f [ttk::frame .f]

# Create the tablelist and the scrollbars as children
# of a frame having -borderwidth 1 and -relief sunken
set frm [ttk::frame $f.frm -borderwidth 1 -relief sunken]
set tbl $frm.tbl
set vsb $frm.vsb
set hsb $frm.hsb
tablelist::tablelist $tbl ... -borderwidth 0 \
    -xscrollcommand [list $hsb set] -yscrollcommand [list $vsb set]
. . .
ttk::scrollbar $vsb -orient vertical   -command [list $tbl yview]
ttk::scrollbar $hsb -orient horizontal -command [list $tbl xview]

. . .

# Manage the widgets within the frame
grid $tbl -row 0 -rowspan 2 -column 0 -columnspan 2 -sticky news
if {[tk windowingsystem] eq "win32"} {
    grid $vsb -row 0 -rowspan 2 -column 2 -sticky ns
} else {
    grid [$tbl cornerpath] -row 0 -column 2 -sticky ew
    grid $vsb              -row 1 -column 2 -sticky ns
}
grid [$tbl cornerpath -sw] -row 2 -column 0 -sticky ns
grid $hsb                  -row 2 -column 1 -sticky ew
grid rowconfigure    $frm 1 -weight 1
grid columnconfigure $frm 1 -weight 1

# Manage the frame
pack $frm -expand yes -fill both -padx 10 -pady 10

. . .

The second script uses a scrollarea widget, which makes it much simpler:

package require tablelist_tile 6.5
package require scrollutil_tile

wm title . "Scrolled Tablelist"

set f [ttk::frame .f]

# Create the tablelist within a scrollarea
set sa [scrollutil::scrollarea $f.sa]
set tbl $sa.tbl
tablelist::tablelist $tbl ...
. . .
$sa setwidget $tbl

. . .

# Manage the scrollarea
pack $sa -expand yes -fill both -padx 10 -pady 10

. . .

3.2 Support for Widgets that Are Scrollable in One Direction Only

Live presentation of the following scripts:

entryTest/scrodget.tcl
entryTest/scrolledwidget.tcl
entryTest/BWidget_ScrolledWindow.tcl
entryTest/widget_scrolledwindow.tcl
entryTest/scrollutil_scrollarea.tcl

Conclusion:

Error message with scrodget, scrolledwidget, and BWidget ScrolledWindow;
Behavior as expected with widget::scrolledwindow and scrollutil::scrollarea.

3.3 The Shimmering Problem in Connection with text Widgets

Live presentation of the following scripts:

shimmeringTest/autoscroll.tcl
shimmeringTest/scrodget.tcl
shimmeringTest/scrolledwidget.tcl
shimmeringTest/BWidget_ScrolledWindow.tcl
shimmeringTest/widget_scrolledwindow.tcl
shimmeringTest/scrollutil_scrollarea.tcl

Conclusion:

Heavy shimmering with autoscroll, scrodget, and scrolledwidget;
BWidget ScrolledWindow partially circumvents the shimmering;
The way widget::scrolledwindow prevents the shimmering is bogus;
scrollutil::scrollarea appears to handle the shimmering as expected.

4. Short History of the Mouse Wheel and Its Support in Tk

4.1 History of the Mouse Wheel

1985: First scrolling mouse, called Mighty Mouse, with the scroll wheel accessible on the side, jointly invented by NTT (Nippon Telegraph and Telephone) and ETH (Eidgenössische Technische Hochschule) Zürich, Switzerland;
1987: An early prototype of the mouse with top mounted scrolling wheel, developed by Jack McCauley for gaming applications;
1995: First commercial mouse with scroll wheel, named Genius EasyScroll and Mouse Systems ProAgio, released by the Taiwanese company KYE Systems;
1996: Microsoft IntelliMouse and support for the mouse wheel in Microsoft Office 97.

4.2 History of the Mouse Wheel Support in Tk

1998-11-20, Tcl/Tk 8.0.4: Added support for the <MouseWheel> event for the listbox and text widgets on Windows;
2000-02-10, Tcl/Tk 8.3.0: Added support for <Button-4> and <Button-5> as mouse wheel style scrolling in listbox and text widgets for Unix;
2004-03-01, Tcl/Tk 8.4.6: Added <MouseWheel> event handling for Mac OS X;
2004-03-05: TIP 171 by Jeff Hobbs & Keith Vetter: Change the default <MouseWheel> bindigs in such a way that they scroll what the mouse is over, not what has the focus;
2011-08-08, Tcl/Tk 8.6.b2: On Windows, too, the mouse wheel events are no longer reported to the widget having the focus, but to the one under the pointer (this makes TIP 171 redundant);
2012-12-20: Released Tcl/Tk 8.6.0.

5. Mouse Wheel Event Handling in Scrollable Widget Containers

5.1 How to Use the Mouse Wheel Event Handling of the Scrollutil Package in Scrollable Widget Containers?

Create mouse wheel event bindings for the binding tag "all" or for the toplevel widgets (including ".") having scrollable widget containers, by invoking the scrollutil::createWheelEventBindings command. In addition, register your scrollable widget containers for scrolling via these bindings with the aid of the scrollutil::enableScrollingByWheel command. Result: The mouse wheel events will scroll the registered widget container that is an ascendant of the widget under the pointer.
Eliminate the annoying and often dangerous double-handling effect, by invoking the scrollutil::adaptWheelEventHandling command for those widgets contained in registered scrollable widget containers that have mouse wheel event (class) bindings. Result: If the focus is on the widget under the pointer then the mouse wheel events will be handled by the (class bindings of the) widget only, otherwise by the bindings created with the scrollutil::createWheelEventBindings command.
Where desirable (e.g., for the entry components of mentry widgets of type "Date", "Time", "DateTime", "IPAddr", or"IPv6Addr"), make the focus check within this modified event handling less restrictive with the aid of the scrollutil::setFocusCheckWindow command.

5.2 Command Reference

package require scrollutil(_tile) ?version?

scrollutil::createWheelEventBindings ?tag tag ...?

scrollutil::enableScrollingByWheel ?scrollableWidgetContainer scrollableWidgetContainer ...?

scrollutil::adaptWheelEventHandling ?widget widget ...?

scrollutil::setFocusCheckWindow widget ?widget ...? otherWidget

scrollutil::focusCheckWindow widget

6. A Demo Script Using the Scrollutil Package and a BWidget ScrollableFrame

Live presentation and review of the script ScrollableFrmDemo1.tcl ...

package require Tk 8.5
package require BWidget
Widget::theme yes
package require scrollutil_tile

wm title . "European Capitals Quiz"

# Create a ScrollableFrame within a scrollarea
set f  [ttk::frame .f]
set sa [scrollutil::scrollarea $f.sa]
set sf [ScrollableFrame $sa.sf]
$sa setwidget $sf

. . .

# Create mouse wheel event bindings for the binding tag "all" and
# register the ScrollableFrame for scrolling by these bindings
scrollutil::createWheelEventBindings all
scrollutil::enableScrollingByWheel $sf

# Get the content frame and populate it

set cf [$sf getframe]

set countryList {
    Albania Andorra Austria Belarus Belgium "Bosnia and Herzegovina" Bulgaria
    . . .
}
set capitalList {
    Tirana "Andorra la Vella" Vienna Minsk Brussels Sarajevo Sofia
    . . .
}

. . .

set capitalList [lsort $capitalList]

. . .

set row 0
foreach country $countryList {
    . . .

    set w [ttk::combobox $cf.cb$row -state readonly -width 14 \
           -values $capitalList]
    . . .

    # Adapt the handling of the mouse wheel events for the ttk::combobox widget
    scrollutil::adaptWheelEventHandling $w

    . . .

    incr row
}

. . .

7. A Demo Script Using Scrollutil and two BWidget ScrollableFrame Widgets

Live presentation and review of the script ScrollableFrmDemo2.tcl ...

package require Tk 8.5.9                        ;# for ttk::spinbox
package require BWidget
Widget::theme yes
package require mentry_tile 3.2                 ;# for mouse wheel support
package require tablelist_tile 6.5              ;# for -(x|y)mousewheelwindow
                                                ;# and scrollutil::scrollarea
package require scrollutil_tile

wm title . "Scrollutil Demo"

# Create a ScrollableFrame within a scrollarea
set tf [ttk::frame .tf]
set sa [scrollutil::scrollarea $tf.sa]
set sf [ScrollableFrame $sa.sf]
$sa setwidget $sf

. . .

# Get the content frame and populate it
set cf [$sf getframe]
source ScrollableFrmContent.tcl

# Additional stuff related to the mouse wheel events:

# Create mouse wheel event bindings for the binding tag "all" and
# register the ScrollableFrame for scrolling by these bindings
scrollutil::createWheelEventBindings all
scrollutil::enableScrollingByWheel $sf

# Adapt the handling of the mouse wheel events for the text, listbox,
# ttk::combobox, ttk::spinbox, tablelist, and ttk::treeview widgets, as
# well as for the entry components of the mentry widget of type "Date"
set entryList [$me entries]
scrollutil::adaptWheelEventHandling $txt $lb $cb $sb $tbl $tv {*}$entryList

# For the entry components of the mentry widget
# set the "focus check window" to the mentry
scrollutil::setFocusCheckWindow {*}$entryList $me

In the file ScrollableFrmContent.tcl the scrolled text, listbox, tablelist, and ttk::treeview widgets are created within scrollarea widgets:

set _sa [scrollutil::scrollarea ...]
set txt [text $_sa.txt -font TkFixedFont -width 73]
$_sa setwidget $txt
grid $_sa ...

. . .

set _sa [scrollutil::scrollarea ...]
set lb [listbox $_sa.lb -width 0]
$_sa setwidget $lb
grid $_sa ...

. . .

set _sa [scrollutil::scrollarea ...]
set tbl [tablelist::tablelist $_sa.tbl ...]
. . .
$_sa setwidget $tbl
grid $_sa ...

. . .

set _sa [scrollutil::scrollarea ... -borderwidth 0]
set tv [ttk::treeview $_sa.tv ...]
. . .
$_sa setwidget $tv
grid $_sa ...

Live presentation of the procedure configTablelist, contained in the file ScrollableFrmContent.tcl and associated with the "Configure Tablelist Widget" button as the value of its -command option. It creates a second ScrollableFrame within a scrollarea and invokes:

scrollutil::enableScrollingByWheel for its own ScrollableFrame widget;
scrollutil::adaptWheelEventHandling for the ttk::combobox and ttk::spinbox widgets.

On the scrollarea Widget and Scrollable Widget Containers

by