Scrollutil Programmer's Guide

For Scrollutil Version 1.12

by

Csaba Nemethi

csaba.nemethi@t-online.de

Contents

Overview

Examples

Start page


Overview

What Is Scrollutil?

Scrollutil is a library package for Tcl/Tk versions 8.0 or higher, written in pure Tcl/Tk code.  It contains:

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 scrolled window implementation also supports the widgets that are scrollable in one direction only (e.g., entry and ttk::entry) and respects the header component and title columns of tablelist widgets (this is freely configurable).

The scrollutil::scrollarea widget is similar to BWidget ScrolledWindow and its snit-based equivalent widget::scrolledwindow, contributed by Jeffrey Hobbs and contained in tklib.  The snit-based scrodget package by Aldo Buratti and its TclOO-based equivalent scrolledwidget contributed by Johann Oberdorfer are further scrolled window implementations. However, full tablelist support is only provided by the scrollarea widget, which is free from external dependencies like BWidget, snit, or (for Tcl 8.5) TclOO.  It is also free from the shimmering problem in connection with text widgets, which the above-mentioned scrolled window implementations either share with the autoscroll package (contained in tklib) or circumvent in a suboptimal way.

The scrollutil::scrollsync mega-widget is designed for scrolling several widgets simultaneously.  Whenever the horizontal/vertical position of the view in the window of one of its widgets changes, the view in the windows of all the other widgets is automatically adjusted accordingly, thus making sure that the view's position in these windows is kept in sync.  This mega-widget is horizontally and vertically scrollable, hence it can be embedded into a scrollutil::scrollarea widget via the latter's setwidget subcommand.

The scrollutil::scrollableframe mega-widget is a scrollable widget container.  It contains a content frame, whose dimensions are typically larger than those of the widget itself.  Arbitrary regions of this frame can be brought into view by scrolling, and the widget also provides a command for making individual widgets contained in the content frame visible in the scrollableframe window.

The scrollutil::scrollableframe widget is similar to BWidget ScrollableFrame and iwidgets::scrolledframe.  However, unlike these widgets, which use a canvas for scrolling the content frame, it adjusts the view with the aid of the place geometry manager, just like the scrolledframe::scrolledframe command of the Scrolledframe package by Maurice Bredelet (ulis) and its optimized and enhanced version contributed by Keith Nash.  For details on these commands see the wiki page

https://wiki.tcl-lang.org/page/A+scrolled+frame

The canvas-free approach is more lightweight and integrates better in applications that use tile widgets.

The scrollutil::scrollednotebook mega-widget contains a ttk::notebook within a scrollableframe and supports an arbitrary number of unsqueezed tabs.  Currently not visible tabs can be brought into view by navigating and scrolling with the mouse wheel or keyboard, and the widget also provides a command for making individual tabs visible in the scrollednotebook window.  It is made sure that the currently selected tab is always visible.  Unlike the ttk::notebook widget, whose -width option is quite often overriden by the total width of the tabs, the scrollednotebook widget respects the value of its -width option, regardless of the space required by the tabs.

The scrollutil::plainnotebook mega-widget extends a ttk::notebook having an arbitrary number of pages with invisible tabs by a ttk::frame to its left or right containing, among others, a scrollableframe whose content frame is the parent of a series of widgets that play the role of vertically laid-out notebook tabs.  Currently not visible "tabs" can be brought into view by scrolling with the mouse wheel or the vertical scrollbar of the scrollarea containing the scrollableframe, and the widget provides a command for making individual "tabs" visible in the plainnotebook window.  Unlike a ttk::notebook widget with vertically aligned tabs, which in most themes has a suboptimal look and whose -height option is quite often overriden by the total height of the tabs, the plainnotebook widget respects the value of its -height option, regardless of the space required by the "tabs".

The scrollutil::pagesman mega-widget provides the basic functionality of a pages manager, meaning that it manages a list of windows, called pages, of which only one is visible at a time.  By using it with plainnotebook widgets as pages, it is quite easy to write applications in which the user can descend from a plainnotebook to another one with a single mouse click and switch back in the same way to the original one.  Everything needed for this navigation is provided by appropriate options and subcommands of the plainnotebook widget.

From the point of view of the commands related to mouse wheel event handling provided by the Scrollutil package, the scrollability of a widget or widget container window means that the associated Tcl command supports the  xview scroll number units  and  yview scroll number units  subcommands.  The reason for requiring at least Tk version 8.6b2 on Windows for the commands related to scrollable widget containers is that in earlier Tk versions on this platform the mouse wheel events were sent to the widget having the focus rather than to the one under the pointer.

To make use of the user-friendly mouse wheel event handling via the Scrollutil package, follow the steps below:

The mouse wheel event handling with the aid of the Scrollutil package was also tested to work with the scrolledframe::scrolledframe command of the Scrolledframe package by Maurice Bredelet (ulis) and its optimized and enhanced version contributed by Keith Nash, as well as with the sframe command implemented by Paul Walton.  For details on these commands (which provide further implementations of scrollable widget containers) see the above-mentioned wiki page.

How to Get It?

Scrollutil is available for free download from the Web page

https://www.nemethi.de

The distribution file is scrollutil1.12.tar.gz for UNIX and scrollutil1_12.zip for Windows.  These files contain the same information, except for the additional carriage return character preceding the linefeed at the end of each line in the text files for Windows.

Scrollutil is also included in tklib, which has the address

https://core.tcl.tk/tklib

How to Install It?

Install the package as a subdirectory of one of the directories given by the auto_path variable.  For example, you can install it as a directory at the same level as the Tcl and Tk script libraries.  The locations of these library directories are given by the tcl_library and tk_library variables, respectively.

To install Scrollutil on UNIX, cd to the desired directory and unpack the distribution file scrollutil1.12.tar.gz:

gunzip -c scrollutil1.12.tar.gz | tar -xf -

On most UNIX systems this can be replaced with

tar -zxf scrollutil1.12.tar.gz

Both commands will create a directory named scrollutil1.12, with the subdirectories demos, doc, and scripts.

On Windows, use WinZip or some other program capable of unpacking the distribution file scrollutil1_12.zip into the directory scrollutil1.12, with the subdirectories demos, doc, and scripts.

Notice that in tklib the Scrollutil demos directory is replaced with the subdirectory scrollutil of the examples directory.  Please take this into account when reading the examples below.

How to Use It?

The Scrollutil distribution provides two packages, called Scrollutil and Scrollutil_tile.  The main difference between the two is that Scrollutil_tile enables the tile-based, theme-specific appearance of scrollarea, scrollsync, and scrollableframe widgets, and provides the themed scrollednotebook widget; this package requires Tcl/Tk 8.4 or higher and tile 0.8 or higher.  It is not possible to use both packages in one and the same application, because both are implemented in the same scrollutil namespace and provide identical commands (except for the scrollutil::scrollednotebook command, which is provided by the Scrollutil_tile package only).

To be able to access the commands and variables defined in the package Scrollutil, your scripts must contain one of the lines

package require scrollutil ?version?
package require Scrollutil ?version?

You can use either one of the two statements above because the file scrollutil.tcl contains both lines

package provide scrollutil ...
package provide Scrollutil ...

Likewise, to be able to access the commands and variables defined in the package Scrollutil_tile, your scripts must contain one of the lines

package require scrollutil_tile ?version?
package require Scrollutil_tile ?version?

Again, you can use either one of the two statements above because the file scrollutil_tile.tcl contains both lines

package provide scrollutil_tile ...
package provide Scrollutil_tile ...

You are free to remove one of these two lines from scrollutil.tcl and scrollutil_tile.tcl, respectively, if you want to prevent the corresponding packages from making themselves known under two different names each.  Of course, by doing so you restrict the argument of  package require  to a single name.

Since the packages Scrollutil and Scrollutil_tile are implemented in the scrollutil namespace, you must either invoke the

namespace import scrollutil::pattern ?scrollutil::pattern ...?

command to import the procedures you need, or use qualified names like scrollutil::scrollarea.  In the examples below we have chosen the latter approach.

To access Scrollutil variables, you must use qualified names.  There are only four Scrollutil variables that are designed to be accessed outside the namespace scrollutil:

The Scrollutil_tile package checks whether the required Tk and tile versions are present, by executing the commands

package require Tk 8.4
if {$::tk_version < 8.5 || [regexp {^8\.5a[1-5]$} $::tk_patchLevel]} {
    package require tile 0.8
}

The second command above reflects the fact that, beginning with Tk 8.5a6, tile is integrated into the Tk core and therefore it should only be loaded explicitly when using an earlier Tk version.

More on scrollutil::scalingpct

The way Scrollutil initializes the variable scrollutil::scalingpct depends on the windowing system:

On Windows and Mac OS X/11+ the scaling percentage is computed from  [tk scaling].  Note that on Mac OS X/11+ the result is always 100, regardless of the display's scaling level.  On this system the desktop engine automatically scales everything as needed.

On X11, computing the scaling percentage from  [tk scaling]  is done as fallback method only, because the implementation of display scaling is highly dependent on the desktop environment and it mostly manipulates system resources that are resident outside of Xlib, which Tk is based on.  (Traditional X applications like bitmap and xmag are also affected by this.)  With the exception of Xfce and MATE, Scrollutil computes the scaling percentage from the value of the X resource Xft.dpi, by executing the xrdb application.  On GNOME-based systems where xrdb is not installed per default (e.g., Solus GNOME and Solus Budgie), it uses the xrandr application and the file ~/.config/monitors.xml instead.

The additional steps described in the rest of this section are only performed if the scaling percentage is greater than 100:

After getting the scaling percentage on X11, Scrollutil sets the scaling factor to be used by Tk to convert between physical units and pixels, by passing the scaling factor corresponding to the scaling percentage to the  tk scaling  command.

When initializing the variable scrollutil::scalingpct on X11, Scrollutil also corrects the sizes of the standard fonts if needed.  These fonts (TkDefaultFont, TkTextFont, etc.) are defined in the file $tk_library/ttk/fonts.tcl.  For quite a long time, the font sizes for X11 given in this file were sizes in pixels, which was not suitable for use on HiDPI displays.  This caused several Linux distributions to bundle patched versions of this file, in which the sizes in pixels are replaced with sizes in points.  The same fix was committed in February 2020 into the Tk core repository and is now contained in Tk 8.7a5 and later.  To make sure that, regardless of the Tk version, the font sizes will suit the display's scaling level, Scrollutil examines this library file and, if the latter contains sizes in pixels, then it sets the -size option of the standard fonts to corresponding sizes in points (without altering the file).  In addition, for the HiDPI mode on Xfce and MATE, Scrollutil doubles the sizes (in points) of the standard fonts (the way display scaling works on these desktops makes this necessary).

The code responsible for the initialization of the variable scrollutil::scalingpct also scales:

In addition, the above-mentioned variable initialization code makes sure that in the vista and xpnative themes the indicators of the ttk::checkbutton and ttk::radiobutton widgets will appear properly scaled, regardless of the Tk release being used.  (A long-standing bug in the implementation of these widgets was fixed in May 2020 and is now contained in both Tk 8.6.11 and later and 8.7a5 and later, but Scrollutil provides a workaround for the Tk versions that are still affected by this bug.)

Contents     Start page


Examples

The Helper Script styleUtil.tcl

All the examples in the demos directory use tile (ttk) widgets and contain the lines

set dir [file dirname [info script]]
source [file join $dir styleUtil.tcl]

The script styleUtil.tcl starts with a comment related to the -autohidescrollbars and -setfocus scrollarea configuration options:

#
# To set the "-autohidescrollbars" or "-setfocus" option of all scrollarea
# widgets in all demo scripts to true, uncomment the corresponding line below:
#
# option add *Scrollarea.autoHideScrollbars 1
# option add *Scrollarea.setFocus           1

You are free to follow this hint or to run the demo scripts with the default  -autohidescrollbars 0  and  -setfocus 0  scrollarea settings.

On X11, the script sets the theme to a slightly patched variant of the clam theme (having smaller ttk::button widgets as well as ttk::treeview and tablelist headers).  Next, it patches a few ttk widget styles and defines the style Small.Toolbutton.

The patch for the style TCombobox makes sure that the (readonly) ttk::combobox widgets of the themes alt, clam, classic, and default will show whether they have the focus.  This basic requirement, which makes the keyboard navigation more user-friendly, is already fulfilled by the themes vista, xpnative, and aqua.

The ttk::button widgets of the style Small.Toolbutton created by the procedure createToolbutton, implemented in this helper script, will appear raised when they have the focus.  Again, this makes the keyboard navigation more user-friendly.

A Scrolled tablelist Widget

This example shows how you can greatly simplify the creation of a scrolled tablelist by using a scrollarea widget.

The script ScrolledTablelist1.tcl in the demos directory creates a horizontally and vertically scrolled tablelist widget having two header rows and one title column, and manages the two scrollbars in such a way that the vertical scrollbar appears below the tablelist's header and the horizontal one starts to the right of the widget's title column area:

ScrolledTablelist

The script achieves these requirements using traditional scrollbar management, which is shown below in red color:

package require Tk 8.5
package require tablelist_tile 6.3
set dir [file dirname [info script]]
source [file join $dir styleUtil.tcl]

wm title . "Scrolled Tablelist"

#
# Create the tablelist and the scrollbars as children
# of a frame having -borderwidth 1 and -relief sunken
#
set f   [ttk::frame .f]
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 7p -pady 7p
pack $f   -expand yes -fill both

The script ScrolledTablelist2.tcl in the demos directory replaces the rather technical code above with just a few lines (shown below in red color), by embedding the tablelist into a scrollarea widget.  It requires Tablelist version 6.5, which is needed so the -respectheader and -respecttitlecolumns scrollarea options can work as expected (for earlier Tablelist versions these options are silently ignored).  As a further benefit, the scrollbars created with this method will have the default display mode dynamic.

package require Tk 8.5
package require tablelist_tile 6.5
package require scrollutil_tile
set dir [file dirname [info script]]
source [file join $dir styleUtil.tcl]

wm title . "Scrolled Tablelist"

#
# Create the tablelist within a scrollarea
#
set f  [ttk::frame .f]
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 7p -pady 7p
pack $f  -expand yes -fill both

A Scrolled text Widget

The script ScrolledText.tcl in the demos directory shows how the scrollarea widget circumvents the potential shimmering effect in connection with text widgets.

ScrolledText

Here is the relevant code, in which the lines related to the scrollarea widget are shown in red color:

package require scrollutil_tile
set dir [file dirname [info script]]
source [file join $dir styleUtil.tcl]

wm title . "Scrolled Text"

#
# Create a text widget within a scrollarea
#
set f  [ttk::frame .f]
set sa [scrollutil::scrollarea $f.sa -lockinterval 10]
set txt [text $sa.txt -font TkFixedFont -width 49 -height 12 \
         -spacing1 1.5p -spacing3 1.5p -wrap none]
$sa setwidget $txt

#
# Populate the text widget and set the background color of line #25 to red
#
for {set i 1} {$i <= 30} {incr i} {
    set j [expr {2*$i}]
    $txt insert end [string repeat x $j]\n
}
$txt delete 30.end
$txt tag configure bgRed -background red
$txt tag add bgRed 25.0 25.end

. . .

#
# Manage the scrollarea
#
pack $sa -expand yes -fill both -padx 7p -pady 7p
pack $f  -expand yes -fill both

#
# Adjust the vertical view in the text window
# so that line #25 becomes the bottom line
#
tkwait visibility $txt
after 100 [list $txt yview 14.0]

The script creates a text widget $txt embedded into a scrollarea, populates it with 30 lines, and adjusts the vertical view in the text window so that line #25 becomes the bottom line.  This line has 50 characters, hence it doesn't fit completely into the window, whose width is 49 characters.  Consequently, the command  $txt xview  will return the list  {0.0 0.98},  hence the scrollarea's horizontal scrollbar will be mapped and will obscure most part of the bottom line.  Since this line has red background, it is easy to see how much of it sticks out above the upper edge of the scrollbar.

Let's analyze what happens if the text widget's height is decreased by dragging the main window's upper or lower edge, just until the red pixels get obscured by the horizontal scrollbar.  After performing this action, line #25 is completely out of view and the new bottom line is line #24, which has 48 characters, hence the command  $txt xview  will return  {0.0 1.0}.  Normally, this would cause the horizontal scrollbar to be unmapped.  However, that would make line #25 to the bottom line, thus causing the horizontal scrollbar to be mapped again.  This time the scrollbar would completely obscure this line, which would result in line #24 to become the bottom line, which would cause the scrollbar to be unmapped again, and so on.  In other words, the horizontal scrollbar would get mapped and unmapped in an endless loop, giving rise to an annoying flickering effect.  The built-in locking mechanism of the scrollarea widget guards against such potential endless loops.  To make sure that the locking will work as expected, we have set the -lockinterval scrollarea option to 10 (recall that the default value is 1).

Synchronizing Two listbox Widgets

The script SyncListboxes.tcl in the demos directory creates two listboxes within a scrollsync widget, which in turn is embedded into a scrollarea.

SyncListboxes

Here is the relevant code, in which the lines related to the scrollarea and scrollsync widgets are shown in red color:

package require scrollutil_tile
set dir [file dirname [info script]]
source [file join $dir styleUtil.tcl]

wm title . "European Countries"

. . .

set f  [ttk::frame .f]

. . .

#
# Create a scrollsync widget within a scrollarea
#
set sa [scrollutil::scrollarea $f.sa]
set ss [scrollutil::scrollsync $sa.ss]
$sa setwidget $ss

#
# Populate the scrollsync widget with two listboxes
#

. . .

set lb1 [listbox $ss.lb1 -activestyle none -highlightthickness 0 -width 16]
set lb2 [listbox $ss.lb2 -activestyle none -highlightthickness 0 -width 16]
$ss setwidgets [list $lb1 $lb2]

. . .

grid $lb1 $lb2 -sticky news -padx {0 1.5p}
grid rowconfigure    $ss 0 -weight 1
grid columnconfigure $ss 0 -weight 1
grid columnconfigure $ss 1 -weight 1

. . .

pack $sa -side top -expand yes -fill both -padx 7p -pady {1.5p 7p}
pack $f  -expand yes -fill both

. . .

Synchronizing Three tablelist Widgets

The script SyncTablelists.tcl in the demos directory creates three tablelists within a scrollsync widget, which in turn is embedded into a scrollarea.

SyncTablelists

The relevant code is similar to the one shown in the previous example:

package require tablelist_tile
package require scrollutil_tile
set dir [file dirname [info script]]
source [file join $dir styleUtil.tcl]

wm title . "Synchronized Tablelists"

. . .

set f  [ttk::frame .f]

. . .

#
# Create a scrollsync widget within a scrollarea
#
set sa [scrollutil::scrollarea $f.sa]
set ss [scrollutil::scrollsync $sa.ss]
$sa setwidget $ss

#
# Populate the scrollsync widget with three tablelists
#

if {$ttk::currentTheme ne "aqua"} {
    option add *Tablelist.background            white
    option add *Tablelist.stripeBackground      #f0f0f0
}

for {set n 1; set colWidth 40} {$n <= 3} {incr n; incr colWidth 20} {
    set tbl [tablelist::tablelist $ss.tbl$n \
             -columns [list 0 "Column 0" left  $colWidth "Column 1" left]]
    set tbl$n $tbl

    for {set i 0} {$i < 40} {incr i} {
        $tbl insert end [list "cell $i,0" "cell $i,1"]
    }
}
$ss setwidgets [list $tbl1 $tbl2 $tbl3]

grid $tbl1 $tbl2 $tbl3 -sticky news -padx {0 1.5p}
grid rowconfigure    $ss 0 -weight 1
grid columnconfigure $ss 0 -weight 1
grid columnconfigure $ss 1 -weight 1
grid columnconfigure $ss 2 -weight 1

. . .

pack $sa -side top -expand yes -fill both -padx 7p -pady {1.5p 7p}
pack $f  -expand yes -fill both

. . .

The option database settings above for the -background and -stripebackground tablelist configuration options are not present in case of the aqua theme, because for this theme the default values of these options are not only aqua-specific, but in addition on Mac OS 10.14 (Mojave) and later they also depend on the current system appearance (Light Mode or Dark Mode).

Notice that column #1 of the three tablelist widgets is 40, 60, and 80 characters wide, respectively.  For this reason, when scrolling horizontally to the right, the left table's view will reach its horizontal end position first, then that of the midde table, and as last one the view of the right table.

A Script Using a scrollutil::scrollableframe Widget

The script SuScrollableFrmDemo1.tcl in the demos directory creates a scrollutil::scrollableframe widget embedded into a scrollarea and creates mouse wheel event bindings for the binding tag "all" with the aid of the scrollutil::createWheelEventBindings command.  Recall that the scrollableframe was automatically registered for scrolling by these bindings at creation time, hence there is no need to invoke the scrollutil::enableScrollingByWheel command for it again.  After that, the script populates the content frame of the scrollableframe with ttk::label widgets displaying the names of the European countries, ttk::combobox widgets for selecting the corresponding capital cities, and ttk::button widgets of the style Small.Toolbutton (created by using the procedure createToolbutton, implemented in the file styleUtil.tcl) for the less patient users, displaying the text "Resolve".

ScrollableFrmDemo1

Here is the relevant code:

package require scrollutil_tile
set dir [file dirname [info script]]
source [file join $dir styleUtil.tcl]

wm title . "European Capitals Quiz"

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

#
# Create mouse wheel event bindings for the binding tag "all"
#
scrollutil::createWheelEventBindings all

#
# Get the content frame and populate it
#

set cf [$sf contentframe]

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

    #
    # Make the keyboard navigation more user-friendly
    #
    bind $w <<TraverseIn>> [list $sf see %W]

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

    . . .

    incr row
}

. . .

We make the keyboard navigation more user-friendly with the aid of the see subcommand of the scrollableframe widget when handling the <<TraverseIn>> virtual event for the ttk::combobox and (not shown above) ttk::button widgets.  In addition, we invoke the scrollutil::adaptWheelEventHandling command for every ttk::combobox widget, which is needed for a user-friendly event handling, being that this widget has built-in bindings for the mouse wheel events.  Due to this command, the mouse wheel events over one of the ttk::combobox widgets will only select the next/previous capital city if the widget has the focus, otherwise they will scroll the scrollableframe.

With this script you can also test the scanning in the scrollableframe:  If you press mouse button 1 over a free space of the scrollableframe window then the cursor will take on the shape of a pointing hand, and by draggging the mouse, the content frame will drag at high speed through the window, in the direction the mouse moves.

A Script Using a BWidget ScrollableFrame Widget

The script BwScrollableFrmDemo1.tcl in the demos directory creates a BWidget ScrollableFrame embedded into a scrollarea widget, creates mouse wheel event bindings for the binding tag "all" with the aid of the scrollutil::createWheelEventBindings command, and invokes the scrollutil::enableScrollingByWheel command for this ScrollableFrame, thus registering the latter for scrolling by these bindings.  After that it populates the content frame of the ScrollableFrame with the same widgets as SuScrollableFrmDemo1.tcl in the previous example.

Here is the relevant code:

package require BWidget
Widget::theme yes
package require scrollutil_tile
set dir [file dirname [info script]]
source [file join $dir styleUtil.tcl]

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

    #
    # Make the keyboard navigation more user-friendly
    #
    bind $w <<TraverseIn>> [list $sf see %W]

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

    . . .

    incr row
}

. . .

A Script Using an iwidgets::scrolledframe Widget

The script ScrolledFrmDemo1.tcl in the demos directory creates an iwidgets::scrolledframe widget, creates mouse wheel event bindings for the binding tag "all" with the aid of the scrollutil::createWheelEventBindings command, and invokes the scrollutil::enableScrollingByWheel command for this scrolledframe, thus registering the latter for scrolling by these bindings.  After that it populates the content frame of the scrolledframe with the same widgets as SuScrollableFrmDemo1.tcl and BwScrollableFrmDemo1.tcl in the two previous examples.

Here is the relevant code:

if {[catch {package require iwidgets} result1] != 0 &&
    [catch {package require Iwidgets} result2] != 0} {
    error "$result1; $result2"
}
set dir [file dirname [info script]]
source [file join $dir scrolledwidgetPatch.itk] ;# adds ttk::scrollbar widgets
package require scrollutil_tile
source [file join $dir styleUtil.tcl]

wm title . "European Capitals Quiz"

. . .

#
# Create a scrolledframe
#
set f  [ttk::frame .f]
set sf [iwidgets::scrolledframe $f.sf -borderwidth 1 -relief sunken \
        -scrollmargin 0]
. . .

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

#
# Get the content frame and populate it
#

set cf [$sf childsite]
. . .

<exactly as in the two previous examples, except the stuff related to keyboard navigation>

. . .

The code related to keyboard navigation is not present in this example, because the iwidgets::scrolledframe widget doesn't provide a see subcommand.

A Script Using Two scrollutil::scrollableframe Widgets

The script SuScrollableFrmDemo2.tcl in the demos directory creates a scrollutil::scrollableframe widget embedded into a scrollarea and then sources the script SuScrollableFrmContent.tcl, which populates the content frame of the scrollableframe with the following widgets:

With the exception of ttk::label, ttk::entry, and ttk::separator, all these widgets have bult-in mouse wheel event bindings.

ScrollableFrmDemo2

Here is the relevant code:

package require Tk 8.5.9                        ;# for ttk::spinbox
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
set dir [file dirname [info script]]
source [file join $dir styleUtil.tcl]

wm title . "Scrollutil Demo"

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

#
# Get the content frame and populate it
#
set cf [$sf contentframe]
source [file join $dir SuScrollableFrmContent.tcl]

#
# Make the keyboard navigation more user-friendly
#
foreach w [list $cb $sb $e $me] {
    bind $w <<TraverseIn>> [list $sf see %W]
}
foreach w [list $txt $lb $tbl $tv] {
    bind $w <<TraverseIn>> [list seeScrollarea $sf %W]
}
proc seeScrollarea {sf w} { $sf see [scrollutil::getscrollarea $w] }

Whenever the <<TraverseIn>> virtual event is sent to one of the four widgets created within scrollareas, we query the path name of the corresponding scrollarea via scrollutil::getscrollarea and bring that scrollarea (including the scrollbars and the border) into view rather than just the widget in question.  While in this script we could have used  [winfo parent]  instead, the command scrollutil::getscrollarea is the recommended one, being that it works also for widgets that are no children of the corresponding scrollareas.

Here is the additional stuff related to the mouse wheel events, using the Scrollutil commands described in the What Is Scrollutil? section:

#
# Create mouse wheel event bindings for the binding tag "all"
#
scrollutil::createWheelEventBindings all

#
# 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

Notice that we have passed, among others, the tablelist widget to the scrollutil::adaptWheelEventHandling command.  This will only work for Tablelist versions 6.4 and later, because the command handles tablelist widgets by setting their -xmousewheelwindow and -ymousewheelwindow options to the path name of the containing toplevel window, and these options were introduced in Tablelist version 6.4.  (For earlier Tablelist versions the command silently ignores any tablelist widget passed to it as argument.)

As already mentioned, in the file SuScrollableFrmContent.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]
scrollutil::addMouseWheelSupport $txt
$_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 ...

In the case of the text, listbox, and tablelist widgets we use scrollarea widgets with their default  -borderwidth 1 -relief sunken  settings, which will cause the setwidget subcommand of the associated Tcl commands to set the -borderwidth option of the text, listbox, and tablelist widgets to 0.  On the other hand, for the ttk::treeview we use a scrollarea widget with  -borderwidth 0,  because the ttk::treeview has a border of width 1 and doesn't support the -borderwidth configuration option.

For our text widget we prefer a mouse wheel event handling that scrolls the widget by lines rather than pixels, as done by the Text class bindings in Tk 8.5 and later; we achieve this by passing the path name $txt to the scrollutil::addMouseWeelSupport command.

The file SuScrollableFrmContent.tcl implements just a minimal interaction between four of the already mentioned widgets within the content frame:  By selecting a Tablelist release from the ttk::combobox $cb, the ttk::spinbox $sb is set to the corresponding number of changes, the comment associated with that release is inserted into the ttk::entry $e, and the corresponding item of the tablelist $tbl is selected and brought into view within the tablelist widget.

The file SuScrollableFrmContent.tcl contains also the implementation of the procedure configTablelist, associated with the "Configure Tablelist Widget" button as the value of its -command option.  This procedure opens a toplevel window that contains a scrollutil::scrollableframe widget created with the  -fitcontentwidth yes  setting within a scrollarea.  After that it populates the content frame of the scrollableframe with ttk::label, ttk::combobox, ttk::spinbox, ttk::entry, and ttk::checkbutton widgets used to display and edit the configuration options of the tablelist widget.  The procedure handles the <<TraverseIn>> virtual event sent to one of these widgets with the aid of the scrollableframe's see subcommand.  Whenever a ttk::combobox or ttk::spinbox is created, the scrollutil::adaptWheelEventHandling command is invoked for it, being that these widgets have built-in bindings for the mouse wheel events.

The widgets populating the content frame are managed using grid.  In case of the ttk::entry widgets we invoke grid with  -sticky we.  Due to this and the  -fitcontentwidth yes  scrollableframe setting, the ttk::entry widgets will stretch or shrink whenever the width of the scrollableframe changes as a result of resizing the toplevel window.

TablelistConfig

A Script Using Two BWidget ScrollableFrame Widgets

The script BwScrollableFrmDemo2.tcl in the demos directory creates a BWidget ScrollableFrame embedded into a scrollarea widget and then sources the script BwScrollableFrmContent.tcl, which populates the content frame of the ScrollableFrame with the same widgets as SuScrollableFrmContent.tcl in the previous example.

Here is the relevant code:

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
set dir [file dirname [info script]]
source [file join $dir styleUtil.tcl]

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 [file join $dir BwScrollableFrmContent.tcl]

#
# Make the keyboard navigation more user-friendly
#
foreach w [list $cb $sb $e $me] {
    bind $w <<TraverseIn>> [list $sf see %W]
}
foreach w [list $txt $lb $tbl $tv] {
    bind $w <<TraverseIn>> [list seeScrollarea $sf %W]
}
proc seeScrollarea {sf w} { $sf see [scrollutil::getscrollarea $w] }

The additional stuff related to the mouse wheel events contains the same Scrollutil command invocations as the one in the previous example, except that in addition it registers the ScrollableFrame for scrolling with the mouse wheel:

#
# 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

. . .

The file BwScrollableFrmContent.tcl contains also the implementation of the procedure configTablelist, associated with the "Configure Tablelist Widget" button as the value of its -command option.  This procedure opens a toplevel window that contains a BWidget ScrollableFrame created with the  -constrainedwidth yes  setting within a scrollarea widget and invokes the scrollutil::enableScrollingByWheel command for this ScrollableFrame, thus registering the latter for scrolling by the already created mouse wheel event bindings for the binding tag "all".  After that it populates the content frame of the ScrollableFrame with ttk::label, ttk::combobox, ttk::spinbox, ttk::entry, and ttk::checkbutton widgets used to display and edit the configuration options of the tablelist widget.  The procedure handles the <<TraverseIn>> virtual event sent to one of these widgets with the aid of the ScrollableFrame's see subcommand.  Whenever a ttk::combobox or ttk::spinbox is created, the scrollutil::adaptWheelEventHandling command is invoked for it, being that these widgets have built-in bindings for the mouse wheel events.

Again, all this is nearly identical to what we did in the previous example.

A Script Using Two iwidgets::scrolledframe Widgets

The script ScrolledFrmDemo2.tcl in the demos directory creates an iwidgets::scrolledframe widget and then sources the file ScrolledFrmContent.tcl, which populates the content frame of the scrolledframe with the same widgets as SuScrollableFrmContent.tcl and BwScrollableFrmContent.tcl in the two previous examples.

Here is the relevant code:

package require Tk 8.5.9                        ;# for ttk::spinbox
if {[catch {package require iwidgets} result1] != 0 &&
    [catch {package require Iwidgets} result2] != 0} {
    error "$result1; $result2"
}
set dir [file dirname [info script]]
source [file join $dir scrolledwidgetPatch.itk] ;# adds ttk::scrollbar widgets
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
source [file join $dir styleUtil.tcl]

wm title . "Scrollutil Demo"

. . .

#
# Create a scrolledframe
#
set tf [ttk::frame .tf]
set sf [iwidgets::scrolledframe $tf.sf -borderwidth 1 -relief sunken \
        -scrollmargin 0]
. . .

#
# Get the content frame and populate it
#
set cf [$sf childsite]
. . .
source [file join $dir ScrolledFrmContent.tcl]

The additional stuff related to the mouse wheel events contains the same Scrollutil command invocations as the one in the previous example.

The file ScrolledFrmContent.tcl contains also the implementation of the procedure configTablelist, associated with the "Configure Tablelist Widget" button as the value of its -command option.  This procedure opens a toplevel window that contains an iwidgets::scrolledframe widget with a manually implemented equivalent of the  -fitcontentwidth yes  scrollutil::scrollableframe and  -constrainedwidth yes  BWidget ScrollableFrame settings and invokes the scrollutil::enableScrollingByWheel command for this scrolledframe, thus registering the latter for scrolling by the already created mouse wheel event bindings for the binding tag "all".  After that it populates the content frame of the scrolledframe with ttk::label, ttk::combobox, ttk::spinbox, ttk::entry, and ttk::checkbutton widgets used to display and edit the configuration options of the tablelist widget.  Whenever a ttk::combobox or ttk::spinbox is created, the scrollutil::adaptWheelEventHandling command is invoked for it, being that these widgets have built-in bindings for the mouse wheel events.

Again, all this is nearly identical to what we did in the two previous examples.

A scrollutil::scrollednotebook Demo

The script ScrolledNotebookDemo.tcl in the demos directory creates a scrollutil::scrollednotebook widget and populates it with panes containing scrollareas that wrap text widgets displaying the contents of the Ttk library files.  After that it sets the width of the scrollednotebook to a value computed from the requested width of the scrollarea widgets and the padding applied to the panes, and provides pop-up menu items for left/right moving and closing the tabs.

ScrolledNotebookDemo

Here is the relevant code:

package require scrollutil_tile
set dir [file dirname [info script]]
source [file join $dir styleUtil.tcl]

wm title . "Ttk Library Scripts"

scrollutil::addclosetab My.TNotebook

set pct $scrollutil::scalingpct
image create photo fileImg -file [file join $dir file$pct.gif]

#
# Create a scrollednotebook widget having closable (and, per default,
# movable) tabs and populate it with panes that contain scrolled
# text widgets displaying the contents of the Ttk library files
#
set f  [ttk::frame .f]
set nb [scrollutil::scrollednotebook $f.nb -style My.TNotebook \
        -forgetcommand condCopySel -leavecommand condCopySel]
set panePadding [expr {$ttk::currentTheme eq "aqua" ? 0 : "7p"}]
cd [expr {[info exists ttk::library] ? $ttk::library : $tile::library}]
foreach fileName [lsort [glob *.tcl]] {
    set baseName [string range $fileName 0 end-4]
    set sa [scrollutil::scrollarea $nb.sa_$baseName -lockinterval 10]
    if {$ttk::currentTheme eq "vista"} {
        $sa configure -relief solid
    }
    set txt [text $sa.txt -font TkFixedFont -takefocus 1 -wrap none]
    catch {$txt configure -tabstyle wordprocessor}      ;# for Tk 8.5 and later
    scrollutil::addMouseWheelSupport $txt       ;# old-school wheel support
    $sa setwidget $txt

    set chan [open $fileName]
    $txt insert end [read -nonewline $chan]
    close $chan
    $txt configure -state disabled
    bind $txt <Button-1> { focus %W }   ;# for Tk versions < 8.6.11/8.7a4

    $nb add $sa -text $fileName -image fileImg -compound left \
                -padding $panePadding
}

#
# Set the scrollednotebook's width.  Take into account that in the aqua
# theme the -padding option of the TNotebook style is set to {18 8 18 17}
# and the panes are drawn with a hard-coded internal padding of {9 5 9 9}.
#
update idletasks
set width [expr {[winfo reqwidth $sa] + [winfo reqwidth $sa.vsb]}]
incr width [expr {$ttk::currentTheme eq "aqua" ?
                  2*27 : 2*[winfo pixels . 7p] + 4}]
$nb configure -width $width

proc condCopySel {nb widget} {
    set txt $widget.txt
    if {[$txt tag nextrange sel 1.0 end] eq ""} {
        return 1
    }

    set btn [tk_messageBox -title "Copy Selection?" -icon question \
             -message "Do you want to copy the selection to the clipboard?" \
             -type yesnocancel]
    switch $btn {
        yes     { tk_textCopy $txt; return 1 }
        no      { return 1 }
        cancel  { return 0 }
    }
}

#
# Create a binding for moving and closing the tabs interactively
#
bind $nb <<MenuItemsRequested>> { populateMenu %W %d }

proc populateMenu {nb data} {
    foreach {menu tabIdx} $data {}
    set tabCount [$nb index end]
    set prevIdx [expr {($tabIdx - 1) % $tabCount}]
    set nextIdx [expr {($tabIdx + 1) % $tabCount}]
    set widget [lindex [$nb tabs] $tabIdx]

    $menu add command -label "Move Tab Left"  -command \
        [list $nb insert $prevIdx $widget]
    $menu add command -label "Move Tab Right" -command \
        [list $nb insert $nextIdx $widget]
    $menu add separator
    $menu add command -label "Close Tab" -command \
        [list $nb forget $tabIdx]
}

. . .

We add the closetab element to the tabs of the My.TNotebook style with the aid of the scrollutil::addclosetab command, and create a scrollednotebook widget of this style.  Note that, while in this example we could have used the default ttk::notebook style TNotebook instead, working with different ttk::notebook styles is necessary in applications having both notebooks with the closetab element in their tabs and notebooks without this element.

Note that the state of the text widgets is set to disabled, but the user can select a text range and then copy the selection into the clipboard via Control-c (Command-c on Mac OS X/11+).  When attempting to close a tab or to leave the currently selected one, the path name of the corresponding scrollarea widget is automatically passed to the condCopySel procedure, which was specified as the value of the -forgetcommand and -leavecommand options.  This procedure checks the text widget child of the scrollarea for the existence of a selection and enables the user to make sure that the selection will be copied to the clipboard before closing or leaving the tab, or to cancel the attempted operation on it.  In a real-world application, the procedure(s) specified as the value(s) of the two above-mentioned options typically ask the user whether to save the changes before closing or leaving the tab, or to cancel the attempted operation on it.

We also make use of the virtual event <<MenuItemsRequested>> to populate the pop-up menu shown when the user clicks a tab with mouse button 3.

When running the script, the scrollednotebook widget appears with the configured width and tabs displaying the unstripped file names.  For comparison:  The very similar script TtkNotebookDemo.tcl in the demos directory creates a ttk::notebook widget and populates it in the same way as the script ScrolledNotebookDemo.tcl discussed above.  Although the script also sets the notebook's -width option to a value corresponding to the requested width of the scrollarea widgets and the padding applied to the panes, the ttk::notebook appears with an exorbitantly large width and (on most displays) with squeezed tabs.  If you resize it to a reasonable width, its tabs become so small that their texts are no longer readable.

A scrollutil::plainnotebook Demo

The script PlainNotebookDemo.tcl in the demos directory creates a scrollutil::plainnotebook widget and populates it with panes containing scrollareas that wrap text widgets displaying the contents of the Ttk library files.  After that it provides pop-up menu items for moving the tabs upward/downward and closing them.

PlainNotebookDemo

The relevant code is nearly identical to the one shown in the previous example, except that here we make the tabs closable by using the -closabletabs plainnotebook option and the widget's width is set automatically to fit that of its panes:

package require scrollutil_tile
set dir [file dirname [info script]]
source [file join $dir styleUtil.tcl]

wm title . "Ttk Library Scripts"

set pct $scrollutil::scalingpct
image create photo fileImg -file [file join $dir file$pct.gif]

#
# Create a plainnotebook widget having closable (and, per default,
# movable) tabs and populate it with panes that contain scrolled
# text widgets displaying the contents of the Ttk library files
#
set f  [ttk::frame .f]
set nb [scrollutil::plainnotebook $f.nb -closabletabs 1 \
        -forgetcommand condCopySel -leavecommand condCopySel]
. . .

proc condCopySel {nb widget} {
    . . .
}

#
# Create a binding for moving and closing the tabs interactively
#
bind $nb <<MenuItemsRequested>> { populateMenu %W %d }

proc populateMenu {nb data} {
    . . .
}

. . .

A scrollutil::pagesman Demo

The script PagesManDemo.tcl in the demos directory demonstrates the use of the scrollutil::pagesman widget having scrollutil::plainnotebook widgets as pages.  It creates a pagesman widget and adds four plainnotebook children as pages to it.  The panes of the first page display the contents of the Tk library files, to be found in the directory $tk_library.  The panes of the three other pages display the contents of the GIF image files, message catalogs, and Ttk scripts, situated in the subdirectories images, msgs, and (for Tk 8.5a5 and later) ttk, respectively.

PagesManDemo

The user can switch from the first page to the three other ones with the aid of the three toolbuttons displaying a folder image and the descend style element.  To switch back, he or she has to use the ascend toolbutton, shown in the top-left corner of the respective plainnotebook widget.

PagesManDemoImages

Here is the relevant code:

package require scrollutil_tile
set dir [file dirname [info script]]
source [file join $dir styleUtil.tcl]

wm title . "Tk Library Files"

set pct $scrollutil::scalingpct
image create photo fileImg   -file [file join $dir file$pct.gif]
image create photo folderImg -file [file join $dir folder$pct.gif]

#
# Populates a given plainnotebook widget with panes that display the contents
# of the files of the specified suffix within the current working directory
#
proc populateNotebook {nb sfx} {
    set panePadding [expr {$ttk::currentTheme eq "aqua" ? 0 : "7p"}]
    foreach fileName [lsort -dictionary [glob *.$sfx]] {
        set baseName [string range $fileName 0 end-4]
        set sa [scrollutil::scrollarea $nb.sa_$baseName]
        if {$sfx eq "gif"} {
            set canv [canvas $sa.canv -background silver]
            set img [image create photo -file $fileName]
            $canv create image 10 10 -anchor nw -image $img
            set width  [expr {[image width  $img] + 20}]
            set height [expr {[image height $img] + 20}]
            $canv configure -scrollregion [list 0 0 $width $height]
            scrollutil::addMouseWheelSupport $canv
            $sa setwidget $canv
        } else {
            $sa configure -lockinterval 10
            . . .

        }
        $nb add $sa -text $fileName -image fileImg -compound left \
                    -padding $panePadding
    }
}

#
# Create a pagesman widget
#
set f [ttk::frame .f]
set pm [scrollutil::pagesman $f.pm -leavecommand pmLeaveCmd]

#
# Add option database entries for the -closabletabs,
# -forgetcommand, and -leavecommand plainnotebook options
#
option add *Plainnotebook.closableTabs  1
option add *Plainnotebook.forgetCommand condCopySel
option add *Plainnotebook.leaveCommand  condCopySel

#
# Create a plainnotebook child displaying the contents of the Tk library files
#
set nbTk [scrollutil::plainnotebook $pm.nbTk]
$pm add $nbTk
$nbTk addbutton 1 "Image Files"      folderImg
$nbTk addbutton 2 "Message Catalogs" folderImg
$nbTk addbutton 3 "Ttk Scripts"      folderImg
$nbTk addseparator
$nbTk addlabel "Tk Scripts"
cd $tk_library
populateNotebook $nbTk "tcl"

#
# Create a plainnotebook child displaying the images for the Tcl (Powered) Logo
#
set nbImgs [scrollutil::plainnotebook $pm.nbImgs -caller 0 -title "Image Files"]
$pm add $nbImgs
cd $tk_library/images
populateNotebook $nbImgs "gif"

#
# Create a plainnotebook child displaying the contents of the message catalogs
#
set nbMsgs [scrollutil::plainnotebook $pm.nbMsgs -caller 0 -title \
            "Message\nCatalogs"]
$pm add $nbMsgs
cd $tk_library/msgs
populateNotebook $nbMsgs "msg"

#
# Create a plainnotebook child displaying the contents of the Ttk library files
#
set nbTtk [scrollutil::plainnotebook $pm.nbTtk -caller 0 -title "Ttk Scripts"]
$pm add $nbTtk
### cd $tk_library/ttk          ;# works for Tk versions 8.5a5 and later only
cd [expr {[info exists ttk::library] ? $ttk::library : $tile::library}]
populateNotebook $nbTtk "tcl"

proc pmLeaveCmd {pm nb} {
    return [condCopySel $nb [$nb select]]
}

proc condCopySel {nb widget} {
    global nbImgs
    if {$nb eq $nbImgs || [winfo class $widget] ne "Scrollarea"} {
        return 1
    }

    . . .
}


#
# Create a binding for moving and closing the tabs interactively
#
bind $nb <<MenuItemsRequested>> { populateMenu %W %d }

proc populateMenu {nb data} {
    . . .
}

. . .

The four pages of the pagesman widget, created by using the latter's add subcommand, will have the numerical indices 0, ..., 3.  We pass the page indices 1, 2, and 3 to the first plainnotebook's addbutton subcommand, with which we create the three toolbuttons used to descend from this page to the other ones.  When we create the three other plainnotebook widgets, we set their -caller option to 0, which will make their ascend toolbutton visible and will make sure that invoking this button will switch back to the first plainnotebook.

Contents     Start page