2013-10-30  Andreas Kupries (AS Senior Dev)  <andreask@activestate.com>

	* examples/canvas/crosshairs_for_axes.tcl: [Ticket [19721eff15]].
	* examples/canvas/crosshairs_for_multixyplot.tcl: Updated canvas
	* examples/canvas/crosshairs_scaled.tcl: examples for runnability
	  against an installed tklib. Patch by stu.

2020-02-09  0.7  <andreas_kupries@users.sourceforge.net>

	*
	* Released and tagged Tklib 0.7 ========================
	* 

2013-10-30  Andreas Kupries (AS Senior Dev)  <andreask@activestate.com>

	* examples/canvas/crosshairs_for_axes.tcl: [Ticket [19721eff15]].
	* examples/canvas/crosshairs_for_multixyplot.tcl: Updated canvas
	* examples/canvas/crosshairs_scaled.tcl: examples for runnability
	  against an installed tklib. Patch by stu.

Identifier: tklib
Title:  Tk Standard Library
Description: This package is intended to be a collection of
    Tcl packages that provide utility functions useful to a
    large collection of Tk programmers.
Rights: BSD
Version: 0.6
URL: http://core.tcl.tk/tklib/
Architecture: tcl
Contributor: Aaron Faupell <afaupell at users dot sourceforge dot net>
Contributor: Andreas Kupries <andreas_kupries at users dot sourceforge dot net>

Contributor: Arjen Markus <arjenmarkus at users dot sourceforge dot net>
Contributor: Csaba Nemethi <csaba dot nemethi at t-online dot de>
Contributor: David N. Welton <davidw at dedasys dot com>
Contributor: George Peter Staplin <georgeps at users dot sourceforge dot net>
Contributor: Jean-Luc Fontaine <jfontain at free dot fr>
Contributor: Jeff Hobbs <jeffh at ActiveState dot com>
Contributor: Keith Nash <kjnash at users dot sourceforge dot net>

Identifier: tklib
Title:  Tk Standard Library
Description: This package is intended to be a collection of
    Tcl packages that provide utility functions useful to a
    large collection of Tk programmers.
Rights: BSD
Version: 0.7
URL: http://core.tcl.tk/tklib/
Architecture: tcl
Contributor: Aaron Faupell <afaupell at users dot sourceforge dot net>
Contributor: Andreas Kupries <andreask at activestate dot com>
Contributor: Andreas Kupries (AS Senior Dev) <andreask at activestate dot com>
Contributor: Arjen Markus <arjenmarkus at users dot sourceforge dot net>
Contributor: Csaba Nemethi <csaba dot nemethi at t-online dot de>
Contributor: David N. Welton <davidw at dedasys dot com>
Contributor: George Peter Staplin <georgeps at users dot sourceforge dot net>
Contributor: Jean-Luc Fontaine <jfontain at free dot fr>
Contributor: Jeff Hobbs <jeffh at ActiveState dot com>
Contributor: Keith Nash <kjnash at users dot sourceforge dot net>

'\"
'\" Generated from file 'datefield\&.man' by tcllib/doctools with format 'nroff'
'\" Copyright (c) Keith Vetter <keith@ebook\&.gemstar\&.com>

'\"
.TH "datefield" n 0\&.2 tklib "Tk datefield widget"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
................................................................................
..
.BS
.SH NAME
datefield \- Tk datefield widget
.SH SYNOPSIS
package require \fBTk \fR
.sp
package require \fBdatefield  ?0\&.2?\fR
.sp
\fB::datefield::datefield\fR \fIwidgetpath\fR ?\fIoptions\fR?


.sp
.BE
.SH DESCRIPTION
The \fBdatefield\fR package provides the datefield widget which
is an enhanced text entry widget for the purpose of date entry\&. Only
valid dates of the form MM/DD/YYYY can be entered\&.







.PP
The datefield widget is, in fact, just an entry widget with
specialized bindings\&. This means all the command and options for an
entry widget apply equally here\&.
.SH COMMANDS
.TP
\fB::datefield::datefield\fR \fIwidgetpath\fR ?\fIoptions\fR?
Creates and configures a date field widget\&.
.PP
.SH OPTIONS






See the \fBentry\fR manual entry for details on all available options\&.

.SH EXAMPLE
.CS


 package require datefield

 wm title \&. "Datefield example"
 proc DayOfWeek {args} {
     set now [clock scan $::myDate]
     set ::myDate2 [clock format $now -format %A]
 }
 trace variable myDate w DayOfWeek

 ::datefield::datefield \&.df -textvariable myDate
 label \&.l1 -text "Enter a date:"   -anchor e
 label \&.l2 -text "That date is a:" -anchor e
 label \&.l3 -textvariable myDate2 -relief sunken -width 12

 grid \&.l1 \&.df -sticky ew
 grid \&.l2 \&.l3 -sticky ew
 focus \&.df
................................................................................
.SH KEYWORDS
clock, date, dateentry, entry, widget
.SH CATEGORY
Widget
.SH COPYRIGHT
.nf
Copyright (c) Keith Vetter <keith@ebook\&.gemstar\&.com>


.fi

'\"
'\" Generated from file 'datefield\&.man' by tcllib/doctools with format 'nroff'
'\" Copyright (c) Keith Vetter <keith@ebook\&.gemstar\&.com>
'\" Copyright (c) Thomas Wunderlich <tcl\&.tk@blindenfreizeiten\&.de>
'\"
.TH "datefield" n 0\&.3 tklib "Tk datefield widget"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
................................................................................
..
.BS
.SH NAME
datefield \- Tk datefield widget
.SH SYNOPSIS
package require \fBTk \fR
.sp
package require \fBdatefield  ?0\&.3?\fR
.sp
\fB::datefield::datefield\fR \fIwidgetpath\fR ?\fIoptions\fR?
.sp
\fI-format\fR
.sp
.BE
.SH DESCRIPTION
The \fBdatefield\fR package provides the datefield widget which
is an enhanced text entry widget for the purpose of date entry\&. There
are three valid formats for the dates which can be entered:
.IP [1]
English form MM/DD/YYYY using \fI-format "%m/%d/%Y"\fR (default)
.IP [2]
German form DD\&.MM\&.YYYY using \fI-format "%d\&.%m\&.%Y"\fR
.IP [3]
ISO form YYYY-MM-DD using \fI-format "%Y-%m-%d"\fR
.PP
.PP
The datefield widget is, in fact, just an entry widget with
specialized bindings\&. This means all the command and options for an
entry widget apply equally here\&.
.SH COMMANDS
.TP
\fB::datefield::datefield\fR \fIwidgetpath\fR ?\fIoptions\fR?
Creates and configures a date field widget\&.
.PP
.SH OPTIONS
.TP
\fI-format\fR
One of "%m/%d/%Y" (English, default if option left), "%d\&.%m\&.%Y" (German),
or "%Y-%m-%d" (ISO)\&.
.PP
.PP
See the \fBentry\fR manual entry for details on all remaining/available
options\&.
.SH EXAMPLE
.CS


 package require datefield

 wm title \&. "Datefield example"
 proc DayOfWeek {args} {
     set now [clock scan $::myDate]
     set ::myDate2 [clock format $now -format %A]
 }
 trace variable myDate w DayOfWeek

 ::datefield::datefield \&.df -textvariable myDate -format "%m/%d/%Y"
 label \&.l1 -text "Enter a date:"   -anchor e
 label \&.l2 -text "That date is a:" -anchor e
 label \&.l3 -textvariable myDate2 -relief sunken -width 12

 grid \&.l1 \&.df -sticky ew
 grid \&.l2 \&.l3 -sticky ew
 focus \&.df
................................................................................
.SH KEYWORDS
clock, date, dateentry, entry, widget
.SH CATEGORY
Widget
.SH COPYRIGHT
.nf
Copyright (c) Keith Vetter <keith@ebook\&.gemstar\&.com>
Copyright (c) Thomas Wunderlich <tcl\&.tk@blindenfreizeiten\&.de>

.fi

package require widgetPlus
::widgetPlus::EnableBWidget
namespace import widgetPlus::*

entryPlus \&.cb\&.e -undo 1 -maxundo 0

.CE







.SH "SEE ALSO"
BWidget, ComboBox, Entry, entry, persistentSelection, spinbox, text, ttk::combobox, ttk::entry, ttk::spinbox

package require widgetPlus
::widgetPlus::EnableBWidget
namespace import widgetPlus::*

entryPlus \&.cb\&.e -undo 1 -maxundo 0

.CE
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems\&.
Please report such in the category \fIwidgetPlus\fR of the
\fITklib Trackers\fR [http://core\&.tcl\&.tk/tklib/reportlist]\&.
Please also report any ideas for enhancements you may have for either
package and/or documentation\&.
.SH "SEE ALSO"
BWidget, ComboBox, Entry, entry, persistentSelection, spinbox, text, ttk::combobox, ttk::entry, ttk::spinbox

	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<!-- Generated from file 'datefield.man' by tcllib/doctools with format 'html'
   -->
<!-- Copyright &amp;copy; Keith Vetter &amp;lt;keith@ebook.gemstar.com&amp;gt;
   -->
<!-- datefield.n
   -->
<body><hr> [
   <a href="../../../../../../../../home">Tklib Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<div class="doctools">
<h1 class="doctools_title">datefield(n) 0.2 tklib &quot;Tk datefield widget&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>datefield - Tk datefield widget</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
................................................................................
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tk</b></li>
<li>package require <b class="pkgname">datefield <span class="opt">?0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::datefield::datefield</b> <i class="arg">widgetpath</i> <span class="opt">?<i class="arg">options</i>?</span></a></li>

</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">datefield</b> package provides the datefield widget which
is an enhanced text entry widget for the purpose of date entry. Only
valid dates of the form MM/DD/YYYY can be entered.</p>





<p>The datefield widget is, in fact, just an entry widget with
specialized bindings. This means all the command and options for an
entry widget apply equally here.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::datefield::datefield</b> <i class="arg">widgetpath</i> <span class="opt">?<i class="arg">options</i>?</span></a></dt>
<dd><p>Creates and configures a date field widget.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">OPTIONS</a></h2>





<p>See the <b class="cmd"><a href="../../../../index.html#key32">entry</a></b> manual entry for details on all available options.</p>

</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EXAMPLE</a></h2>
<pre class="doctools_example">
 package require datefield
 wm title . &quot;Datefield example&quot;
 proc DayOfWeek {args} {
     set now [clock scan $::myDate]
     set ::myDate2 [clock format $now -format %A]
 }
 trace variable myDate w DayOfWeek
 ::datefield::datefield .df -textvariable myDate
 label .l1 -text &quot;Enter a date:&quot;   -anchor e
 label .l2 -text &quot;That date is a:&quot; -anchor e
 label .l3 -textvariable myDate2 -relief sunken -width 12
 grid .l1 .df -sticky ew
 grid .l2 .l3 -sticky ew
 focus .df
</pre>
................................................................................
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#key31">clock</a>, <a href="../../../../index.html#key33">date</a>, <a href="../../../../index.html#key6">dateentry</a>, <a href="../../../../index.html#key32">entry</a>, <a href="../../../../index.html#key11">widget</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Widget</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright &copy; Keith Vetter &lt;keith@ebook.gemstar.com&gt;</p>

</div>
</div></body></html>

	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<!-- Generated from file 'datefield.man' by tcllib/doctools with format 'html'
   -->
<!-- Copyright &amp;copy; Keith Vetter &amp;lt;keith@ebook.gemstar.com&amp;gt;   -- Copyright &amp;copy; Thomas Wunderlich &amp;lt;tcl.tk@blindenfreizeiten.de&amp;gt;
   -->
<!-- datefield.n
   -->
<body><hr> [
   <a href="../../../../../../../../home">Tklib Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<div class="doctools">
<h1 class="doctools_title">datefield(n) 0.3 tklib &quot;Tk datefield widget&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>datefield - Tk datefield widget</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
................................................................................
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tk</b></li>
<li>package require <b class="pkgname">datefield <span class="opt">?0.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::datefield::datefield</b> <i class="arg">widgetpath</i> <span class="opt">?<i class="arg">options</i>?</span></a></li>
<li><a href="#2"><i class="arg">-format</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">datefield</b> package provides the datefield widget which
is an enhanced text entry widget for the purpose of date entry. There
are three valid formats for the dates which can be entered:</p>
<ol class="doctools_enumerated">
<li><p>English form MM/DD/YYYY using <i class="arg">-format &quot;%m/%d/%Y&quot;</i> (default)</p></li>
<li><p>German form DD.MM.YYYY using <i class="arg">-format &quot;%d.%m.%Y&quot;</i></p></li>
<li><p>ISO form YYYY-MM-DD using <i class="arg">-format &quot;%Y-%m-%d&quot;</i></p></li>
</ol>
<p>The datefield widget is, in fact, just an entry widget with
specialized bindings. This means all the command and options for an
entry widget apply equally here.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::datefield::datefield</b> <i class="arg">widgetpath</i> <span class="opt">?<i class="arg">options</i>?</span></a></dt>
<dd><p>Creates and configures a date field widget.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">OPTIONS</a></h2>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">-format</i></a></dt>
<dd><p>One of &quot;%m/%d/%Y&quot; (English, default if option left), &quot;%d.%m.%Y&quot; (German),
or &quot;%Y-%m-%d&quot; (ISO).</p></dd>
</dl>
<p>See the <b class="cmd"><a href="../../../../index.html#key32">entry</a></b> manual entry for details on all remaining/available
options.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EXAMPLE</a></h2>
<pre class="doctools_example">
 package require datefield
 wm title . &quot;Datefield example&quot;
 proc DayOfWeek {args} {
     set now [clock scan $::myDate]
     set ::myDate2 [clock format $now -format %A]
 }
 trace variable myDate w DayOfWeek
 ::datefield::datefield .df -textvariable myDate -format &quot;%m/%d/%Y&quot;
 label .l1 -text &quot;Enter a date:&quot;   -anchor e
 label .l2 -text &quot;That date is a:&quot; -anchor e
 label .l3 -textvariable myDate2 -relief sunken -width 12
 grid .l1 .df -sticky ew
 grid .l2 .l3 -sticky ew
 focus .df
</pre>
................................................................................
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#key31">clock</a>, <a href="../../../../index.html#key33">date</a>, <a href="../../../../index.html#key6">dateentry</a>, <a href="../../../../index.html#key32">entry</a>, <a href="../../../../index.html#key11">widget</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Widget</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright &copy; Keith Vetter &lt;keith@ebook.gemstar.com&gt;<br>
Copyright &copy; Thomas Wunderlich &lt;tcl.tk@blindenfreizeiten.de&gt;</p>
</div>
</div></body></html>

<!DOCTYPE html>
<html>
<head>
  <title>The Multi-Entry Widget Package Mentry 3.10</title>

  <meta name="Author" content="Csaba Nemethi">
  <meta name="Keywords" content="mentry, widget, entry, label">
</head>

<body>
  <div align="center">
    <h1>The Multi-Entry Widget Package Mentry 3.10</h1>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:csaba.nemethi@t-online.de">csaba.nemethi@t-online.de</a>
    </address>
  </div>

  <hr>

  <h2>Contents</h2>

  <p><a href="mentry.html">Mentry Programmer's Guide</a></p>

  <p><a href="mentryWidget.html">The <code>mentry::mentry</code>
  Command</a></p>

  <p><a href="mentryDateTime.html">Multi-Entry Widgets for Date and
  Time</a></p>

  <p><a href="mentryFixedPoint.html">Multi-Entry Widgets for Real Numbers in
  Fixed-Point Format</a></p>

  <p><a href="mentryIPAddr.html">Multi-Entry Widgets for IP Addresses</a></p>

  <p><a href="mentryIPv6Addr.html">Multi-Entry Widgets for IPv6
  Addresses</a></p>

  <p><a href="mentryThemes.html">Commands Related to Tile Themes</a></p>

  <p><a href="wcbRef.html">Wcb Command Reference</a></p>
</body>
</html>

<!DOCTYPE html>
<html>
<head>
  <title>Mentry Programmer's Guide</title>

  <meta name="Author" content="Csaba Nemethi">
  <meta name="Keywords" content="mentry, widget, entry, label">

  <link rel="stylesheet" type="text/css" href="stylesheet.css">
</head>

<body>
  <div align="center">
    <h1>Mentry Programmer's Guide</h1>

    <h2>For Mentry Version 3.10</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:csaba.nemethi@t-online.de">csaba.nemethi@t-online.de</a>
    </address>
  </div>

  <hr>

  <h2 id="contents">Contents</h2>

  <h4><a href="#overview">Overview</a></h4>

  <ul>
    <li><a href="#ov_what">What Is Mentry?</a></li>

    <li><a href="#ov_get">How to Get It?</a></li>

    <li><a href="#ov_install">How to Install It?</a></li>

    <li><a href="#ov_use">How to Use It?</a></li>

    <li><a href="#ov_tile">More on Mentry_tile</a></li>
  </ul>

  <h4><a href="#examples">Examples</a></h4>

  <ul>
    <li><a href="#ex_phoneNumber">A mentry Widget for Phone Numbers</a></li>

    <li><a href="#ex_ethernetAddr">A mentry Widget for Ethernet
    Addresses</a></li>

    <li><a href="#ex_dateTime">Using mentry Widgets for Date and Time</a></li>

    <li><a href="#ex_tile">Tile-Based Demo Scripts</a></li>
  </ul>

  <div align="center">
    <p><a href="index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="overview">Overview</h2>

  <h3 id="ov_what">What Is Mentry?</h3>

  <p>Mentry is a library package for Tcl/Tk versions 8.0 or higher, written in
  pure Tcl/Tk code.&nbsp; It contains:</p>

  <ul>
    <li>the implementation of the <a href="mentryWidget.html">multi-entry
    mega-widget <b>mentry</b></a>, including a general utility module for
    mega-widgets;</li>

    <li>procedures that facilitate the use of multi-entry widgets for
    displaying and editing <a href="mentryDateTime.html">date and time</a> in a
    great variety of formats, <a href="mentryFixedPoint.html">real numbers in
    fixed-point format</a>, as well as <a href="mentryIPAddr.html">IP(v4)
    addresses</a> and <a href="mentryIPv6Addr.html">IPv6 addresses</a>;</li>

    <li>two richly commented demo scripts containing the typical steps needed
    to create and handle a mentry widget for a particular purpose;</li>

    <li>two demo scripts that show how to use the date- and time-related
    procedures;</li>

    <li>tile-based counterparts of the above-mentioned demo scripts;</li>

    <li>this tutorial;</li>

    <li>reference pages in HTML format.</li>
  </ul>

  <p>A multi-entry widget consists of any number of entry widgets separated by
  labels, all embedded in a frame.&nbsp; Appropriately chosen configuration
  options make this conglomerate look like one single entry containing
  preinserted text pieces having invariant positions within the widget.&nbsp;
  The initial width of an entry child also determines the maximal number of
  characters that can be inserted into it; when reaching this limit in an entry
  having the input focus, the latter is set automatically to the next enabled
  entry child.&nbsp; The same action is triggered by typing a character
  contained in the label following the current entry, if the latter is
  non-empty.</p>

  <p>Within a mentry widget, the <code>Left</code>, <code>Right</code>,
  <code>Home</code>, <code>End</code>, and <code>BackSpace</code> keys work
  across entry boundaries, while <code>Control-Left</code> and
  <code>Control-Right</code> play the same role as <code>Tab</code> and
  <code>Shift-Tab</code> in the case of ordinary entries.</p>

  <p>Some of the above features are implemented with the aid of the widget
  callback package Wcb, written in pure Tcl/Tk code as well.&nbsp; <b>The
  Mentry package requires version 3.1 or higher of Wcb</b>, whose download
  location is</p>

  <blockquote>
    <address>
      <a href="http://www.nemethi.de">http://www.nemethi.de</a>
    </address>
  </blockquote>

  <p id="ov_example">It is very easy to create a multi-entry widget.&nbsp; For
  example, the command</p>

  <blockquote>
    <pre>
mentry::mentry .me -body {3 - 3 - 4}
</pre>
  </blockquote>

  <p>will create a mentry widget consisting of two entries of width 3 and one
  of width 4, separated by <code>"-"</code> characters.&nbsp; With the
  command</p>

  <blockquote>
    <pre>
foreach w [.me entries] {
    wcb::cbappend $w before insert wcb::checkStrForNum
}
</pre>
  </blockquote>

  <p>you can make sure that the three entries will only accept numeric input,
  thus providing a comfortable and safe user interface for editing 10-digit
  phone numbers.</p>

  <h3 id="ov_get">How to Get It?</h3>

  <p>Mentry is available for free download from the same URL as Wcb.&nbsp; The
  distribution file is <code>mentry3.10.tar.gz</code> for UNIX and
  <code>mentry3_10.zip</code> for Windows.&nbsp; 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.</p>

  <p>Mentry is also included in tklib, which has the address</p>

  <blockquote>
    <address>
      <a href="http://core.tcl.tk/tklib">http://core.tcl.tk/tklib</a>
    </address>
  </blockquote>

  <h3 id="ov_install">How to Install It?</h3>

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

  <p>To install Mentry <i>on UNIX</i>, <code>cd</code> to the desired directory
  and unpack the distribution file <code>mentry3.10.tar.gz</code>:</p>

  <blockquote>
    <pre>
gunzip -c mentry3.10.tar.gz | tar -xf -
</pre>
  </blockquote>

  <p>On most UNIX systems this can be replaced with</p>

  <blockquote>
    <pre>
tar -zxf mentry3.10.tar.gz
</pre>
  </blockquote>

  <p>Both commands will create a directory named <code>mentry3.10</code>, with
  the subdirectories <code>demos</code>, <code>doc</code>, and
  <code>scripts</code>.</p>

  <p><i>On Windows</i>, use WinZip or some other program capable of unpacking
  the distribution file <code>mentry3_10.zip</code> into the directory
  <code>mentry3.10</code>, with the subdirectories <code>demos</code>,
  <code>doc</code>, and <code>scripts</code>.</p>

  <p>The file <code>mentryThemes.tcl</code> in the <code>scripts</code>
  directory is only needed for applications using the package Mentry_tile (see
  next section).</p>

  <p>Notice that in tklib the Mentry <code>demos</code> directory is replaced
  with the subdirectory <code>mentry</code> of the <code>examples</code>
  directory.&nbsp; Please take this into account when reading the <a href=
  "#examples">examples</a> below.</p>

  <h3 id="ov_use">How to Use It?</h3>

  <p>The Mentry distribution provides two packages, called <b>Mentry</b> and
  <b>Mentry_tile</b>.&nbsp; The main difference between the two is that
  Mentry_tile enables the tile-based, theme-specific appearance of mentry
  widgets; this package requires Tcl/Tk 8.4 or higher and tile 0.6 or
  higher.&nbsp; It is not possible to use both packages in one and the same
  application, because both are implemented in the same <code>mentry</code>
  namespace and provide identical commands.</p>

  <p>To be able to access the commands and variables defined in the package
  Mentry, your scripts must contain one of the lines</p>

  <blockquote>
    <pre>
package require mentry ?<i>version</i>?
package require Mentry ?<i>version</i>?
</pre>
  </blockquote>

  <p>You can use either one of the two statements above because the file
  <code>mentry.tcl</code> contains both lines</p>

  <blockquote>
    <pre>
package provide mentry ...
package provide Mentry ...
</pre>
  </blockquote>

  <p>Likewise, to be able to access the commands and variables defined in the
  package Mentry_tile, your scripts must contain one of the lines</p>

  <blockquote>
    <pre>
package require mentry_tile ?<i>version</i>?
package require Mentry_tile ?<i>version</i>?
</pre>
  </blockquote>

  <p>Again, you can use either one of the two statements above because the file
  <code>mentry_tile.tcl</code> contains both lines</p>

  <blockquote>
    <pre>
package provide mentry_tile ...
package provide Mentry_tile ...
</pre>
  </blockquote>

  <p>You are free to remove one of the above lines from <code>mentry.tcl</code>
  and <code>mentry_tile.tcl</code>, respectively, if you want to prevent the
  corresponding packages from making themselves known under two different names
  each.&nbsp; Of course, by doing so you restrict the argument of&nbsp;
  <code>package require</code>&nbsp; to a single name per package.</p>

  <p>Please note that <b>ActiveTcl versions 8.5 and later use a modified
  package mechanism, which only exports the all-lowercase names
  <code>mentry</code> and <code>mentry_tile</code></b>.&nbsp; For this reason,
  the <a href="#examples">examples</a> below use the statement&nbsp;
  <code>package require mentry</code>,&nbsp; and their tile-based counterparts
  invoke the command&nbsp; <code>package require mentry_tile</code>.</p>

  <p>Since the packages Mentry and Mentry_tile are implemented in the
  <code>mentry</code> namespace, you must either invoke the</p>

  <blockquote>
    <pre>
namespace import mentry::<i>pattern</i> ?mentry::<i>pattern ...</i>?
</pre>
  </blockquote>

  <p>command to import the <i>procedures</i> you need, or use qualified names
  like <code>mentry::mentry</code>.&nbsp; In the examples below we have chosen
  the latter approach.</p>

  <p>To access Mentry <i>variables</i>, you <i>must</i> use qualified
  names.&nbsp; There are only three Mentry variables (and one more when using
  Mentry_tile) that are designed to be accessed outside the namespace
  <code>mentry</code>:</p>

  <ul>
    <li>The variable <code>mentry::version</code> holds the current version
    number of the Mentry package.</li>

    <li>The variable <code>mentry::library</code> holds the location of the
    Mentry installation directory.</li>

    <li>The read-only variable <code>mentry::usingTile</code> has the value
    <code>0</code> in the package Mentry and the value <code>1</code> in
    Mentry_tile.</li>

    <li>In Mentry_tile the array <code>mentry::themeDefaults</code> holds the
    theme-specific default values of a series of Mentry configuration
    options.</li>
  </ul>

  <h3 id="ov_tile">More on Mentry_tile</h3>

  <p>As mentioned above, a mentry widget consists of entry and label widgets,
  embedded in a frame.&nbsp; While in the Mentry package all of these
  components are Tk widgets, the Mentry_tile package uses both Tk frame, tile
  entry, and Tk label widgets.&nbsp; Due to several incompatibilities between
  Tk and tile, it is currently not possible to replace all Tk widgets making up
  a mentry with their tile counterparts.&nbsp; Actually, the entry components
  of a tile-based mentry are embedded into Tk frame widgets, which in turn,
  together with the labels, are packed into a specially constructed tile entry
  rather than a frame.&nbsp; This somewhat complicated layout is needed because
  in several themes it is not possible to draw flat, borderless tile enty
  widgets.</p>

  <p>From the above it follows that <b>the package Mentry_tile will only work
  as expected if the Tk <code>frame</code> and <code>label</code> commands
  haven't been overridden by using&nbsp; <code>namespace import -force
  ttk::*</code>&nbsp; at global scope</b>.&nbsp; While earlier tile releases
  suggested using this command at global scope for the really adventurous, in
  newer tile versions this is considered a Really Bad Idea, causing many things
  to break.&nbsp; Instead, <b>you should explicitly invoke
  <code>ttk::frame</code>, <code>ttk::label</code>, etc. whenever you want to
  use a tile widget</b>.</p>

  <p>Another restriction to be taken into account (as of tile version 0.8) is
  due to the fact that the&nbsp; <code>(ttk::)style theme use</code>&nbsp;
  command can only be used to set the current theme, but not to retrieve
  it.&nbsp; For this reason, the package Mentry_tile makes use of the variable
  <code>ttk::currentTheme</code> or <code>tile::currentTheme</code> (depending
  on the tile version), which is set by the <code>ttk::setTheme</code> or
  <code>tile::setTheme</code> procedure.&nbsp; From this it follows that <b>the
  tile-based mentry widgets will only have the expected appearance if the
  platform-specific default theme is either left unchanged or replaced with
  another theme by invoking the procedure <code>ttk::setTheme</code> or
  <code>tile::setTheme</code>, depending on the current tile version</b>.&nbsp;
  (See also the <code><a href=
  "mentryThemes.html#setTheme">mentry::setTheme</a></code> command.)</p>

  <p>After these cautions concerning the use of tile, the rest of this section
  describes the differences between the packages Mentry and Mentry_tile.</p>

  <p>The Mentry_tile package checks whether the required Tk and tile versions
  are present, by executing the commands</p>

  <blockquote>
    <pre>
package require Tk 8.4
if {$::tk_version &lt; 8.5 || [regexp {^8\.5a[1-5]$} $::tk_patchLevel]} {
    package require tile 0.6
}
</pre>
  </blockquote>

  <p>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.</p>

  <p>Apart from this and the <code>_tile</code> suffix in the&nbsp;
  <code>package require</code>&nbsp; command, the only difference (from the
  programmer's point of view) between the packages Mentry and Mentry_tile is
  related to the supported configuration options:&nbsp; The following Tk
  (entry) widget options, present in the Mentry package, are not supported by
  Mentry_tile, because they are not available for tile (entry) widgets:
  <code>-borderwidth</code>, <code>-disabledbackground</code>,
  <code>-disabledforeground</code>, <code>-highlightbackground</code>,
  <code>-highlightcolor</code>, <code>-highlightthickness</code>,
  <code>-insertbackground</code>, <code>-insertborderwidth</code>,
  <code>-insertofftime</code>, <code>-insertontime</code>,
  <code>-insertwidth</code>, <code>-readonlybackground</code>,
  <code>-relief</code>, <code>-selectbackground</code>,
  <code>-selectborderwidth</code>, and <code>-selectforeground</code>.</p>

  <p>Notice that the <code>-background</code> option doesn't work as expected
  if the current theme is <code>plastik</code>, <code>tileqt</code>,
  <code>vista</code>, or <code>xpnative</code>, because these themes silently
  ignore any attempt to change the background color of a tile entry widget.</p>

  <p>Finally, take into account that, when using the <code>tileqt</code> theme,
  the version number of the <code>tile::theme::tileqt</code> package must be
  0.4 or higher, and <code>tileqt</code> itself won't work with tile versions
  earlier than 0.7.</p>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="examples">Examples</h2>

  <h3 id="ex_phoneNumber">A mentry Widget for Phone Numbers</h3>

  <p>Let's resume the <a href="#ov_example">example</a> mentioned in the
  Overview in a bit more systematical manner.&nbsp; First, we will write a
  procedure for creating a mentry widget that allows to display and edit
  10-digit phone numbers and accepts any configuration options supported by the
  <code><a href="mentryWidget.html">mentry::mentry</a></code> command:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# phoneNumberMentry
#
# Creates a new mentry widget win that allows to display and edit 10-digit
# phone numbers.  Sets the type attribute of the widget to PhoneNumber and
# returns the name of the newly created widget.
#------------------------------------------------------------------------------</span>
proc phoneNumberMentry {win args} {
    <span class="cmt">#
    # Create a mentry widget consisting of two entries of width 3 and one of
    # width 4, separated by "-" characters, and set its type to PhoneNumber
    #</span>
    eval [list mentry::mentry $win] $args
    $win configure -body {3 - 3 - 4}
    $win attrib type PhoneNumber

    <span class="cmt">#
    # Allow only decimal digits in all entry children; use
    # wcb::cbappend (or wcb::cbprepend) instead of wcb::callback
    # in order to keep the wcb::checkEntryLen callback,
    # registered by mentry::mentry for all entry children
    #</span>
    for {set n 0} {$n &lt; 3} {incr n} {
        wcb::cbappend [$win entrypath $n] before insert wcb::checkStrForNum
        $win adjustentry $n "0123456789"
    }

    return $win
}
</pre>
  </blockquote>

  <p>The first argument <code>win</code> is the name of the widget, and the
  keyword <code>args</code> represents a list of configuration options and
  their values, just like in the case of the standard Tk widgets.&nbsp; The
  value&nbsp; <code>{3 - 3 - 4}</code>&nbsp; of the <code><a href=
  "mentryWidget.html#body">-body</a></code> option specifies that the mentry
  should consist of two entries of width 3 and one of width 4, separated by
  labels displaying the <code>"-"</code> character.</p>

  <p>Each mentry widget may have any number of private <b>attributes</b>, which
  can be set and retrieved with the aid of the <code><a href=
  "mentryWidget.html#attrib">attrib</a></code> subcommand of the Tcl procedure
  corresponding to the widget.&nbsp; We use this subcommand to define the
  <code>type</code> attribute of the newly created widget and set it to the
  value <code>"PhoneNumber"</code>.&nbsp; Although this is not strictly
  necessary, it will enable us to distinguish a phone number mentry from other
  multi-entry widgets.</p>

  <p>The <code>mentry::mentry</code> command registers the <code><a href=
  "wcbRef.html#entrycb">wcb::checkEntryLen</a></code> callback with each entry
  child of the mentry widget to restrict the number of characters that can be
  inserted into it to the initial width specified in the <code>-body</code>
  option.&nbsp; Besides this constraint, we want our entries to accept only
  decimal digits, therefore we use the <code><a href=
  "wcbRef.html#cbappend">wcb::cbappend</a></code> command to <i>add</i> the
  procedure <code><a href="wcbRef.html#entrycb">wcb::checkStrForNum</a></code>
  to the callback list of each entry child.&nbsp; By invoking <code><a href=
  "wcbRef.html#callback">wcb::callback</a></code> instead of
  <code>wcb::cbappend</code> (or <code><a href=
  "wcbRef.html#cbprepend">wcb::cbprepend</a></code>), we would <i>replace</i>
  the callback list with the one consisting of the single element
  <code>wcb::checkStrForNum</code>.</p>

  <p>Now we know that each entry child of the mentry widget will only accept a
  limited number of decimal digits.&nbsp; But are the widths of the entry
  children large enough to hold the maximal number of 3 or 4 decimal digits,
  respectively?&nbsp; In the case of a fixed-width font the answer is
  definitely "yes", and the same holds true for most proportionally-spaced
  fonts.&nbsp; There are, however, fonts in which not all decimal digits have
  the same width.&nbsp; For this reason, we invoke the <code><a href=
  "mentryWidget.html#adjustentry">adjustentry</a></code> subcommand for each
  entry child, passing to it as last argument a string consisting of the
  allowed characters, which in this example are the decimal digits.&nbsp; This
  subcommand will increase the entry widget's width if needed, to make it just
  large enough for texts of the child-specific maximal length, consisting of
  characters specified by that string.</p>

  <p>Our second procedure outputs a phone number to a mentry widget having a
  <code>type</code> attribute value of <code>"PhoneNumber"</code>:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# putPhoneNumber
#
# Outputs the phone number num to the mentry widget win of type PhoneNumber.
# The phone number must be a string of length 10, consisting of decimal digits.
#------------------------------------------------------------------------------</span>
proc putPhoneNumber {num win} {
    <span class="cmt">#
    # Check the syntax of num
    #</span>
    if {[string length $num] != 10 || ![regexp {^[0-9]*$} $num]} {
        return -code error "expected 10 decimal digits but got \"$num\""
    } 

    <span class="cmt">#
    # Check the widget and display the properly formatted phone number
    #</span>
    checkIfPhoneNumberMentry $win
    $win put 0 [string range $num 0 2] [string range $num 3 5] \
               [string range $num 6 9]
}
</pre>
  </blockquote>

  <p>We use the <code><a href="mentryWidget.html#put">put</a></code> subcommand
  of the Tcl procedure corresponding to the mentry widget to display the three
  substrings of the given phone number in the corresponding entries, starting
  with the entry child whose index is specified as the first argument following
  the word <code>put</code>.</p>

  <p>Next, we need a procedure that returns the phone number contained in a
  mentry widget having a <code>type</code> attribute value of
  <code>"PhoneNumber"</code>:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# getPhoneNumber
#
# Returns the phone number contained in the mentry widget win of type
# PhoneNumber.
#------------------------------------------------------------------------------</span>
proc getPhoneNumber win {
    <span class="cmt">#
    # Check the widget
    #</span>
    checkIfPhoneNumberMentry $win

    <span class="cmt">#
    # Generate an error if any entry child is empty or incomplete
    #</span>
    for {set n 0} {$n &lt; 3} {incr n} {
        if {[$win isempty $n]} {
            focus [$win entrypath $n]
            return -code error EMPTY
        }
        if {![$win isfull $n]} {
            focus [$win entrypath $n]
            return -code error INCOMPL
        }
    }

    <span class="cmt">#
    # Return the phone number built from the
    # values contained in the entry children
    #</span>
    $win getarray strs
    return $strs(0)$strs(1)$strs(2)
}
</pre>
  </blockquote>

  <p>The procedure runs over the indices of the entry children of the given
  mentry widget and invokes the <code><a href=
  "mentryWidget.html#isempty">isempty</a></code> and <code><a href=
  "mentryWidget.html#isfull">isfull</a></code> subcommands of the Tcl command
  corresponding to the given mentry widget.&nbsp; If one of the entries is
  found to be empty or incomplete, the procedure gets its path name by calling
  the <code><a href="mentryWidget.html#entrypath">entrypath</a></code>
  subcommand, sets the focus to that entry, raises an error, and returns the
  value <code>"EMPTY"</code> or <code>"INCOMPL"</code>, respectively.&nbsp; The
  application invoking this procedure should then display an appropriate error
  message corresponding to the return value.</p>

  <p>Notice that the number <code>3</code> in the <code>for</code> loop above
  is nothing else than&nbsp; <code>[$win <a href=
  "mentryWidget.html#entrycount">entrycount</a>]</code>.&nbsp; Also, it would
  be sufficient to check whether all entry children are full, because an empty
  entry is at the same time incomplete.&nbsp; The preliminary check whether an
  entry is empty is just made for the user's convenience.</p>

  <p>To build the phone number from the values contained in the entry children,
  we use a temporary array variable and invoke the <code><a href=
  "mentryWidget.html#getarray">getarray</a></code> subcommand, which copies the
  contents of the entries to the corresponding array elements.</p>

  <p>The last two procedures presented above contain an invocation of the
  command <code>checkIfPhoneNumberMentry</code>, which is implemented as
  folows:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# checkIfPhoneNumberMentry
#
# Generates an error if win is not a mentry widget of type PhoneNumber.
#------------------------------------------------------------------------------</span>
proc checkIfPhoneNumberMentry win {
    if {![winfo exists $win]} {
        return -code error "bad window path name \"$win\""
    }

    if {[string compare [winfo class $win] "Mentry"] != 0 ||
        [string compare [$win attrib type] "PhoneNumber"] != 0} {
        return -code error \
               "window \"$win\" is not a mentry widget for phone numbers"
    }
}
</pre>
  </blockquote>

  <p>This procedure retrieves the value of the <code>type</code> attribute of
  its argument to check whether the latter denotes a mentry widget for phone
  numbers (remember that this attribute was set to the value
  <code>"PhoneNumber"</code> in the procedure
  <code>phoneNumberMentry</code>).</p>

  <p>The four procedures discussed above are implemented in the file
  <code>phonenumber.tcl</code>, contained in the <code>demos</code>
  directory.&nbsp; This script also puts them together to build a small
  application displaying the following figure:</p>

  <blockquote>
    <img src="phonenumber.png" alt="Phone Number" width="269" height="228">
  </blockquote>

  <p>Here is the relevant code fragment:</p>

  <blockquote>
    <pre>
package require mentry

set title "Phone Number"
wm title . $title

<span class="cmt">#
# Add some entries to the Tk option database
#</span>
source [file join [file dirname [info script]] option.tcl]

. . .

<span class="cmt">#
# Frame .f with a mentry displaying a phone number
#</span>
frame .f
label .f.l -text "A mentry widget for phone numbers:"
phoneNumberMentry .f.me -background white
pack .f.l .f.me

<span class="cmt">#
# Message strings corresponding to the values
# returned by getPhoneNumber on failure
#</span>
array set msgs {
    EMPTY       "Field value missing"
    INCOMPL     "Incomplete field value"
}

<span class="cmt">#
# Button .get invoking the procedure getPhoneNumber
#</span>
button .get -text "Get from mentry" -command {
    if {[catch {
        set num ""
        set num [getPhoneNumber .f.me]
    } result] != 0} {
        bell
        tk_messageBox -icon error -message $msgs($result) \
                      -title $title -type ok
    }
}

<span class="cmt">#
# Label .num displaying the result of getPhoneNumber
#</span>
label .num -textvariable num -background white

. . .

putPhoneNumber 1234567890 .f.me
focus [.f.me entrypath 0]
</pre>
  </blockquote>

  <h3 id="ex_ethernetAddr">A mentry Widget for Ethernet Addresses</h3>

  <p>Ethernet addresses are usuallly written in the form
  <code>"XX:XX:XX:XX:XX:XX"</code>, where each <code>"X"</code> is a
  hexadecimal digit.&nbsp; The file <code>ethernetaddr.tcl</code> in the
  <code>demos</code> directory contains the steps needed to create and use a
  multi-entry widget for displaying and editing Ethernet addresses.&nbsp; It
  implements the procedures <code>ethernetAddrMentry</code>,
  <code>putEthernetAddr</code>, and <code>getEthernetAddr</code>; the last two
  invoke the helper procedure <code>checkIfEthernetAddrMentry</code>, while the
  first one is implemented as follows:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# ethernetAddrMentry
#   
# Creates a new mentry widget win that allows to display and edit Ethernet
# addresses.  Sets the type attribute of the widget to EthernetAddr and returns
# the name of the newly created widget.
#------------------------------------------------------------------------------</span>
proc ethernetAddrMentry {win args} {
    <span class="cmt">#
    # Create a mentry widget consisting of 6 entry children of
    # width 2, separated by colons, and set its type to EthernetAddr
    #</span>
    eval [list mentry::mentry $win] $args
    $win configure -body {2 : 2 : 2 : 2 : 2 : 2}
    $win attrib type EthernetAddr

    <span class="cmt">#
    # Install automatic uppercase conversion and allow only hexadecimal
    # digits in all entry children; use wcb::cbappend (or wcb::cbprepend)
    # instead of wcb::callback in order to keep the wcb::checkEntryLen
    # callback, registered by mentry::mentry for all entry children
    #</span>
    for {set n 0} {$n &lt; 6} {incr n} {
        wcb::cbappend [$win entrypath $n] before insert wcb::convStrToUpper \
                      {wcb::checkStrForRegExp {^[0-9A-F]*$}}
        $win adjustentry $n "0123456789ABCDEF"
    }
    
    return $win
}
</pre>
  </blockquote>

  <p>Notice again the invocation of the <code><a href=
  "mentryWidget.html#adjustentry">adjustentry</a></code> subcommand of the Tcl
  command associated with the mentry widget, for each of its entry
  children.&nbsp; This is necessary, because in the case of a
  proportionally-spaced font the characters <code>A</code> - <code>F</code>
  need more room than the digits <code>0</code> - <code>9</code> (and it is not
  even guaranteed that the latters have the same width).</p>

  <p>The procedure <code>putEthernetAddr</code> expects as its first argument a
  string of the form <code>"XX:XX:XX:XX:XX:XX"</code>, where each
  <code>"XX"</code> must be a hexadecimal string in the range <code>0</code> -
  <code>255</code>:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# putEthernetAddr
#
# Outputs the Ethernet address addr to the mentry widget win of type
# EthernetAddr.  The address must be a string of the form XX:XX:XX:XX:XX:XX,
# where each XX must be a hexadecimal string in the range 0 - 255.  Leading
# zeros are allowed (but not required), hence the components may have more (but
# also less) than two characters; the procedure displays them with exactly two
# digits.
#------------------------------------------------------------------------------</span>
proc putEthernetAddr {addr win} {
    set errorMsg "expected an Ethernet address but got \"$addr\""

    <span class="cmt">#
    # Check the syntax of addr
    #</span>
    set lst [split $addr :]
    if {[llength $lst] != 6} {
        return -code error $errorMsg
    }

    <span class="cmt">#
    # Try to convert the 6 components of addr to hexadecimal
    # strings and check whether they are in the range 0 - 255
    #</span>
    for {set n 0} {$n &lt; 6} {incr n} {
        set val 0x[lindex $lst $n]
        if {[catch {format "%02X" $val} str$n] != 0 || $val &lt; 0 || $val &gt; 255} {
            return -code error $errorMsg
        }
    }

    <span class="cmt">#
    # Check the widget and display the properly formatted Ethernet address
    #</span>
    checkIfEthernetAddrMentry $win
    $win put 0 $str0 $str1 $str2 $str3 $str4 $str5
}
</pre>
  </blockquote>

  <p>The procedure <code>getEthernetAddr</code> raises an error if any entry
  child of the given mentry widget is empty.&nbsp; It accepts also entry
  strings of length one, but in the return value all components will have
  exactly two digits:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# getEthernetAddr
#
# Returns the Ethernet address contained in the mentry widget win of type
# EthernetAddr.
#------------------------------------------------------------------------------</span>
proc getEthernetAddr win {
    <span class="cmt">#
    # Check the widget
    #</span>
    checkIfEthernetAddrMentry $win

    <span class="cmt">#
    # Generate an error if any entry child is empty
    #</span>
    for {set n 0} {$n &lt; 6} {incr n} {
        if {[$win isempty $n]} {
            focus [$win entrypath $n]
            return -code error EMPTY
        }
    }

    <span class="cmt">#
    # Return the properly formatted Ethernet address built
    # from the values contained in the entry children
    #</span>
    $win getarray strs
    return [format "%02X:%02X:%02X:%02X:%02X:%02X" \
            0x$strs(0) 0x$strs(1) 0x$strs(2) 0x$strs(3) 0x$strs(4) 0x$strs(5)]
}
</pre>
  </blockquote>

  <p>We will not show the rest of the code here, because it is very similar to
  the one presented in the preceding section.&nbsp; The mentry widget for
  Ethernet addresses looks like in the following figure:</p>

  <blockquote>
    <img src="ethernetaddr.png" alt="Ethernet Address" width="290"
    height="243">
  </blockquote>

  <h3 id="ex_dateTime">Using mentry Widgets for Date and Time</h3>

  <p>Multi-entry widgets can be used to display and edit date and time in a
  great variety of formats.&nbsp; The Mentry package contains ready-to-use
  commands for this purpose:</p>

  <ul>
    <li>The procedure <code><a href=
    "mentryDateTime.html#dateMentry">mentry::dateMentry</a></code> creates a
    new mentry widget for displaying and editing a date according to the format
    passed to the command as a three-character string consisting of the field
    descriptor characters <code>"d"</code>, <code>"m"</code>, and
    <code>"y"</code> or <code>"Y"</code>, known from the&nbsp; <code>clock
    format</code>&nbsp; command.&nbsp; Another argument expected by the
    procedure is the string (usually a single character) to be displayed in the
    labels separating the three components of the date.</li>

    <li class="tm">Similarly, the procedure <code><a href=
    "mentryDateTime.html#timeMentry">mentry::timeMentry</a></code> creates a
    new mentry widget for displaying and editing a time according to the format
    passed to the command as a two- or three-character string consisting of the
    following field descriptor characters of the&nbsp; <code>clock
    format</code>&nbsp; command: <code>"H"</code> or <code>"I"</code>, followed
    by <code>"M"</code>, and optionally the letter <code>"S"</code>.&nbsp; An
    <code>"H"</code> as first character specifies the time format
    <code>"%H:%M"</code> or <code>"%H:%M:%S"</code> (i.e., with the hour
    between <code>0</code> and <code>23</code>), while the letter
    <code>"I"</code> stands for&nbsp; <code>"%I:%M %p"</code>&nbsp; or&nbsp;
    <code>"%I:%M:%S %p"</code>&nbsp; (i.e., with AM/PM indicator).&nbsp; The
    procedure expects the separator string (which is usually the
    <code>":"</code> character) as another command-line argument.</li>

    <li class="tm">Finally, the procedure <code><a href=
    "mentryDateTime.html#dateTimeMentry">mentry::dateTimeentry</a></code>
    creates a new mentry widget for displaying and editing a date & time
    according to the format passed to the command as a 5- or 6-character
    string, with the first three characters consisting of the letters
    <code>"d"</code>, <code>"m"</code>, and <code>"y"</code> or
    <code>"Y"</code>, followed by two or three further field descriptor
    characters of the&nbsp; <code>clock format</code>&nbsp; command, which must
    be: <code>"H"</code> or <code>"I"</code>, then <code>"M"</code>, and
    optionally the letter <code>"S"</code>.&nbsp; The procedure expects two
    more arguments, specifying the separators to be used in the date and time
    parts of the mentry widget, respectively.</li>
  </ul>

  <p>Before describing the other date- and time-related commands provided by
  the Mentry package, let's see how the first two of the above are invoked in
  the file <code>datetime1.tcl</code>, located in the <code>demos</code>
  directory:</p>

  <blockquote>
    <pre>
package require mentry

set title "Date & Time"
wm title . $title 

<span class="cmt">#
# Add some entries to the Tk option database
#</span>
source [file join [file dirname [info script]] option.tcl]
    
<span class="cmt">#   
# Date and time formats supported by this demo
# script and the corresponding field separators
#</span>
array set dateFmts {0 mdy  1 dmy  2 Ymd}
array set dateSeps {0 /    1 .    2 -  }
array set timeFmts {0 IMS  1 HMS}
array set timeSeps {0 :    1 :  }

<span class="cmt">#
# Choose the date & time formats; don't use the %p field descriptor
# for displaying the AM/PM indicator, because it doesn't work on
# UNIX if Tcl/Tk 8.4 or higher is used in a non-default locale
#</span>
wm withdraw .
set clockVal [clock seconds]
if {[clock format $clockVal -format "%H"] &lt; 12} {
    set meridian AM
} else {
    set meridian PM
}
set dateIdx [tk_dialog .choice $title "Please choose a date format" {} -1 \
                       [clock format $clockVal -format "%m/%d/%y"] \ 
                       [clock format $clockVal -format "%d.%m.%y"] \ 
                       [clock format $clockVal -format "%Y-%m-%d"]]
set timeIdx [tk_dialog .choice $title "Please choose a time format" {} -1 \
                       [clock format $clockVal -format "%I:%M:%S $meridian"] \
                       [clock format $clockVal -format "%H:%M:%S"]]
wm deiconify .

<span class="cmt">#   
# Frame .f with mentries displaying the date & time
#</span>   
frame .f
label .f.lDate -text "Date: "
mentry::dateMentry .f.date $dateFmts($dateIdx) $dateSeps($dateIdx) \ 
                   -justify center -background white
frame .f.gap -width 10
label .f.lTime -text "Time: "
mentry::timeMentry .f.time $timeFmts($timeIdx) $timeSeps($timeIdx) \
                   -justify center -background white
pack .f.lDate .f.date .f.gap .f.lTime .f.time -side left
</pre>
  </blockquote>

  <p>Before displaying the main window, the script lets the user choose one out
  of three date and one out of two time formats.&nbsp; The corresponding
  command-line arguments passed to <code>mentry::dateMentry</code> and
  <code>mentry::timeMentry</code> are taken from the arrays
  <code>dateFmts</code>, <code>dateSeps</code>, <code>timeFmts</code>, and
  <code>timeSeps</code>.</p>

  <p>The following figure corresponds to the choices&nbsp; <code>dateIdx =
  2</code>&nbsp; and&nbsp; <code>timeIdx = 1</code>:</p>

  <blockquote>
    <img src="datetime1.png" alt="Date & Time" width="279" height="209">
  </blockquote>

  <p>The demo script <code>datetime2.tcl</code> displays both the date and time
  in the same mentry widget, with the aid of the third command described
  above:</p>

  <blockquote>
    <pre>
<span class="cmt">#
# Frame .f with a mentry displaying the date & time
#</span>
frame .f
label .f.l -text "Date & time: "
mentry::dateTimeMentry .f.me $dateFmts($dateIdx)$timeFmts($timeIdx) \
                       $dateSeps($dateIdx) $timeSeps($timeIdx) \
                       -justify center -background white
pack .f.l .f.me
</pre>
  </blockquote>

  <blockquote>
    <img src="datetime2.png" alt="Date & Time" width="272" height="209">
  </blockquote>

  <p>The Mentry package exports two further commands for date, time, and date &
  time mentries:</p>

  <ul>
    <li>The procedure <code><a href=
    "mentryDateTime.html#putClockVal">mentry::putClockVal</a></code> outputs
    the date, time, or date & time corresponding to an integer clock value
    specified as its first argument to a date, time, or date & time mentry
    widget, passed to it as the second parameter.&nbsp; Like the
    &nbsp;<code>clock format</code>&nbsp; command, the procedure accepts the
    optional argument pair&nbsp; <code>-gmt <i>boolean</i></code>.</li>

    <li class="tm">The procedure <code><a href=
    "mentryDateTime.html#getClockVal">mentry::getClockVal</a></code> returns
    the clock value corresponding to the date, time, or date & time contained
    in the date, time, or date & time mentry specified as its first
    argument.&nbsp; Like the &nbsp;<code>clock scan</code>&nbsp; command, the
    procedure accepts the optional argument pairs&nbsp; <code>-base
    <i>clockValue</i></code>&nbsp; and&nbsp; <code>-gmt
    <i>boolean</i></code>.&nbsp; On failure, the procedure sets the focus to
    the first erronous entry child, generates an error, and returns one of the
    values contained in the following code fragment taken from the scripts
    <code>datetime1.tcl</code> and <code>datetime2.tcl</code>:

      <blockquote>
        <pre>
<span class="cmt">#
# Message strings corresponding to the values
# returned by mentry::getClockVal on failure
#</span>
array set msgs {
    EMPTY       "Field value missing"
    BAD         "Invalid field value"
    BAD_DATE    "Invalid date"
    BAD_YEAR    "Unsupported year"
}
</pre>
      </blockquote>

      <p>The string <code>"EMPTY"</code> is returned if any entry child (except
      the one containing the seconds) was found to be empty.&nbsp; The value
      <code>"BAD"</code> means a day, month, or hour value of <code>0</code>
      (the hour must not be <code>0</code> if the AM/PM indicator is
      present).&nbsp; The string <code>"BAD_DATE"</code> is returned when the
      &lt;year, month, day&gt; triple is invalid (note that the procedure is
      aware of leap years).&nbsp; Finally, even if this triple is valid, the
      conversion (made with the aid of the&nbsp; <code>clock scan</code>&nbsp;
      command) can fail because of an unsupported year value (e.g., between
      <code>38</code> and <code>70</code>); in this case the string
      <code>"BAD_YEAR"</code> is returned.</p>
    </li>
  </ul>

  <p>The demo script <code>datetime1.tcl</code> invokes the last two commands
  as follows:</p>

  <blockquote>
    <pre>
<span class="cmt">#
# Button .get invoking the procedure mentry::getClockVal
#</span>
button .get -text "Get from mentries" -command {
    if {[catch {
        set dateTime ""
        set base [mentry::getClockVal .f.date]
        set clockVal [mentry::getClockVal .f.time -base $base]
        set dateTime [clock format $clockVal -format "%c"]
    } result] != 0} {
        bell
        tk_messageBox -icon error -message $msgs($result) \
                      -title $title -type ok
    }
}

<span class="cmt">#
# Label .dateTime displaying the result of mentry::getClockVal
#</span>
label .dateTime -textvariable dateTime -background white

. . .

set clockVal [clock seconds]
mentry::putClockVal $clockVal .f.date
mentry::putClockVal $clockVal .f.time
focus [.f.date entrypath 0]
</pre>
  </blockquote>

  <p>To obtain the clock value from the mentry widgets <code>.f.date</code> and
  <code>.f.time</code>, we first pass the name of the date mentry to the
  command <code>mentry::getClockVal</code> and then use the result as the value
  of the <code>-base</code> option when passing the name of the time mentry to
  the same procedure.</p>

  <p>The demo script <code>datetime2.tcl</code> is simpler:</p>

  <blockquote>
    <pre>
<span class="cmt">#
# Button .get invoking the procedure mentry::getClockVal
#</span>
button .get -text "Get from mentry" -command {
    if {[catch {
        set dateTime ""
        set clockVal [mentry::getClockVal .f.me]
        set dateTime [clock format $clockVal -format "%c"]
    } result] != 0} {
        bell
        tk_messageBox -icon error -message $msgs($result) \
                      -title $title -type ok
    }
}

<span class="cmt">#
# Label .dateTime displaying the result of mentry::getClockVal
#</span>
label .dateTime -textvariable dateTime -background white

. . .

set clockVal [clock seconds]
mentry::putClockVal $clockVal .f.me
focus [.f.me entrypath 0]
</pre>
  </blockquote>

  <h3 id="ex_tile">Tile-Based Demo Scripts</h3>

  <p>The Mentry distribution contains also tile-based counterparts of the demo
  scripts discussed above.&nbsp; As described in the <a href="#ov_tile">More on
  Mentry_tile</a> section of this tutorial, it is quite easy to port an
  application using the Mentry package to one based on Mentry_tile.&nbsp; For
  example, let's see how to transform the demo script
  <code>phonenumber.tcl</code> into a tile-based one, called
  <code>phonenumber_tile.tcl</code>.&nbsp; The changes are shown below in
  <span class="red">red</span> color:</p>

  <blockquote>
    <pre>
package require mentry<span class="red">_tile</span>

set title "Phone Number"
wm title . $title

<span class="cmt">#
# Add some entries to the Tk option database
#</span>
source [file join [file dirname [info script]] option<span class="red">_tile</span>.tcl]

. . .

<span class="red">#
# Improve the window's appearance by using a tile
# frame as a container for the other widgets
#
ttk::frame .base</span>

<span class="cmt">#
# Frame <span class="red">.base</span>.f with a mentry displaying a phone number
#</span>
<span class="red">ttk::</span>frame .base.f
<span class="red">ttk::</span>label .base.f.l -text "A mentry widget for phone numbers:"
phoneNumberMentry <span class="red">.base</span>.f.me
pack <span class="red">.base</span>.f.l <span class="red">.base</span>.f.me

<span class="cmt">#
# Message strings corresponding to the values
# returned by getPhoneNumber on failure
#</span>
array set msgs {
    EMPTY       "Field value missing"
    INCOMPL     "Incomplete field value"
}

<span class="cmt">#
# Button <span class="red">.base</span>.get invoking the procedure getPhoneNumber
#</span>
<span class="red">ttk</span>::button <span class="red">.base</span>.get -text "Get from mentry" -command {
    if {[catch {
        set num ""
        set num [getPhoneNumber <span class="red">.base</span>.f.me]
    } result] != 0} {
        bell
        tk_messageBox -icon error -message $msgs($result) \
                      -title $title -type ok
    }
}

<span class="cmt">#
# Label <span class="red">.base</span>.num displaying the result of getPhoneNumber
#</span>
<span class="red">ttk::</span>label <span class="red">.base</span>.num -textvariable num -background white

. . .

putPhoneNumber 1234567890 <span class="red">.base</span>.f.me
focus [<span class="red">.base</span>.f.me entrypath 0]
</pre>
  </blockquote>

  <p>That's all!&nbsp; The resulting window has a nice theme-specific
  appearance:</p>

  <blockquote>
    <img src="phonenumber_tile.png" alt="Phone Number" width="267"
    height="216">
  </blockquote>

  <p>The only Mentry-specific change in the code above consists of the use of
  the <code>_tile</code> suffix in <code>mentry_tile</code>.</p>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>
</body>
</html>

<!DOCTYPE html>
<html>
<head>
  <title>Multi-Entry Widgets for Date and Time</title>

  <meta name="Author" content="Csaba Nemethi">
  <meta name="Keywords" content="mentry, widget, date, time, clock">

  <link rel="stylesheet" type="text/css" href="stylesheet.css">
</head>

<body>
  <div align="center">
    <h1>Multi-Entry Widgets for Date and Time</h1>

    <h2>For Mentry Version 3.10</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:csaba.nemethi@t-online.de">csaba.nemethi@t-online.de</a>
    </address>
  </div>

  <hr>

  <h2 id="contents">Contents</h2>

  <ul>
    <li><a href="#dateMentry">The <code><b>mentry::dateMentry</b></code>
    Command</a></li>

    <li><a href="#timeMentry">The <code><b>mentry::timeMentry</b></code>
    Command</a></li>

    <li><a href="#dateTimeMentry">The
    <code><b>mentry::dateTimeMentry</b></code> Command</a></li>

    <li><a href="#putClockVal">The <code><b>mentry::putClockVal</b></code>
    Command</a></li>

    <li><a href="#getClockVal">The <code><b>mentry::getClockVal</b></code>
    Command</a></li>
  </ul>

  <div align="center">
    <p><a href="index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="dateMentry">The <code><b>mentry::dateMentry</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::dateMentry</code> &ndash; Create and manipulate mentry
    widgets for date</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::dateMentry</b> <i>pathName format separator</i> ?<i>options</i>?
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command creates a new mentry widget <code><i>pathName</i></code>
    for displaying and editing a date according to the
    <code><i>format</i></code> argument, which must be a string of length 3,
    consisting of the letters <code><b>"d"</b></code> for the day
    (<code>01</code> - <code>31</code>), <code><b>"m"</b></code> for the month
    (<code>01</code> - <code>12</code>), and <code><b>"y"</b></code> or
    <code><b>"Y"</b></code> for the year without century (<code>00</code> -
    <code>99</code>) or with century (e.g., <code>2008</code>), in an arbitrary
    order.&nbsp; These field descriptor characters have the same meanings as in
    the&nbsp; <code><b>clock format</b></code>&nbsp; command.&nbsp; The
    <code><i>separator</i></code> argument specifies the text to be displayed
    in the labels separating the three entry children of the mentry widget (the
    most common values are the <code><b>"/"</b></code>,
    <code><b>"-"</b></code>, and <code><b>"."</b></code> characters).&nbsp; The
    supported <code><i>options</i></code> are the same as in the case of the
    <code><b><a href="mentryWidget.html">mentry::mentry</a></b></code>
    command.</dd>

    <dd class="tm">The command sets the <code><b>type</b></code> attribute of
    the widget to the value <code>"Date"</code>, saves the value of
    <code><i>format</i></code> in its <code><b>format</b></code> attribute, and
    returns the name of the newly created widget.</dd>

    <dt class="tm"><b>DEFAULT BINDINGS</b></dt>

    <dd>The <code><b>mentry::dateMentry</b></code> command defines four new
    keyboard bindings for the entry children of the mentry widget it
    creates:&nbsp; The <code>Up</code> key increments the entry's value by 1 if
    the latter is less than the allowed maximum for that child.&nbsp;
    Similarly, the <code>Down</code> key decrements the entry's value by 1 if
    the latter is greater than the allowed minimum for that child.&nbsp; The
    <code>Prior</code> key increments the entry's value by at most 10 if the
    latter is less than the allowed maximum for that child.&nbsp; Similarly,
    the <code>Next</code> key decrements the entry's value by at most 10 if the
    latter is greater than the allowed minimum for that child.&nbsp; If the
    entry is empty then all of these keys insert the child-specific minimum
    value into the entry.</dd>

    <dd class="tm">The actions performed by the <code>Up</code> and
    <code>Down</code> keys can also be triggered by rolling the mouse
    wheel.&nbsp; In addition, on Mac OS Classic and Mac OS X Aqua, the actions
    performed by the <code>Prior</code> and <code>Next</code> keys can also be
    triggered by rolling the mouse wheel while holding down the
    <code>Option</code> key.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mentry, widget, date</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="timeMentry">The <code><b>mentry::timeMentry</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::timeMentry</code> &ndash; Create and manipulate mentry
    widgets for time</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::timeMentry</b> <i>pathName format separator</i> ?<i>options</i>?
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command creates a new mentry widget <code><i>pathName</i></code>
    for displaying and editing a time according to the
    <code><i>format</i></code> argument, which must be a string of length 2 or
    3, consisting of the following field descriptor characters of the&nbsp;
    <code><b>clock format</b></code>&nbsp; command: <code><b>"H"</b></code> or
    <code><b>"I"</b></code>, followed by <code><b>"M"</b></code>, and
    optionally the letter <code><b>"S"</b></code>.&nbsp; An
    <code><b>"H"</b></code> as first character specifies the time format
    <code><b>"%H:%M"</b></code> or <code><b>"%H:%M:%S"</b></code> (i.e., with
    the hour between <code>0</code> and <code>23</code>), while the letter
    <code><b>"I"</b></code> stands for&nbsp; <code><b>"%I:%M
    %p"</b></code>&nbsp; or&nbsp; <code><b>"%I:%M:%S %p"</b></code>&nbsp;
    (i.e., with AM/PM indicator).&nbsp; The <code><i>separator</i></code>
    argument specifies the text to be displayed in the labels separating the
    entry children of the mentry widget (this is usually the
    <code><b>":"</b></code> character).&nbsp; The <code><i>options</i></code>
    are the same as in the case of the <code><b><a href=
    "mentryWidget.html">mentry::mentry</a></b></code> command.</dd>

    <dd class="tm">The command sets the <code><b>type</b></code> attribute of
    the widget to the value <code>"Time"</code>, saves the value of
    <code><i>format</i></code> in its <code><b>format</b></code> attribute, and
    returns the name of the newly created widget.</dd>

    <dt class="tm"><b>DEFAULT BINDINGS</b></dt>

    <dd>The <code><b>mentry::timeMentry</b></code> command defines four new
    keyboard bindings for the entry children of the mentry widget it
    creates:&nbsp; The <code>Up</code> key increments the entry's value by 1 if
    the latter is less than the allowed maximum for that child.&nbsp;
    Similarly, the <code>Down</code> key decrements the entry's value by 1 if
    the latter is greater than the allowed minimum for that child.&nbsp; The
    <code>Prior</code> key increments the entry's value by at most 10 if the
    latter is less than the allowed maximum for that child.&nbsp; Similarly,
    the <code>Next</code> key decrements the entry's value by at most 10 if the
    latter is greater than the allowed minimum for that child.&nbsp; If the
    entry is empty then all of these keys insert the child-specific minimum
    value into the entry.</dd>

    <dd class="tm">The actions performed by the <code>Up</code> and
    <code>Down</code> keys can also be triggered by rolling the mouse
    wheel.&nbsp; In addition, on Mac OS Classic and Mac OS X Aqua, the actions
    performed by the <code>Prior</code> and <code>Next</code> keys can also be
    triggered by rolling the mouse wheel while holding down the
    <code>Option</code> key.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mentry, widget, time</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="dateTimeMentry">The <code><b>mentry::dateTimeMentry</b></code>
  Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::dateTimeMentry</code> &ndash; Create and manipulate
    mentry widgets for date & time</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::dateTimeMentry</b> <i>pathName format dateSeparator timeSeparator</i> ?<i>options</i>?
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command creates a new mentry widget <code><i>pathName</i></code>
    for displaying and editing a date & time according to the
    <code><i>format</i></code> argument, which must be a string of length 5 or
    6, with the first 3 characters consisting of the letters
    <code><b>"d"</b></code> for the day (<code>01</code> - <code>31</code>),
    <code><b>"m"</b></code> for the month (<code>01</code> - <code>12</code>),
    and <code><b>"y"</b></code> or <code><b>"Y"</b></code> for the year without
    century (<code>00</code> - <code>99</code>) or with century (e.g.,
    <code>2008</code>), in an arbitrary order, followed by 2 or 3 further field
    descriptor characters of the&nbsp;<code><b>clock format</b></code>&nbsp;
    command, which must be: <code><b>"H"</b></code> or <code><b>"I"</b></code>,
    then <code><b>"M"</b></code>, and optionally the letter
    <code><b>"S"</b></code>.&nbsp; An <code><b>"H"</b></code> specifies the
    time format <code><b>"%H:%M"</b></code> or <code><b>"%H:%M:%S"</b></code>
    (i.e., with the hour between <code>0</code> and <code>23</code>), while the
    letter <code><b>"I"</b></code> stands for&nbsp; <code><b>"%I:%M
    %p"</b></code>&nbsp; or&nbsp; <code><b>"%I:%M:%S %p"</b></code>&nbsp;
    (i.e., with AM/PM indicator).&nbsp; The <code><i>dateSeparator</i></code>
    argument specifies the text to be displayed in the labels separating the
    entry children in the date part of the mentry widget (the most common
    values are the <code><b>"/"</b></code>, <code><b>"-"</b></code>, and
    <code><b>"."</b></code> characters).&nbsp; Similarly, the
    <code><i>timeSeparator</i></code> argument stands for the text to be
    displayed in the labels separating the entry children in the time part of
    mentry widget (this is usually the <code><b>":"</b></code>
    character).&nbsp; The date and time parts in turn are separated from each
    other by a space character.&nbsp; The supported <code><i>options</i></code>
    are the same as in the case of the <code><b><a href=
    "mentryWidget.html">mentry::mentry</a></b></code> command.</dd>

    <dd class="tm">The command sets the <code><b>type</b></code> attribute of
    the widget to the value <code>"DateTime"</code>, saves the value of
    <code><i>format</i></code> in its <code><b>format</b></code> attribute, and
    returns the name of the newly created widget.</dd>

    <dt class="tm"><b>DEFAULT BINDINGS</b></dt>

    <dd>The <code><b>mentry::dateTimeMentry</b></code> command defines four new
    keyboard bindings for the entry children of the mentry widget it
    creates:&nbsp; The <code>Up</code> key increments the entry's value by 1 if
    the latter is less than the allowed maximum for that child.&nbsp;
    Similarly, the <code>Down</code> key decrements the entry's value by 1 if
    the latter is greater than the allowed minimum for that child.&nbsp; The
    <code>Prior</code> key increments the entry's value by at most 10 if the
    latter is less than the allowed maximum for that child.&nbsp; Similarly,
    the <code>Next</code> key decrements the entry's value by at most 10 if the
    latter is greater than the allowed minimum for that child.&nbsp; If the
    entry is empty then all of these keys insert the child-specific minimum
    value into the entry.</dd>

    <dd class="tm">The actions performed by the <code>Up</code> and
    <code>Down</code> keys can also be triggered by rolling the mouse
    wheel.&nbsp; In addition, on Mac OS Classic and Mac OS X Aqua, the actions
    performed by the <code>Prior</code> and <code>Next</code> keys can also be
    triggered by rolling the mouse wheel while holding down the
    <code>Option</code> key.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mentry, widget, date, time</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="putClockVal">The <code><b>mentry::putClockVal</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::putClockVal</code> &ndash; Output a clock value to a
    date, time, or date & time mentry</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::putClockVal</b> <i>clockValue</i> <i>pathName</i> ?<b>-gmt</b> <i>boolean</i>?
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command outputs the date, time, or date & time corresponding to
    the integer <code><i>clockValue</i></code> to the mentry widget
    <code><i>pathName</i></code>, which must have been created with the
    <code><b><a href="#dateMentry">mentry::dateMentry</a></b></code>,
    <code><b><a href="#timeMentry">mentry::timeMentry</a></b></code>, or
    <code><b><a href="#dateTimeMentry">mentry::dateTimeMentry</a></b></code>
    command (this is checked by examining the widget's <code><b>type</b></code>
    attribute, which must have the value <code>"Date"</code>,
    <code>"Time"</code>, or <code>"DateTime"</code>).</dd>

    <dd class="tm">Like in the case of the&nbsp; <code><b>clock
    format</b></code>&nbsp; command, the optional argument pair&nbsp;
    <code><b>-gmt</b> <i>boolean</i></code> specifies whether the clock value
    is to be formatted as Greenwich Mean Time or according to the local
    timezone as defined by the operating environment.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mentry, widget, date, time, clock</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="getClockVal">The <code><b>mentry::getClockVal</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::getClockVal</code> &ndash; Get the clock value from a
    date, time, or date & time mentry</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::getClockVal</b> <i>pathName</i> ?<b>-base</b> <i>clockValue</i>? ?<b>-gmt</b> <i>boolean</i>?
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command returns the clock value corresponding to the date, time,
    or date & time contained in the mentry widget <code><i>pathName</i></code>,
    which must have been created with the <code><b><a href=
    "#dateMentry">mentry::dateMentry</a></b></code>, <code><b><a href=
    "#timeMentry">mentry::timeMentry</a></b></code>, or <code><b><a href=
    "#dateTimeMentry">mentry::dateTimeMentry</a></b></code> command (this is
    checked by examining the widget's <code><b>type</b></code> attribute, which
    must have the value <code>"Date"</code>, <code>"Time"</code>, or
    <code>"DateTime"</code>).</dd>

    <dd class="tm">Like in the case of the&nbsp; <code><b>clock
    scan</b></code>&nbsp; command, the optional argument pair&nbsp;
    <code><b>-base</b> <i>clockValue</i></code> specifies that the date
    contained in <code><i>clockValue</i></code> is to be used when getting the
    clock value from the given mentry widget, and the optional argument
    pair&nbsp; <code><b>-gmt</b> <i>boolean</i></code> specifies whether the
    clock value is to be calculated relative to Greenwich Mean Time or
    according to the local timezone as defined by the operating
    environment.</dd>

    <dd class="tm">If an error occurs during the conversion, the command sets
    the focus to the first erronous entry child, generates an error, and
    returns one of the values contained in the following table:</dd>

    <dd class="tm">
      <table border="2" cellspacing="0" cellpadding="3">
        <tr bgcolor="#FFFFE0">
          <th align="left" nowrap>Return Value</th>

          <th align="left">Meaning</th>
        </tr>

        <tr>
          <td><code>"EMPTY"</code></td>

          <td>Any entry child (except the one containing the seconds) is
          empty.</td>
        </tr>

        <tr>
          <td><code>"BAD"</code></td>

          <td>The value of the day, month, or hour (the latter only if the
          AM/PM indicator is present) is <code>0</code>.</td>
        </tr>

        <tr>
          <td><code>"BAD_DATE"</code></td>

          <td>The &lt;year, month, day&gt; triple is invalid (note that the
          command is aware of leap years).</td>
        </tr>

        <tr>
          <td><code>"BAD_YEAR"</code></td>

          <td>The above triple is valid, but the conversion (made with the aid
          of the&nbsp; <code><b>clock scan</b></code>&nbsp; command) failed
          because of an unsupported year value (e.g., between <code>38</code>
          and <code>70</code>).</td>
        </tr>
      </table>
    </dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mentry, widget, date, time, clock</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>
</body>
</html>

<!DOCTYPE html>
<html>
<head>
  <title>Multi-Entry Widgets for Real Numbers in Fixed-Point Format</title>

  <meta name="Author" content="Csaba Nemethi">
  <meta name="Keywords" content="mentry, widget, real number">

  <link rel="stylesheet" type="text/css" href="stylesheet.css">
</head>

<body>
  <div align="center">
    <h1>Multi-Entry Widgets for Real Numbers<br>
    in Fixed-Point Format</h1>

    <h2>For Mentry Version 3.10</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:csaba.nemethi@t-online.de">csaba.nemethi@t-online.de</a>
    </address>
  </div>

  <hr>

  <h2 id="contents">Contents</h2>

  <ul>
    <li><a href="#fixedPointMentry">The
    <code><b>mentry::fixedPointMentry</b></code> Command</a></li>

    <li><a href="#putReal">The <code><b>mentry::putReal</b></code>
    Command</a></li>

    <li><a href="#getReal">The <code><b>mentry::getReal</b></code>
    Command</a></li>
  </ul>

  <div align="center">
    <p><a href="index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="fixedPointMentry">The <code><b>mentry::fixedPointMentry</b></code>
  Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::fixedPointMentry</code> &ndash; Create and manipulate
    mentry widgets for real numbers in fixed-point format</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::fixedPointMentry</b> <i>pathName count1 count2</i> ?<b>-comma</b>? ?<i>options</i>?
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command creates a new mentry widget <code><i>pathName</i></code>
    for displaying and editing real numbers in fixed-point format, with
    <code><i>count1</i></code> characters before and <code><i>count2</i></code>
    digits after the decimal point.&nbsp; Both <code><i>count1</i></code> and
    <code><i>count2</i></code> must be positive integers.&nbsp; The mentry will
    have two entry children, separated by a label displaying a
    <code><b>"."</b></code> character by default; the optional
    <code><b>-comma</b></code> switch changes the label text to
    <code><b>","</b></code>.&nbsp; The supported <code><i>options</i></code>
    are the same as in the case of the <code><b><a href=
    "mentryWidget.html">mentry::mentry</a></b></code> command.</dd>

    <dd class="tm">The command sets the <code><b>type</b></code> attribute of
    the widget to the value <code>"FixedPoint"</code> and returns the name of
    the newly created widget.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mentry, widget, real number</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="putReal">The <code><b>mentry::putReal</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::putReal</code> &ndash; Output a real number to a mentry
    of type <code>"FixedPoint"</code></dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::putReal</b> <i>number</i> <i>pathName</i>
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command outputs the real number <code><i>number</i></code> to the
    mentry widget <code><i>pathName</i></code>, which must have been created
    with the <code><b><a href=
    "#fixedPointMentry">mentry::fixedPointMentry</a></b></code> command (this
    is checked by examining the widget's <code><b>type</b></code> attribute,
    which must have the value <code>"FixedPoint"</code>).</dd>

    <dd class="tm">The command generates an error if the number does not fit
    into the widget because it has too many characters before the decimal
    point.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mentry, widget, real number</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="getReal">The <code><b>mentry::getReal</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::getReal</code> &ndash; Get a real number from a mentry of
    type <code>"FixedPoint"</code></dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::getReal</b> <i>pathName</i>
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command returns the number contained in the mentry widget
    <code><i>pathName</i></code>, which must have been created with the
    <code><b><a href=
    "#fixedPointMentry">mentry::fixedPointMentry</a></b></code> command (this
    is checked by examining the widget's <code><b>type</b></code> attribute,
    which must have the value <code>"FixedPoint"</code>).</dd>

    <dd class="tm">If both entry children of the widget are empty, the command
    sets the focus to the first entry child, generates an error, and returns
    the string <code>"EMPTY"</code>.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mentry, widget, real number</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>
</body>
</html>

<!DOCTYPE html>
<html>
<head>
  <title>Multi-Entry Widgets for IP Addresses</title>

  <meta name="Author" content="Csaba Nemethi">
  <meta name="Keywords" content="mentry, widget, IP address">

  <link rel="stylesheet" type="text/css" href="stylesheet.css">
</head>

<body>
  <div align="center">
    <h1>Multi-Entry Widgets for IP Addresses</h1>

    <h2>For Mentry Version 3.10</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:csaba.nemethi@t-online.de">csaba.nemethi@t-online.de</a>
    </address>
  </div>

  <hr>

  <h2 id="contents">Contents</h2>

  <ul>
    <li><a href="#ipAddrMentry">The <code><b>mentry::ipAddrMentry</b></code>
    Command</a></li>

    <li><a href="#putIPAddr">The <code><b>mentry::putIPAddr</b></code>
    Command</a></li>

    <li><a href="#getIPAddr">The <code><b>mentry::getIPAddr</b></code>
    Command</a></li>
  </ul>

  <div align="center">
    <p><a href="index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="ipAddrMentry">The <code><b>mentry::ipAddrMentry</b></code>
  Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::ipAddrMentry</code> &ndash; Create and manipulate mentry
    widgets for IP addresses</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::ipAddrMentry</b> <i>pathName</i> ?<i>options</i>?
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command creates a new mentry widget <code><i>pathName</i></code>
    for displaying and editing IP addresses in the standard dotted-decimal
    notation.&nbsp; The supported <code><i>options</i></code> are the same as
    in the case of the <code><b><a href=
    "mentryWidget.html">mentry::mentry</a></b></code> command.</dd>

    <dd class="tm">The command sets the <code><b>type</b></code> attribute of
    the widget to the value <code>"IPAddr"</code> and returns the name of the
    newly created widget.</dd>

    <dt class="tm"><b>DEFAULT BINDINGS</b></dt>

    <dd>The <code><b>mentry::ipAddrMentry</b></code> command defines four new
    keyboard bindings for the entry children of the mentry widget it
    creates:&nbsp; The <code>Up</code> key increments the entry's value by 1 if
    the latter is less than 255.&nbsp; Similarly, the <code>Down</code> key
    decrements the entry's value by 1 if the latter is greater than 0.&nbsp;
    The <code>Prior</code> key increments the entry's value by at most 10 if
    the latter is less than 255.&nbsp; Similarly, the <code>Next</code> key
    decrements the entry's value by at most 10 if the latter is greater than
    0.&nbsp; If the entry is empty then all of these keys insert the value
    <code>0</code> into the entry.</dd>

    <dd class="tm">The actions performed by the <code>Up</code> and
    <code>Down</code> keys can also be triggered by rolling the mouse
    wheel.&nbsp; In addition, on Mac OS Classic and Mac OS X Aqua, the actions
    performed by the <code>Prior</code> and <code>Next</code> keys can also be
    triggered by rolling the mouse wheel while holding down the
    <code>Option</code> key.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mentry, widget, IP address</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="putIPAddr">The <code><b>mentry::putIPAddr</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::putIPAddr</code> &ndash; Output an IP address to a mentry
    of type <code>"IPAddr"</code></dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::putIPAddr</b> <i>address</i> <i>pathName</i>
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command outputs the IP address <code><i>address</i></code> to the
    mentry widget <code><i>pathName</i></code>, which must have been created
    with the <code><b><a href=
    "#ipAddrMentry">mentry::ipAddrMentry</a></b></code> command (this is
    checked by examining the widget's <code><b>type</b></code> attribute, which
    must have the value <code>"IPAddr"</code>).</dd>

    <dd class="tm">The command generates an error if the address is
    invalid.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mentry, widget, IP address</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="getIPAddr">The <code><b>mentry::getIPAddr</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::getIPAddr</code> &ndash; Get an IP address from a mentry
    of type <code>"IPAddr"</code></dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::getIPAddr</b> <i>pathName</i>
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command returns the IP address contained in the mentry widget
    <code><i>pathName</i></code>, which must have been created with the
    <code><b><a href="#ipAddrMentry">mentry::ipAddrMentry</a></b></code>
    command (this is checked by examining the widget's <code><b>type</b></code>
    attribute, which must have the value <code>"IPAddr"</code>).</dd>

    <dd class="tm">If any entry child of the widget is empty, the command sets
    the focus to the first such entry, generates an error, and returns the
    string <code>"EMPTY"</code>.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mentry, widget, IP address</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>
</body>
</html>

<!DOCTYPE html>
<html>
<head>
  <title>Multi-Entry Widgets for IPv6 Addresses</title>

  <meta name="Author" content="Csaba Nemethi">
  <meta name="Keywords" content="mentry, widget, IPv6 address">

  <link rel="stylesheet" type="text/css" href="stylesheet.css">
</head>

<body>
  <div align="center">
    <h1>Multi-Entry Widgets for IPv6 Addresses</h1>

    <h2>For Mentry Version 3.10</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:csaba.nemethi@t-online.de">csaba.nemethi@t-online.de</a>
    </address>
  </div>

  <hr>

  <h2 id="contents">Contents</h2>

  <ul>
    <li><a href="#ipv6AddrMentry">The
    <code><b>mentry::ipv6AddrMentry</b></code> Command</a></li>

    <li><a href="#putIPv6Addr">The <code><b>mentry::putIPv6Addr</b></code>
    Command</a></li>

    <li><a href="#getIPv6Addr">The <code><b>mentry::getIPv6Addr</b></code>
    Command</a></li>
  </ul>

  <div align="center">
    <p><a href="index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="ipv6AddrMentry">The <code><b>mentry::ipv6AddrMentry</b></code>
  Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::ipv6AddrMentry</code> &ndash; Create and manipulate
    mentry widgets for IPv6 addresses</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::ipv6AddrMentry</b> <i>pathName</i> ?<i>options</i>?
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command creates a new mentry widget <code><i>pathName</i></code>
    for displaying and editing IPv6 addresses in the standard hexadecimal
    notation (where the eight groups of one to four hexadecimal digits are
    separated from each other by o colon).&nbsp; The supported
    <code><i>options</i></code> are the same as in the case of the
    <code><b><a href="mentryWidget.html">mentry::mentry</a></b></code>
    command.</dd>

    <dd class="tm">The command sets the <code><b>type</b></code> attribute of
    the widget to the value <code>"IPv6Addr"</code> and returns the name of the
    newly created widget.</dd>

    <dt class="tm"><b>DEFAULT BINDINGS</b></dt>

    <dd>The <code><b>mentry::ipv6AddrMentry</b></code> command defines four new
    keyboard bindings for the entry children of the mentry widget it
    creates:&nbsp; The <code>Up</code> key increments the entry's value by 1 if
    the latter is less than 65535.&nbsp; Similarly, the <code>Down</code> key
    decrements the entry's value by 1 if the latter is greater than 0.&nbsp;
    The <code>Prior</code> key increments the entry's value by at most 10 if
    the latter is less than 65535.&nbsp; Similarly, the <code>Next</code> key
    decrements the entry's value by at most 10 if the latter is greater than
    0.&nbsp; If the entry is empty then all of these keys insert the value
    <code>0</code> into the entry.</dd>

    <dd class="tm">The actions performed by the <code>Up</code> and
    <code>Down</code> keys can also be triggered by rolling the mouse
    wheel.&nbsp; In addition, on Mac OS Classic and Mac OS X Aqua, the actions
    performed by the <code>Prior</code> and <code>Next</code> keys can also be
    triggered by rolling the mouse wheel while holding down the
    <code>Option</code> key.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mentry, widget, IPv6 address</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="putIPAddr">The <code><b>mentry::putIPv6Addr</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::putIPv6Addr</code> &ndash; Output an IPv6 address to a
    mentry of type <code>"IPv6Addr"</code></dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::putIPv6Addr</b> <i>address</i> <i>pathName</i>
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command outputs the IPv6 address <code><i>address</i></code> to
    the mentry widget <code><i>pathName</i></code>, which must have been
    created with the <code><b><a href=
    "#ipv6AddrMentry">mentry::ipv6AddrMentry</a></b></code> command (this is
    checked by examining the widget's <code><b>type</b></code> attribute, which
    must have the value <code>"IPv6Addr"</code>).</dd>

    <dd class="tm">The address is expected to consist of up to eight
    colon-separated groups of one to four hexadecimal digits each.&nbsp; in
    case of less than eight groups, the address must include exactly one
    double-colon (<code>::</code>) (representing consecutive groups of
    zeros).&nbsp; The command generates an error if the address is
    invalid.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mentry, widget, IPv6 address</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="getIPv6Addr">The <code><b>mentry::getIPv6Addr</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::getIPv6Addr</code> &ndash; Get an IPv6 address from a
    mentry of type <code>"IPv6Addr"</code></dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::getIPv6Addr</b> <i>pathName</i>
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command returns the IPv6 address contained in the mentry widget
    <code><i>pathName</i></code>, which must have been created with the
    <code><b><a href="#ipv6AddrMentry">mentry::ipv6AddrMentry</a></b></code>
    command (this is checked by examining the widget's <code><b>type</b></code>
    attribute, which must have the value <code>"IPv6Addr"</code>).</dd>

    <dd class="tm">If any entry child of the widget is empty, the command sets
    the focus to the first such entry, generates an error, and returns the
    string <code>"EMPTY"</code>.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mentry, widget, IPv6 address</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>
</body>
</html>

<!DOCTYPE html>
<html>
<head>
  <title>Commands Related to Tile Themes</title>

  <meta name="Author" content="Csaba Nemethi">
  <meta name="Keywords" content="mentry, theme, tile">

  <link rel="stylesheet" type="text/css" href="stylesheet.css">
</head>

<body>
  <div align="center">
    <h1>Commands Related to Tile Themes</h1>

    <h2>For Mentry Version 3.10</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:csaba.nemethi@t-online.de">csaba.nemethi@t-online.de</a>
    </address>
  </div>

  <hr>

  <h2 id="contents">Contents</h2>

  <ul>
    <li><a href="#overview">Overview</a></li>

    <li><a href="#setTheme">The <code><b>mentry::setTheme</b></code>
    Command</a></li>

    <li><a href="#getCurrentTheme">The
    <code><b>mentry::getCurrentTheme</b></code> Command</a></li>

    <li><a href="#getThemes">The <code><b>mentry::getThemes</b></code>
    Command</a></li>

    <li><a href="#setThemeDefaults">The
    <code><b>mentry::setThemeDefaults</b></code> Command</a></li>
  </ul>

  <div align="center">
    <p><a href="index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="overview">Overview</h2>

  <p>The commands described in this reference page should only be invoked when
  using the package Mentry_tile.&nbsp; They enable you to set and query the
  current theme, to retrieve a list of the available themes, and to make sure
  that your widgets will have a theme-specific appearance.</p>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="setTheme">The <code><b>mentry::setTheme</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::setTheme</code> &ndash; Set the current theme</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::setTheme</b> <i>theme</i>
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command sets the current theme to <code><i>theme</i></code>,
    loading it if necessary.&nbsp; It is simply an alias for
    <code><b>ttk::setTheme</b></code> or <code><b>tile::setTheme</b></code>,
    depending on the tile version loaded into the interpreter.&nbsp; (The
    <code><b>tile::setTheme</b></code> command was renamed to
    <code><b>ttk::setTheme</b></code> in tile version 0.8.)</dd>

    <dd class="tm">Being just an alias for a tile library procedure, the
    <code><b>mentry::setTheme</b></code> command does exactly the same as the
    original one: It loads the package implementing the given theme if needed,
    sets the theme to the specified one, and saves the latter in the variable
    <code><b>ttk::currentTheme</b></code> or
    <code><b>tile::currentTheme</b></code>, depending on the current tile
    version.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mentry, theme, tile</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="getCurrentTheme">The <code><b>mentry::getCurrentTheme</b></code>
  Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::getCurrentTheme</code> &ndash; Get the current theme</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::getCurrentTheme</b>
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command returns the value of the variable
    <code><b>ttk::currentTheme</b></code> or
    <code><b>tile::currentTheme</b></code>, depending on the tile version
    loaded into the interpreter.&nbsp; (The namespace containing the variable
    <code><b>currentTheme</b></code> was changed in tile version 0.8 from
    <code><b>tile</b></code> to <code><b>ttk</b></code>.)</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mentry, theme, tile</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="getThemes">The <code><b>mentry::getThemes</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::getThemes</code> &ndash; Get the themes registered in the
    package database</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::getThemes</b>
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command returns a list of the themes registered in the package
    database.&nbsp; It is simply an alias for <code><b>ttk::themes</b></code>
    or <code><b>tile::availableThemes</b></code>, depending on the tile version
    loaded into the interpreter.&nbsp; (The
    <code><b>tile::availableThemes</b></code> command was renamed to
    <code><b>ttk::themes</b></code> in tile version 0.8.)</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mentry, theme, tile</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="setThemeDefaults">The <code><b>mentry::setThemeDefaults</b></code>
  Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::setThemeDefaults</code> &ndash; Set theme-specific
    default values of some mentry configuration options</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::setThemeDefaults</b>
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command populates the array
    <code><b>mentry::themeDefaults</b></code> with theme-specific default
    values of a series of Mentry configuration options.&nbsp; The array names
    are the command-line names of the options, and the corresponding array
    values are the default values of these configuration options for the
    currently set tile theme.</dd>

    <dd class="tm">The options whose names and values are written into the
    array <code><b>mentry::themeDefaults</b></code> are:
    <code><b>-background</b></code>, <code><b>-foreground</b></code>, and
    <code><b>-font</b></code>.&nbsp; In addition, the command sets some other
    array elements to theme-specific default values, needed for internal
    purposes, like updating the background and foreground colors of the label
    components of a mentry widget in <code><b>disabled</b></code> or
    <code><b>readonly</b></code> state; the corresponding array names are:
    <code><b>-disabledbackground</b></code>,
    <code><b>-disabledforeground</b></code>, and
    <code><b>-readonlybackground</b></code>.&nbsp; Finally, the array values
    associated with the names <code><b>-selectbackground</b></code>,
    <code><b>-selectforeground</b></code>, and
    <code><b>-selectborderwidth</b></code> are not used by Mentry_tile, but
    might prove useful for other purposes, as described below.</dd>

    <dd class="tm">The <code><b>mentry::setThemeDefaults</b></code> command is
    invoked by Mentry_tile automatically whenever a mentry widget is createad
    or the <code><b>&lt;&lt;ThemeChanged&gt;&gt;</b></code> virtual event is
    received by a mentry widget.&nbsp; In the latter case, the widget is
    reconfigured, using the new default values of those options that were not
    set explicitly to values different from the corresponding defaults.</dd>

    <dd class="tm">Besides being used by the Mentry_tile code, this command can
    also be invoked in Tcl scripts, still before creating any tile-based mentry
    widget.&nbsp; By calling it explicitly and using the values written by it
    into the array <code><b>mentry::themeDefaults</b></code>, you can make sure
    that classical Tk widgets, e.g., text, will have a theme-specific
    appearance, just like the tile widgets.&nbsp; For example, you can add some
    common configuration options to the option database as follows:</dd>

    <dd>
      <blockquote>
        <pre>
mentry::setThemeDefaults
option add *Text.background   $mentry::themeDefaults(-background)
option add *Text.foreground   $mentry::themeDefaults(-foreground)
option add *Font              $mentry::themeDefaults(-font)
option add *selectBackground  $mentry::themeDefaults(-selectbackground)
option add *selectForeground  $mentry::themeDefaults(-selectforeground)
option add *selectBorderWidth $mentry::themeDefaults(-selectborderwidth)
</pre>
      </blockquote>
    </dd>

    <dt><b>KEYWORDS</b></dt>

    <dd>mentry, theme, tile</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>
</body>
</html>

<!DOCTYPE html>
<html>
<head>
  <title>The mentry::mentry Command</title>

  <meta name="Author" content="Csaba Nemethi">
  <meta name="Keywords" content="mentry, widget, entry, label">

  <link rel="stylesheet" type="text/css" href="stylesheet.css">
</head>

<body>
  <div align="center">
    <h1>The <code><b>mentry::mentry</b></code> Command</h1>

    <h2>For Mentry Version 3.10</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:csaba.nemethi@t-online.de">csaba.nemethi@t-online.de</a>
    </address>
  </div>

  <hr>

  <h2 id="contents">Contents</h2>

  <ul>
    <li><a href="#quick_ref">Quick Reference</a></li>

    <li><a href="#detailed_ref">Detailed Reference</a></li>
  </ul>

  <div align="center">
    <p><a href="index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="quick_ref">Quick Reference</h2>

  <dl>
    <dt><a href="#name">NAME</a></dt>

    <dd><code>mentry::mentry</code> &ndash; Create and manipulate multi-entry
    widgets</dd>

    <dt class="tm"><a href="#synopsis">SYNOPSIS</a></dt>

    <dd>
      <pre>
<b>mentry::mentry</b> <i>pathName</i> ?<i>options</i>?
</pre>
    </dd>

    <dt><a href="#description">DESCRIPTION</a></dt>

    <dt class="tm"><a href="#std_options">STANDARD OPTIONS</a></dt>

    <dd>
      <pre>
<b>-borderwidth          -highlightcolor      -relief
-highlightbackground  -highlightthickness</b>
</pre>
    </dd>

    <dt><a href="#child_options">OPTIONS FOR ALL ENTRY AND LABEL
    CHILDREN</a></dt>

    <dd>
      <pre>
<b>-background  -cursor  -font  -foreground</b>
</pre>
    </dd>

    <dt><a href="#entry_options">OPTIONS FOR ALL ENTRY CHILDREN</a></dt>

    <dd>
      <pre>
<b>-exportselection    -insertwidth        -selectforeground
-insertbackground   -invalidcommand     -show
-insertborderwidth  -justify            -state
-insertofftime      -selectbackground   -validate
-insertontime       -selectborderwidth  -validatecommand</b>
</pre>
    </dd>

    <dt><a href="#widget_options">WIDGET-SPECIFIC OPTIONS</a></dt>

    <dd><code><b><a href="#body">-body</a></b> {<i>width</i> ?<i>text</i>
    <i>width</i> <i>text</i> ...?}</code></dd>

    <dd><code><b><a href="#disabledbackground">-disabledbackground</a></b>
    <i>color</i></code></dd>

    <dd><code><b><a href="#disabledforeground">-disabledforeground</a></b>
    <i>color</i></code></dd>

    <dd><code><b><a href="#readonlybackground">-readonlybackground</a></b>
    <i>color</i></code></dd>

    <dd><code><b><a href="#takefocus">-takefocus</a></b>
    <b>0</b>|<b>1</b>|<b>""</b>|<i>command</i></code></dd>

    <dd><code><b><a href="#textvariable">-textvariable</a></b>
    <i>array</i></code></dd>

    <dt class="tm"><a href="#indices">INDICES</a></dt>

    <dd>
      <pre>
<i>number</i>  <b>end</b>
</pre>
    </dd>

    <dt class="tm"><a href="#widget_command">WIDGET COMMAND</a></dt>

    <dd><code><i>pathName</i> <b><a href="#adjustentry">adjustentry</a></b>
    <i>index</i> <i>string</i></code></dd>

    <dd><code><i>pathName</i> <b><a href="#attrib">attrib</a></b> ?<i>name</i>?
    ?<i>value</i> <i>name</i> <i>value</i> ...?</code></dd>

    <dd><code><i>pathName</i> <b><a href="#cget">cget</a></b>
    <i>option</i></code></dd>

    <dd><code><i>pathName</i> <b><a href="#clear">clear</a></b> <i>first</i>
    ?<i>last</i>?</code></dd>

    <dd><code><i>pathName</i> <b><a href="#configure">configure</a></b>
    ?<i>option</i>? ?<i>value</i> <i>option</i> <i>value</i> ...?</code></dd>

    <dd><code><i>pathName</i> <b><a href="#entries">entries</a></b></code></dd>

    <dd><code><i>pathName</i> <b><a href=
    "#entrycount">entrycount</a></b></code></dd>

    <dd><code><i>pathName</i> <b><a href="#entrylimit">entrylimit</a></b>
    <i>index</i></code></dd>

    <dd><code><i>pathName</i> <b><a href="#entrypath">entrypath</a></b>
    <i>index</i></code></dd>

    <dd><code><i>pathName</i> <b><a href="#getarray">getarray</a></b>
    <i>array</i></code></dd>

    <dd><code><i>pathName</i> <b><a href="#getlist">getlist</a></b></code></dd>

    <dd><code><i>pathName</i> <b><a href=
    "#getstring">getstring</a></b></code></dd>

    <dd><code><i>pathName</i> <b><a href="#hasattrib">hasattrib</a></b>
    <i>name</i></code></dd>

    <dd><code><i>pathName</i> <b><a href="#isempty">isempty</a></b>
    ?<i>index</i>?</code></dd>

    <dd><code><i>pathName</i> <b><a href="#isfull">isfull</a></b>
    ?<i>index</i>?</code></dd>

    <dd><code><i>pathName</i> <b><a href=
    "#labelcount">labelcount</a></b></code></dd>

    <dd><code><i>pathName</i> <b><a href="#labelpath">labelpath</a></b>
    <i>index</i></code></dd>

    <dd><code><i>pathName</i> <b><a href="#labels">labels</a></b></code></dd>

    <dd><code><i>pathName</i> <b><a href="#put">put</a></b> <i>startIndex</i>
    ?<i>string</i> <i>string</i> ...?</code></dd>

    <dd><code><i>pathName</i> <b><a href=
    "#setentryextrawidth">setentryextrawidth</a></b> <i>index</i>
    <i>amount</i></code></dd>

    <dd><code><i>pathName</i> <b><a href="#setentryfont">setentryfont</a></b>
    <i>index</i> <i>font</i></code></dd>

    <dd><code><i>pathName</i> <b><a href="#setentrywidth">setentrywidth</a></b>
    <i>index</i> <i>width</i></code></dd>

    <dd><code><i>pathName</i> <b><a href="#unsetattrib">unsetattrib</a></b>
    <i>name</i></code></dd>

    <dt class="tm"><a href="#bindings">DEFAULT BINDINGS</a></dt>

    <dt class="tm"><a href="#keywords">KEYWORDS</a></dt>

    <dd>mentry, widget, entry, label</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="detailed_ref">Detailed Reference</h2>

  <dl>
    <dt id="name"><b>NAME</b></dt>

    <dd><code>mentry::mentry</code> &ndash; Create and manipulate multi-entry
    widgets</dd>

    <dt class="tm" id="synopsis"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::mentry</b> <i>pathName</i> ?<i>options</i>?
</pre>
    </dd>

    <dt id="description"><b>DESCRIPTION</b></dt>

    <dd>The <code><b>mentry::mentry</b></code> command creates a new window
    named <code><i>pathName</i></code> and of the class
    <code><b>Mentry</b></code>, and makes it into a <b>mentry</b> widget.&nbsp;
    Additional options, described below, may be specified on the command line
    or in the option database to configure aspects of the mentry such as its
    colors, font, and children.&nbsp; The <code><b>mentry::mentry</b></code>
    command returns its <code><i>pathName</i></code> argument.&nbsp; At the
    time this command is invoked, there must not exist a window named
    <code><i>pathName</i></code>, but <code><i>pathName</i></code>'s parent
    must exist.</dd>

    <dd class="tm">The word <i>mentry</i> is an abbreviation of
    <i>multi-entry</i>.&nbsp; A mentry is a mega-widget consisting of any
    number of entries separated by labels, all embedded in a frame.&nbsp; Due
    to appropriately chosen configuration options for the entries and labels, a
    mentry widget looks like one single entry containing preinserted text
    pieces that cannot be moved, changed, or deleted by the user.</dd>

    <dd class="tm">The initial width of each entry child (specified by the
    <code><b><a href="#body">-body</a></b></code> configuration option) also
    determines the maximal number of characters that can be inserted into
    it.&nbsp; This is achieved with the aid of the <code><b><a href=
    "wcbRef.html#callback">wcb::callback</a></b></code> command, by registering
    the <code><b><a href=
    "wcbRef.html#entrycb">wcb::checkEntryLen</a></b></code>
    before-<code><b>insert</b></code> callback with the entry child.&nbsp; In
    order to keep this callback, additional before-<code><b>insert</b></code>
    callbacks (if needed) should only be registered with the <code><b><a href=
    "wcbRef.html#cbappend">wcb::cbappend</a></b></code> and <code><b><a href=
    "wcbRef.html#cbprepend">wcb::cbprepend</a></b></code> commands.&nbsp; When
    reaching this limit in an entry having the input focus, the latter is set
    automatically to the next enabled entry child, the contents of that widget
    is selected, and the insertion cursor is set to its end.&nbsp; This is made
    sure by defining an appropriate after-<code><b>insert</b></code> callback,
    which must be kept to be the last such callback for the entry.&nbsp; For
    this reason, additional after-<code><b>insert</b></code> callbacks (if
    needed) should only be registered with the
    <code><b>wcb::cbprepend</b></code> command.&nbsp; The same command should
    be used exclusively to define after-<code><b>motion</b></code> callbacks
    (if needed), because <code><b>mentry::mentry</b></code> registers one that
    must be the last after-<code><b>motion</b></code> callback for each entry
    child.</dd>

    <dd class="tm">Each mentry widget may have any number of <b>attributes</b>,
    which can be used in commands that create or manipulate mentry widgets for
    particular purposes.&nbsp; For example, each date mentry created by the
    <code><b><a href=
    "mentryDateTime.html#dateMentry">mentry::dateMentry</a></b></code> command
    has a <code><b>type</b></code> attribute having the value
    <code>"Date"</code> and a <code><b>format</b></code> attribute specifying
    the meanings of its components.&nbsp; The values of these attributes are
    queried and used in the bodies of the procedures <code><b><a href=
    "mentryDateTime.html#putClockVal">mentry::putClockVal</a></b></code> and
    <code><b><a href=
    "mentryDateTime.html#getClockVal">mentry::getClockVal</a></b></code>.</dd>

    <dt class="tm" id="std_options"><b>STANDARD OPTIONS</b></dt>

    <dd>
      <pre>
<b>-borderwidth          -highlightcolor      -relief
-highlightbackground  -highlightthickness</b>
</pre>
    </dd>

    <dd>See the <b>options</b> manual entry for details on the standard Tk
    widget options.&nbsp; These options are only supported by the Mentry
    package, but not by Mentry_tile.</dd>

    <dt class="tm" id="child_options"><b>OPTIONS FOR ALL ENTRY AND LABEL
    CHILDREN</b></dt>

    <dd>
      <pre>
<b>-background  -cursor  -font  -foreground</b>
</pre>
    </dd>

    <dd>These options (described in the <b>options</b> manual entry) specify
    the values of the options of the same names for all entry and label
    children of the given multi-entry widget.&nbsp; These values may be changed
    for an individual child by using the <code><b>configure</b></code>
    subcommand of the Tcl command corresponding to that child.&nbsp; However,
    applying this method to change the font of an entry child of a tile-based
    mentry widget might break the latter's appearance (this has tile-related
    technical reasons).&nbsp; To avoid this problem, it is recommended to use
    the <code><b><a href="#setentryfont">setentryfont</a></b></code> subcommand
    of the Tcl command associated with the mentry widget for changing the value
    of the <code><b>-font</b></code> option of one of its entry children.</dd>

    <dd class="tm">When using the package Mentry_tile, these options have
    theme-specific default values.&nbsp; The common abbreviations
    <code><b>-bg</b></code> (for <code><b>-background</b></code>) and
    <code><b>-fg</b></code> (for <code><b>-foreground</b></code>) are supported
    for both classical and tile-based mentry widgets.</dd>

    <dd class="tm"><b>REMARK:</b>&nbsp; Please take into account that for some
    themes (like <code><b>Arc</b></code>, <code><b>plastik</b></code>,
    <code><b>tileqt</b></code>, <code><b>vista</b></code>, and
    <code><b>xpnative</b></code>), the <code><b>-background</b></code> option
    will be ignored for the entry children of a tile-based mentry widget.</dd>

    <dt class="tm" id="entry_options"><b>OPTIONS FOR ALL ENTRY
    CHILDREN</b></dt>

    <dd>
      <pre>
<b>-exportselection    -insertwidth        -selectforeground
-insertbackground   -invalidcommand     -show
-insertborderwidth  -justify            -state
-insertofftime      -selectbackground   -validate
-insertontime       -selectborderwidth  -validatecommand</b>
</pre>
    </dd>

    <dd>These options specify the values of the options of the same names for
    all entry children of the given multi-entry widget.&nbsp; These values may
    be changed for an individual entry child by using the
    <code><b>configure</b></code> subcommand of the Tcl command corresponding
    to that entry.&nbsp; The <code><b>-invalidcommand</b></code>,
    <code><b>-validate</b></code>, and <code><b>-validatecommand</b></code>
    options are only supported if Tk version 8.3 or higher is used, because the
    options of the same names for entry widgets were introduced in Tk
    8.3.&nbsp; The options <code><b>-insertbackground</b></code>,
    <code><b>-insertborderwidth</b></code>, <code><b>-insertofftime</b></code>,
    <code><b>-insertontime</b></code>, <code><b>-insertwidth</b></code>,
    <code><b>-selectbackground</b></code>,
    <code><b>-selectborderwidth</b></code>, and
    <code><b>-selectforeground</b></code> are only supported by the Mentry
    package, but not by Mentry_tile.&nbsp; The common abbreviations
    <code><b>-invcmd</b></code> (for <code><b>-invalidcommand</b></code>) and
    <code><b>-vcmd</b></code> (for <code><b>-validatecommand</b></code>) are
    supported for both classical and tile-based mentry widgets.</dd>

    <dt class="tm" id="widget_options"><b>WIDGET-SPECIFIC OPTIONS</b></dt>

    <dd class="tm" id="body">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
          <td><code><b>-body</b></code></td>
        </tr>

        <tr>
          <td>Database Name:</td>
          <td><code><b>&nbsp;body</b></code></td>
        </tr>

        <tr>
          <td>Database Class:</td>
          <td><code><b>&nbsp;Body</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>Specifies the initial widths of the entry children of the given
        multi-entry widget, as well as the texts to be displayed in the labels
        separating the entries.&nbsp; The value of this option is viewed as a
        list.&nbsp; Each odd-numbered element is interpreted as the value of
        the <code><b>-width</b></code> configuration option of an entry child,
        while each even-numbered element represents the value of the
        <code><b>-text</b></code> configuration option of a label child.&nbsp;
        That is, each entry width must be followed by a label text, except for
        the last one, for which a corresponding label text is optional.&nbsp;
        The order of the list elements determines the creation order of the
        child widgets; these will be packed in a row, without any horizontal
        padding.&nbsp; The initial width of each entry child also determines
        the number of characters that can be inserted into it; this maximal
        length remains unchanged even if the entry's width is set to a new
        value later on.</p>

        <p>The width of an entry child and the text displayed in a label may be
        changed by using the <code><b>configure</b></code> subcommand of the
        Tcl command corresponding to that child.&nbsp; However, applying this
        method to change the width of of an entry child of a tile-based mentry
        widget might break the latter's appearance (this has tile-related
        technical reasons).&nbsp; To avoid this problem, it is recommended to
        use the <code><b><a href="#setentrywidth">setentrywidth</a></b></code>
        subcommand of the Tcl command associated with the mentry widget for
        changing the value of the <code><b>-width</b></code> option of one of
        its entry children.</p>
      </blockquote>
    </dd>

    <dd id="disabledbackground">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
          <td><code><b>-disabledbackground</b></code></td>
        </tr>

        <tr>
          <td>Database Name:</td>
          <td><code><b>&nbsp;disabledBackground</b></code></td>
        </tr>

        <tr>
          <td>Database Class:</td>
          <td><code><b>&nbsp;DisabledBackground</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>This option, which is only supported for Tk versions 8.4 or higher,
        specifies the background color to use for all entry and label children
        of the given multi-entry widget when it is disabled.&nbsp; If the value
        of this option is the empty string then the normal background color is
        used.&nbsp; This option is only supported by the Mentry package, but
        not by Mentry_tile.</p>
      </blockquote>
    </dd>

    <dd id="disabledforeground">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
          <td><code><b>-disabledforeground</b></code></td>
        </tr>

        <tr>
          <td>Database Name:</td>
          <td><code><b>&nbsp;disabledForeground</b></code></td>
        </tr>

        <tr>
          <td>Database Class:</td>
          <td><code><b>&nbsp;DisabledForeground</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>This option, which is only supported for Tk versions 8.4 or higher,
        specifies the foreground color to use for all entry and label children
        of the given multi-entry widget when it is disabled.&nbsp; If the value
        of this option is the empty string then the normal foreground color is
        used.&nbsp; This option is only supported by the Mentry package, but
        not by Mentry_tile.</p>
      </blockquote>
    </dd>

    <dd id="readonlybackground">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
          <td><code><b>-readonlybackground</b></code></td>
        </tr>

        <tr>
          <td>Database Name:</td>
          <td><code><b>&nbsp;readonlyBackground</b></code></td>
        </tr>

        <tr>
          <td>Database Class:</td>
          <td><code><b>&nbsp;ReadonlyBackground</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>This option, which is only supported for Tk versions 8.4 or higher,
        specifies the background color to use for all entry and label children
        of the given multi-entry widget when it is readonly.&nbsp; If the value
        of this option is the empty string then the normal background color is
        used.&nbsp; This option is only supported by the Mentry package, but
        not by Mentry_tile.</p>
      </blockquote>
    </dd>

    <dd id="takefocus">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
          <td><code><b>-takefocus</b></code></td>
        </tr>

        <tr>
          <td>Database Name:</td>
          <td><code><b>&nbsp;takeFocus</b></code></td>
        </tr>

        <tr>
          <td>Database Class:</td>
          <td><code><b>&nbsp;TakeFocus</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>This option determines whether the widget accepts the focus during
        keyboard traversal.&nbsp; It is almost identical to the standard option
        of the same name (see the <b>options</b> manual entry for
        details).&nbsp; The only difference is that not the widget itself but
        its first enabled entry child will receive the focus during keyboard
        traversal with the standard keys (<code>Tab</code> and
        <code>Shift-Tab</code>).&nbsp; See the <a href="#bindings">DEFAULT
        BINDINGS</a> section below for information on how to move the focus
        from one entry child to another using the keyboard.</p>
      </blockquote>
    </dd>

    <dd id="textvariable">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
          <td><code><b>-textvariable</b></code></td>
        </tr>

        <tr>
          <td>Database Name:</td>
          <td><code><b>&nbsp;textvariable</b></code></td>
        </tr>

        <tr>
          <td>Database Class:</td>
          <td><code><b>&nbsp;Variable</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>If the value of this option is not an empty string then it must be
        an array.&nbsp; In this case, for each entry child of the given
        multi-entry widget the value of the array element with the index of the
        entry as element name specifies the value of the
        <code><b>-textvariable</b></code> option for that entry.&nbsp; The
        entry indices start with <code>0</code>.&nbsp; For example,
        specifying&nbsp; <code>-textvariable arr</code>&nbsp; for a multi-entry
        widget having two entry children is equivalent to specifying&nbsp;
        <code>-textvariable arr(0)</code>&nbsp; for the first and&nbsp;
        <code>-textvariable arr(1)</code>&nbsp; for the second entry child of
        that widget.</p>
      </blockquote>
    </dd>

    <dt id="indices"><b>INDICES</b></dt>

    <dd>Some of the widget commands for mentries take an index as
    argument.&nbsp; An index specifies a particular entry or label child of the
    mentry, in any of the following ways:</dd>

    <dd class="tm">
      <table border="0" cellpadding="6" cellspacing="0">
        <tr valign="top">
          <td><code><i>number&nbsp;&nbsp;</i></code></td>
          <td>Specifies the child as a numerical index, where <code>0</code>
          corresponds to the first entry or label child.</td>
        </tr>

        <tr valign="top">
          <td><code><b>end</b></code></td>
          <td>Indicates the last entry or label child of the mentry.</td>
        </tr>
      </table>
    </dd>

    <dd class="tm">The word <code><b>end</b></code> can be abbreviated as
    <code><b>en</b></code> or <code><b>e</b></code>.&nbsp; Out-of-range indices
    are automatically rounded to the nearest legal value.</dd>

    <dt class="tm" id="widget_command"><b>WIDGET COMMAND</b></dt>

    <dd>
      The <code><b>mentry::mentry</b></code> command creates a new Tcl command
      whose name is <code><i>pathName</i></code>.&nbsp; This command may be
      used to invoke various operations on the widget.&nbsp; It has the
      following general form:

      <blockquote>
        <pre>
<i>pathName</i> <i>option</i> ?<i>arg</i> <i>arg</i> ...?
</pre>
      </blockquote>
    </dd>

    <dd><code><i>option</i></code> and the <code><i>arg</i></code>s determine
    the exact behavior of the command.&nbsp; The following commands are
    possible for mentry widgets:</dd>

    <dd>
      <dl>
        <dt class="tm" id="adjustentry"><code><i>pathName</i>
        <b>adjustentry</b> <i>index</i> <i>string</i></code></dt>

        <dd>Increases the width in pixels of the entry child identified by
        <code><i>index</i></code> if needed, to make it just large enough for
        texts of the child-specific maximal length, consisting of characters
        contained in the <code><i>string</i></code> argument.&nbsp; Returns an
        empty string.</dd>

        <dd class="tm">For example, when constructing a mentry widget whose
        components will accept up to two uppercase hexadecimal digits only, by
        passing the string <code>"0123456789ABCDEF"</code> to this subcommand
        you can make sure that the entry children will have optimal widths,
        just large enough to display not only the decimal digits, but also up
        to two letters in the range <code>A</code> - <code>F</code> (which need
        more room than the decimal digits when using a proportionally-spaced
        font).&nbsp; It is recommended to invoke this subcommand even if the
        allowed characters are restricted to the digits <code>0</code> -
        <code>9</code> only, because in some fonts not all decimal digits have
        the same width.</dd>

        <dt class="tm" id="attrib"><code><i>pathName</i> <b>attrib</b>
        ?<i>name</i>? ?<i>value</i> <i>name</i> <i>value</i> ...?</code></dt>

        <dd>Queries or modifies the attributes of the widget.&nbsp; If no
        <code><i>name</i></code> is specified, the command returns a list of
        pairs, each of which contains the name and the value of an attribute
        for <code><i>pathName</i></code>.&nbsp; If <code><i>name</i></code> is
        specified with no <code><i>value</i></code>, then the command returns
        the value of the one named attribute, or an empty string if no
        corresponding value exists (you can use the <code><b><a href=
        "#hasattrib">hasattrib</a></b></code> subcommand to distinguish this
        case from the one that the value of an <i>existing</i> attribute is an
        empty string).&nbsp; If one or more
        <code><i>name</i></code>-<code><i>value</i></code> pairs are specified,
        then the command sets the given widget attribute(s) to the given
        value(s); in this case the return value is an empty string.&nbsp;
        <code><i>name</i></code> may be an arbitrary string.</dd>

        <dt class="tm" id="cget"><code><i>pathName</i> <b>cget</b>
        <i>option</i></code></dt>

        <dd>Returns the current value of the configuration option given by
        <code><i>option</i></code>, which may have any of the values accepted
        by the <code><b>mentry::mentry</b></code> command.</dd>

        <dt class="tm" id="clear"><code><i>pathName</i> <b>clear</b>
        <i>first</i> ?<i>last</i>?</code></dt>

        <dd>Erases the contents of one or more entry children of the
        widget.&nbsp; <code><i>first</i></code> and <code><i>last</i></code>
        are indices specifying the first and last entries in the range to
        clear.&nbsp; If <code><i>last</i></code> is not specified then it
        defaults to <code><i>first</i></code>, i.e., a single entry child is
        cleared.&nbsp; The return value is an empty string.</dd>

        <dt class="tm" id="configure"><code><i>pathName</i> <b>configure</b>
        ?<i>option</i>? ?<i>value</i> <i>option</i> <i>value</i>
        ...?</code></dt>

        <dd>Queries or modifies the configuration options of the widget.&nbsp;
        If no <code><i>option</i></code> is specified, the command returns a
        list describing all of the available options for
        <code><i>pathName</i></code> (see <code><b>Tk_ConfigureInfo</b></code>
        for information on the format of this list).&nbsp; If
        <code><i>option</i></code> is specified with no
        <code><i>value</i></code>, 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 <code><i>option</i></code> is
        specified).&nbsp; If one or more
        <code><i>option</i></code>-<code><i>value</i></code> 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.&nbsp; <code><i>option</i></code> may have any of the values
        accepted by the <code><b>mentry::mentry</b></code> command.</dd>

        <dt class="tm" id="entries"><code><i>pathName</i>
        <b>entries</b></code></dt>

        <dd>Returns a list containing the path names of all entry children of
        the widget.</dd>

        <dt class="tm" id="entrycount"><code><i>pathName</i>
        <b>entrycount</b></code></dt>

        <dd>Returns the number of all entry children of the widget.</dd>

        <dt class="tm" id="entrylimit"><code><i>pathName</i> <b>entrylimit</b>
        <i>index</i></code></dt>

        <dd>Returns the number of characters that can be inserted into the
        entry child identfied by <code><i>index</i></code>.</dd>

        <dt class="tm" id="entrypath"><code><i>pathName</i> <b>entrypath</b>
        <i>index</i></code></dt>

        <dd>Returns the path name of the entry child identfied by
        <code><i>index</i></code>.</dd>

        <dt class="tm" id="getarray"><code><i>pathName</i> <b>getarray</b>
        <i>array</i></code></dt>

        <dd>For each entry child of the widget, the command assigns the string
        contained in the entry to the element of <code><i>array</i></code>
        having the index of the entry as element name.&nbsp; The entry indices
        start with <code>0</code>.&nbsp; The return value is an empty
        string.</dd>

        <dt class="tm" id="getlist"><code><i>pathName</i>
        <b>getlist</b></code></dt>

        <dd>Returns a list containing the strings of all entry children of the
        widget.</dd>

        <dt class="tm" id="getstring"><code><i>pathName</i>
        <b>getstring</b></code></dt>

        <dd>Returns a string built by concatenating the strings contained in
        the entry children of the widget with the texts displayed in the labels
        separating the entries, in the creation order of the children, as given
        by the <code><b><a href="#body">-body</a></b></code> configuration
        option.&nbsp; That is, the string of the first entry child is followed
        by the text of the first label, which in turn is followed by the string
        of the second entry, and so on.</dd>

        <dt class="tm" id="hasattrib"><code><i>pathName</i> <b>hasattrib</b>
        <i>name</i></code></dt>

        <dd>Returns <code>1</code> if the attribute <code><i>name</i></code>
        exists and <code>0</code> otherwise.</dd>

        <dt class="tm" id="isempty"><code><i>pathName</i> <b>isempty</b>
        ?<i>index</i>?</code></dt>

        <dd>If <code><i>index</i></code> is specified then the command returns
        the value <code>1</code> if the string contained in the entry child
        identfied by <code><i>index</i></code> is empty and <code>0</code>
        otherwise.&nbsp; If this optional argument is not present then the
        command returns the value <code>1</code> if the strings contained in
        the entry children of the widget are all empty and <code>0</code>
        otherwise.</dd>

        <dt class="tm" id="isfull"><code><i>pathName</i> <b>isfull</b>
        ?<i>index</i>?</code></dt>

        <dd>If <code><i>index</i></code> is specified then the command returns
        the value <code>1</code> if the length of the string contained in the
        entry child identfied by <code><i>index</i></code> equals the number of
        characters that can be inserted into the entry and <code>0</code>
        otherwise.&nbsp; If this optional argument is not present then the
        command returns the value <code>1</code> if the lengths of the strings
        contained in the entry children of the widget all equal the numbers of
        characters that can be inserted into the respective entries (i.e., if
        all entry children are full) and <code>0</code> otherwise.</dd>

        <dt class="tm" id="labelcount"><code><i>pathName</i>
        <b>labelcount</b></code></dt>

        <dd>Returns the number of all label children of the widget.</dd>

        <dt class="tm" id="labelpath"><code><i>pathName</i> <b>labelpath</b>
        <i>index</i></code></dt>

        <dd>Returns the path name of the label child identfied by
        <code><i>index</i></code>.</dd>

        <dt class="tm" id="labels"><code><i>pathName</i>
        <b>labels</b></code></dt>

        <dd>Returns a list containing the path names of all label children of
        the widget.</dd>

        <dt class="tm" id="put"><code><i>pathName</i> <b>put</b>
        <i>startIndex</i> ?<i>string</i> <i>string</i> ...?</code></dt>

        <dd>Replaces the texts of the entry children whose indices are greater
        than or equal to <code><i>startIndex</i></code> with the corresponding
        <code><i>string</i></code> arguments by using the
        <code><b>delete</b></code> and <code><b>insert</b></code> operations,
        until either the entries or the <code><i>string</i></code>s are
        consumed.&nbsp; If one of these subcommands gets canceled by some
        before-callback in any entry child then the command restores the
        original contents of all affected entries and returns the value
        <code>0</code>, otherwise it returns <code>1</code>.&nbsp; In both
        cases, the command keeps the position of the insertion cursor in all
        entry children.</dd>

        <dt class="tm" id="setentryextrawidth"><code><i>pathName</i>
        <b>setentryextrawidth</b> <i>index</i> <i>amount</i></code></dt>

        <dd>Specifies additonal width to provide for the entry child identified
        by <code><i>index</i></code>.&nbsp; <code><i>amount</i></code> may have
        any of the standard forms for screen distances (e.g., a number of
        pixels).&nbsp; The return value is an empty string.</dd>

        <dd class="tm">Notice that changing the width of an entry child has no
        impact on the number of characters that can be inserted into it, which
        remains set to the corresponding component of the value of the mentry's
        <code><b><a href="#body">-body</a></b></code> option.</dd>

        <dt class="tm" id="setentryfont"><code><i>pathName</i>
        <b>setentryfont</b> <i>index</i> <i>font</i></code></dt>

        <dd>Sets the font of the entry child identified by
        <code><i>index</i></code> to the value given by
        <code><i>font</i></code>.&nbsp; This is done by invoking the
        <code><b>configure</b></code> subcommand of the Tcl command
        corresponding to the entry.&nbsp; When using the package Mentry_tile,
        this command also performs some additional steps necessary for updating
        the appearance of the tile-based mentry widget.&nbsp; The return value
        is an empty string.</dd>

        <dt class="tm" id="setentrywidth"><code><i>pathName</i>
        <b>setentrywidth</b> <i>index</i> <i>width</i></code></dt>

        <dd>Sets the width of the entry child identified by
        <code><i>index</i></code> to the number of characters given by
        <code><i>width</i></code>.&nbsp; This is done by invoking the
        <code><b>configure</b></code> subcommand of the Tcl command
        corresponding to the entry.&nbsp; When using the package Mentry_tile,
        this command also performs some additional steps necessary for updating
        the appearance of the tile-based mentry widget.&nbsp; The return value
        is an empty string.</dd>

        <dd class="tm">Notice that changing the width of an entry child has no
        impact on the number of characters that can be inserted into it, which
        remains set to the corresponding component of the value of the mentry's
        <code><b><a href="#body">-body</a></b></code> option.</dd>

        <dt class="tm" id="unsetattrib"><code><i>pathName</i>
        <b>unsetattrib</b> <i>name</i></code></dt>

        <dd>Unsets the attribute <code><i>name</i></code>.&nbsp; Returns an
        empty string.</dd>
      </dl>
    </dd>

    <dt class="tm" id="bindings"><b>DEFAULT BINDINGS</b></dt>

    <dd>The <code><b>mentry::mentry</b></code> command partially redefines the
    bindings of the children of the mentry widget it creates:</dd>

    <dd>
      <ol>
        <li class="tm">Clicking mouse button 1 in a label child positions the
        insertion cursor to the end of the last enabled entry preceding the
        label, sets the input focus to that entry, and clears any selection in
        it.</li>

        <li class="tm">If in a non-empty entry child a character is typed that
        is contained in the label following that entry (if any), then the focus
        is moved to the next enabled entry child, the contents of that entry
        are selected, and the insertion cursor is set to its end.</li>

        <li class="tm">At the beginning of an entry child that is not the first
        enabled entry within the widget, the <code>Left</code> key clears the
        selection in that entry, moves the focus to the previous enabled entry
        child, and sets the insertion cursor to the end of that widget.&nbsp;
        Similarly, at the end of an entry child that is not the last enabled
        entry within the widget, the <code>Right</code> key clears the
        selection in that entry, moves the focus to the next enabled entry
        child, and sets the insertion cursor to the beginning of that
        widget.&nbsp; If <code><b>tk_strictMotif</b></code> is false then
        <code>Control-b</code> and <code>Control-f</code> behave the same as
        <code>Left</code> and <code>Right</code>, respectively.</li>

        <li class="tm">In an entry child that is not the first enabled entry
        within the widget, <code>Control-Left</code> moves the focus to the
        previous enabled entry child, selects the contents of that widget, and
        sets the insertion cursor to its end; if there is no enabled entry
        child to the left of the current one then <code>Control-Left</code>
        moves the insertion cursor to the beginning of the current entry and
        clears the selection in that widget.&nbsp; Similarly, in an entry child
        that is not the last enabled entry within the widget,
        <code>Control-Right</code> moves the focus to the next enabled entry
        child, selects the contents of that widget, and sets the insertion
        cursor to its end; if there is no enabled entry child to the right of
        the current one then <code>Control-Right</code> moves the insertion
        cursor to the end of the current entry and clears the selection in that
        widget.&nbsp; If <code><b>tk_strictMotif</b></code> is false then
        <code>Meta-b</code> and <code>Meta-f</code> behave the same as
        <code>Control-Left</code> and <code>Control-Right</code>,
        respectively.</li>

        <li class="tm">The <code>Home</code> key clears the selection in the
        current entry widget, moves the focus to the first enabled entry child,
        and sets the insertion cursor to the beginning of that widget.&nbsp;
        Similarly, the <code>End</code> key clears the selection in the current
        entry widget, moves the focus to the last enabled entry child, and sets
        the insertion cursor to the end of that widget.&nbsp; If
        <code><b>tk_strictMotif</b></code> is false then <code>Control-a</code>
        and <code>Control-e</code> behave the same as <code>Home</code> and
        <code>End</code>, respectively.</li>

        <li class="tm"><code>Shift-Home</code> moves the focus to the first
        enabled entry child, sets the insertion cursor to the beginning of that
        widget, and either extends the selection to that position, or clears
        the selection in the current entry and selects the contents of the new
        widget, depending upon whether the current entry is the first enabled
        entry child or not.&nbsp; Similarly, <code>Shift-End</code> moves the
        focus to the last enabled entry child, sets the insertion cursor to the
        end of that widget, and either extends the selection to that position,
        or clears the selection in the current entry and selects the contents
        of the new widget, depending upon whether the current entry is the last
        enabled entry child or not.</li>

        <li class="tm">The <code>BackSpace</code> key deletes the selection if
        there is one in the current entry.&nbsp; Otherwise, it deletes either
        the character to the left of the insertion cursor in the current entry,
        or the last character of the previous enabled entry child.&nbsp; The
        latter takes place at the beginning of an entry child that is not the
        first enabled entry within the widget; in this case, the
        <code>BackSpace</code> key also moves the focus to the previous enabled
        entry child and sets the insertion cursor to its end.&nbsp; If
        <code><b>tk_strictMotif</b></code> is false then <code>Control-h</code>
        behaves the same as <code>BackSpace</code>.</li>

        <li class="tm">If <code><b>tk_strictMotif</b></code> is false then
        <code>Meta-d</code> deletes all characters to the right of the
        insertion cursor within the current entry, while
        <code>Meta-BackSpace</code> and <code>Meta-Delete</code> delete either
        all characters to the left of the insertion cursor in the current
        entry, or the contents of the previous enabled entry child.&nbsp; The
        latter takes place at the beginning of an entry child that is not the
        first enabled entry within the widget; in this case,
        <code>Meta-BackSpace</code> and <code>Meta-Delete</code> also clear the
        selection in the current entry widget and move the focus to the
        previous enabled entry child.</li>
      </ol>
    </dd>

    <dt class="tm" id="keywords"><b>KEYWORDS</b></dt>

    <dd>mentry, widget, entry, label</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>
</body>
</html>

/* generic class defining a top margin whose height equals the font size */
.tm {margin-top: 1em}

/* background, border, and padding for the <pre> tag */
pre {background: #F7F7F7; border: silver solid 1px; padding: 1px}

/* background for the <body> tag */
body {background: #FFFFFF}

/* color for the <span> tag */
span.red {color: #E00000}
span.cmt {color: #36648b}

<!DOCTYPE html>
<html>
<head>
  <title>Wcb Command Reference</title>

  <meta name="Author" content="Csaba Nemethi">
  <meta name="Keywords" content=
  "callback, widget, Tk entry, tile entry, BWidget Entry, Tk spinbox, tile spinbox, tile combobox, listbox, tablelist, tile treeview, text, ctext">

  <link rel="stylesheet" type="text/css" href="stylesheet.css">
</head>

<body>
  <div align="center">
    <h1>Wcb Command Reference</h1>

    <h2>For Wcb Version 3.6</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:csaba.nemethi@t-online.de">csaba.nemethi@t-online.de</a>
    </address>
  </div>

  <hr>

  <h2 id="contents">Contents</h2>

  <ul>
    <li><a href="#callback">The <code><b>wcb::callback</b></code>
    Command</a></li>

    <li><a href="#cbappend">The <code><b>wcb::cbappend</b></code>
    Command</a></li>

    <li><a href="#cbprepend">The <code><b>wcb::cbprepend</b></code>
    Command</a></li>

    <li><a href="#cancel">The <code><b>wcb::cancel</b></code> Command</a></li>

    <li><a href="#canceled">The <code><b>wcb::canceled</b></code>
    Command</a></li>

    <li><a href="#extend">The <code><b>wcb::extend</b></code> Command</a></li>

    <li><a href="#replace">The <code><b>wcb::replace</b></code>
    Command</a></li>

    <li><a href="#pathname">The <code><b>wcb::pathname</b></code>
    Command</a></li>

    <li><a href="#changeEntryText">The <code><b>wcb::changeEntryText</b></code>
    Command</a></li>

    <li><a href="#postInsertEntryLen">The
    <code><b>wcb::postInsertEntryLen</b></code> Command</a></li>

    <li><a href="#postInsertEntryText">The
    <code><b>wcb::postInsertEntryText</b></code> Command</a></li>

    <li><a href="#postDeleteEntryText">The
    <code><b>wcb::postDeleteEntryText</b></code> Command</a></li>

    <li><a href="#entrycb">Before-<code><b>insert</b></code> Callbacks for
    entry, spinbox, and combobox Widgets</a></li>

    <li><a href="#textcb">Before-<code><b>insert</b></code> Callbacks for text
    and ctext Widgets</a></li>
  </ul>

  <div align="center">
    <p><a href="index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="callback">The <code><b>wcb::callback</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>wcb::callback</code> &ndash; Retrieve, set, and remove widget
    callbacks</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>wcb::callback</b> <i>widgetName</i> <b>before</b>|<b>after</b> <i>option</i> ?<i>callback</i> <i>callback</i> ...?
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>Retrieves, sets, or removes the callbacks for the Tk or tile entry,
    BWidget Entry, Tk or tile spinbox, tile combobox, listbox, tablelist, tile
    treeview, text, or ctext widget <code><i>widgetName</i></code>, the
    argument <code><b>before</b></code> or <code><b>after</b></code>, and the
    command corresponding to <code><i>option</i></code>.&nbsp; The values of
    the <code><i>option</i></code> argument can be:</dd>

    <dd class="tm">
      <ul>
        <li><code><b>insert</b></code>, <code><b>delete</b></code>, or
        <code><b>motion</b></code>, for a Tk or tile entry, BWidget Entry, Tk
        or tile spinbox, tile combobox, text, or ctext widget;</li>

        <li><code><b>replace</b></code>, for a text or ctext widget;</li>

        <li><code><b>activate</b></code>, for a listbox, tablelist, or tile
        treeview widget;</li>

        <li><code><b>selset</b></code> or <code><b>selclear</b></code>, for a
        listbox, tablelist, tile treeview, text, or ctext widget;</li>

        <li><code><b>seladd</b></code> or <code><b>seltoggle</b></code>, for a
        tile treeview widget;</li>

        <li><code><b>activatecell</b></code>, <code><b>cellselset</b></code>,
        or <code><b>cellselclear</b></code>, for a tablelist widget.</li>
      </ul>
    </dd>

    <dd class="tm">If no arguments after the <code><i>option</i></code>
    parameter are specified, then the procedure just returns the current
    before- or after-callback list, respectively, for the given widget
    operation.</dd>

    <dd class="tm">Otherwise:</dd>

    <dd>
      <ul>
        <li>
          <p>If at least one of the arguments following the
          <code><i>option</i></code> parameter is a nonempty string, then:</p>

          <ul>
            <li>if called for the first time for this widget with at least one
            nonempty argument following the <code><i>option</i></code>
            parameter, then the procedure renames the Tcl command
            <code><i>widgetName</i></code> to <code>_<i>widgetName</i></code>
            and builds a new procedure <code><i>widgetName</i></code>, in which
            the execution of the widget operations associated with the above
            values of <code><i>option</i></code> is preceded by invocations of
            the corresponding before-callbacks and followed by calls to the
            corresponding after-callbacks, in the global scope;</li>

            <li class="tm">it sets the callback list to the one built from
            these arguments and returns the new list.</li>
          </ul>
        </li>

        <li class="tm">If all arguments following the
        <code><i>option</i></code> parameter are empty, then the procedure
        unregisters all the corresponding before- or after-callbacks for the
        given widget and returns an empty string.</li>
      </ul>
    </dd>

    <dd class="tm">When a callback is invoked, the name of the original Tcl
    command for the widget <code><i>widgetName</i></code> as well as the
    command arguments are automatically appended to it as parameters.</dd>

    <dd class="tm">The following table shows the widget subcommands
    corresponding to the above values of <code><i>option</i></code>, together
    with the arguments of these subcommands:</dd>

    <dd class="tm" id="callback_table">
      <table border="2" cellspacing="0" cellpadding="3">
        <tr bgcolor="#FFFFE0">
          <th align="left">Widget</th>

          <th align="left"><code><i>option</i></code></th>

          <th align="left">Subcommand</th>

          <th align="left">Arguments</th>
        </tr>

        <tr>
          <td rowspan="3">Tk entry, ttk::entry,<br>
          BWidget Entry,<br>
          Tk spinbox, ttk::spinbox,<br>
          or ttk::combobox</td>

          <td><code><b>insert</b></code></td>

          <td><code><b>insert</b></code></td>

          <td><code><i>index</i> <i>string</i></code></td>
        </tr>

        <tr>
          <td><code><b>delete</b></code></td>

          <td><code><b>delete</b></code></td>

          <td><code><i>from</i> ?<i>to</i>?</code></td>
        </tr>

        <tr>
          <td><code><b>motion</b></code></td>

          <td><code><b>icursor</b></code></td>

          <td><code><i>index</i></code></td>
        </tr>

        <tr>
          <td rowspan="3">listbox</td>

          <td><code><b>activate</b></code></td>

          <td><code><b>activate</b></code></td>

          <td><code><i>index</i></code></td>
        </tr>

        <tr>
          <td><code><b>selset</b></code></td>

          <td><code><b>selection set</b></code></td>

          <td><code><i>first</i> ?<i>last</i>?</code></td>
        </tr>

        <tr>
          <td><code><b>selclear</b></code></td>

          <td><code><b>selection clear</b></code></td>

          <td><code><i>first</i> ?<i>last</i>?</code></td>
        </tr>

        <tr>
          <td rowspan="6">tablelist::tablelist</td>

          <td><code><b>activate</b></code></td>

          <td><code><b>activate</b></code></td>

          <td><code><i>index</i></code></td>
        </tr>

        <tr>
          <td><code><b>selset</b></code></td>

          <td><code><b>selection set</b></code></td>

          <td><code><i>first</i> ?<i>last</i>?</code></td>
        </tr>

        <tr>
          <td><code><b>selclear</b></code></td>

          <td><code><b>selection clear</b></code></td>

          <td><code><i>first</i> ?<i>last</i>?</code></td>
        </tr>

        <tr>
          <td><code><b>activatecell</b></code></td>

          <td><code><b>activatecell</b></code></td>

          <td><code><i>cellIndex</i></code></td>
        </tr>

        <tr>
          <td><code><b>cellselset</b></code></td>

          <td><code><b>cellselection set</b></code></td>

          <td><code><i>first</i> ?<i>last</i>?</code></td>
        </tr>

        <tr>
          <td><code><b>cellselclear</b></code></td>

          <td><code><b>cellselection clear</b></code></td>

          <td><code><i>first</i> ?<i>last</i>?</code></td>
        </tr>

        <tr>
          <td rowspan="5">ttk::treeview</td>

          <td><code><b>activate</b></code></td>

          <td><code><b>focus</b></code></td>

          <td><code><i>item</i></code></td>
        </tr>

        <tr>
          <td><code><b>selset</b></code></td>

          <td><code><b>selection set</b></code></td>

          <td><code><i>itemList</i></code></td>
        </tr>

        <tr>
          <td><code><b>seladd</b></code></td>

          <td><code><b>selection add</b></code></td>

          <td><code><i>itemList</i></code></td>
        </tr>

        <tr>
          <td><code><b>selclear</b></code></td>

          <td><code><b>selection remove</b></code></td>

          <td><code><i>itemList</i></code></td>
        </tr>

        <tr>
          <td><code><b>seltoggle</b></code></td>

          <td><code><b>selection toggle</b></code></td>

          <td><code><i>itemList</i></code></td>
        </tr>

        <tr>
          <td rowspan="6">text or ctext</td>

          <td><code><b>insert</b></code></td>

          <td><code><b>insert</b></code></td>

          <td><code><i>index</i> <i>string</i> ?<i>tagList</i> <i>string</i>
          <i>tagList</i> ...?</code></td>
        </tr>

        <tr>
          <td><code><b>delete</b></code></td>

          <td><code><b>delete</b></code></td>

          <td><code><i>from</i> ?<i>to</i>?</code></td>
        </tr>

        <tr>
          <td><code><b>replace</b></code></td>

          <td><code><b>replace</b></code></td>

          <td><code><i>from</i> <i>to</i> <i>string</i> ?<i>tagList</i>
          <i>string</i> <i>tagList</i> ...?</code></td>
        </tr>

        <tr>
          <td><code><b>motion</b></code></td>

          <td><code><b>mark set insert</b></code></td>

          <td><code><i>index</i></code></td>
        </tr>

        <tr>
          <td><code><b>selset</b></code></td>

          <td><code><b>tag add sel</b></code></td>

          <td><code><i>from</i> ?<i>to</i> <i>from</i> <i>to</i>
          ...?</code></td>
        </tr>

        <tr>
          <td><code><b>selclear</b></code></td>

          <td><code><b>tag remove sel</b></code></td>

          <td><code><i>from</i> ?<i>to</i> <i>from</i> <i>to</i>
          ...?</code></td>
        </tr>
      </table>
    </dd>

    <dd class="tm"><b>REMARKS:</b></dd>

    <dd class="tm">
      <ol>
        <li>You may abbreviate the words <code><b>before</b></code>,
        <code><b>after</b></code>, <code><b>insert</b></code>,
        <code><b>delete</b></code>, <code><b>replace</b></code>,
        <code><b>motion</b></code>, and <code><b>activate</b></code> (the
        latter not for tablelist widgets) to a minimum of one character.&nbsp;
        Similarly, the first four characters of the words
        <code><b>selset</b></code>, <code><b>selclear</b></code>,
        <code><b>seladd</b></code>, and <code><b>seltoggle</b></code>, the
        first eight characters of <code><b>cellselset</b></code> and
        <code><b>cellselclear</b></code>, and the first nine characters of
        <code><b>activatecell</b></code> are sufficient for Wcb to recognize
        these options.</li>

        <li class="tm">After a successful invocation of this command with at
        least one nonempty callback following the <code><i>option</i></code>
        argument, you can use either the new procedure
        <code><i>widgetName</i></code> or the original Tcl command
        <code>_<i>widgetName</i></code> to perform any valid operation on the
        widget <code><i>widgetName</i></code>.&nbsp; Use the old Tcl command
        <code>_<i>widgetName</i></code> if you want to prevent the callbacks
        from being invoked when executing the respective widget
        subcommand.</li>

        <li class="tm">When destroying a widget <code><i>widgetName</i></code>
        for which <code><b>wcb::callback</b></code> has replaced the
        corresponding Tcl command with a new procedure, the original command
        <code>_<i>widgetName</i></code> is deleted automatically by the Tcl
        interpreter (this is not true in the case of a BWidget Entry,
        tablelist, or ctext widget).&nbsp; The new widget procedure
        <code><i>widgetName</i></code> would persist, but Wcb arranges for it
        to be deleted from within a cleanup script bound to the
        <code><b>&lt;Destroy&gt;</b></code> event.&nbsp; This cleanup script is
        associated with a binding tag called <code><b>WcbCleanup</b></code>,
        which is appended to the list of binding tags of the widget the first
        time when registering some callbacks for it.&nbsp; (In the case of a
        BWidget Entry, tablelist, or ctext widget, this script also deletes the
        original Tcl command <code>_<i>widgetName</i></code>.)</li>

        <li class="tm">The cleanup script mentioned above also unregisters all
        callbacks defined for <code><i>widgetName</i></code>, thus ensuring
        that a widget with the same path created later will not inherit them
        from the widget just deleted (this can be important in some
        applications).&nbsp; For this reason, you should be careful not to
        remove <code><b>WcbCleanup</b></code> from the list of binding tags of
        the given widget!</li>
      </ol>
    </dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>callback, widget, Tk entry, tile entry, BWidget Entry, Tk spinbox, tile
    spinbox, tile combobox, listbox, tablelist, tile treeview, text, ctext</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="cbappend">The <code><b>wcb::cbappend</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>wcb::cbappend</code> &ndash; Append to a callback list</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>wcb::cbappend</b> <i>widgetName</i> <b>before</b>|<b>after</b> <i>option</i> ?<i>callback</i> <i>callback</i> ...?
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command is almost identical to <code><b><a href=
    "#callback">wcb::callback</a></b></code>.&nbsp; The only difference is that
    <code><b>wcb::cbappend</b></code> <i>appends</i> the arguments specified
    after the <code><i>option</i></code> parameter to the current callback list
    (if present), while <code><b>wcb::callback</b></code> <i>replaces</i> the
    old callbacks with these arguments.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>callback, append, widget</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="cbprepend">The <code><b>wcb::cbprepend</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>wcb::cbprepend</code> &ndash; Prepend to a callback list</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>wcb::cbprepend</b> <i>widgetName</i> <b>before</b>|<b>after</b> <i>option</i> ?<i>callback</i> <i>callback</i> ...?
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command is almost identical to <code><b><a href=
    "#callback">wcb::callback</a></b></code>.&nbsp; The only difference is that
    <code><b>wcb::cbprepend</b></code> <i>prepends</i> the arguments specified
    after the <code><i>option</i></code> parameter to the current callback list
    (if present), while <code><b>wcb::callback</b></code> <i>replaces</i> the
    old callbacks with these arguments.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>callback, prepend, widget</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="cancel">The <code><b>wcb::cancel</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>wcb::cancel</code> &ndash; Cancel a widget command</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>wcb::cancel</b> ?<i>script</i>?
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This procedure is designed to be invoked from a before-callback for a
    widget command.&nbsp; It cancels the execution of that command and of the
    remaining callbacks, and evaluates the <code><i>script</i></code> argument
    in the global scope.&nbsp; If this argument is not specified, it defaults
    to the <code><b>bell</b></code> command.</dd>

    <dd class="tm">The return value is the one obtained from
    <code><i>script</i></code> if this argument is specified and
    nonempty.&nbsp; Otherwise, the command returns an empty string.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>cancel, command, widget</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="canceled">The <code><b>wcb::canceled</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>wcb::canceled</code> &ndash; Query the canceled status of a
    widget command</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>wcb::canceled</b> <i>widgetName</i> <i>option</i>
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>Returns the value <code>1</code> if the most recent invocation of the
    widget operation corresponding to <code><i>widgetName</i></code> and
    <code><i>option</i></code> has been aborted by some before-callback by
    invoking <code><b><a href="#cancel">wcb::cancel</a></b></code>; otherwise,
    the return value is <code>0</code>.&nbsp; The arguments must fulfil the
    same restrictions as in the case of the <code><b><a href=
    "#callback">wcb::callback</a></b></code> command.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>cancel, command, widget</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="extend">The <code><b>wcb::extend</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>wcb::extend</code> &ndash; Extend the argument list of a widget
    command</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>wcb::extend</b> ?<i>arg</i> <i>arg</i> ...?
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This procedure is designed to be invoked from a before-callback for a
    widget command.&nbsp; It appends the values given in the optional
    <code><i>arg</i></code> parameters to the argument list of that
    command.&nbsp; The new argument list will be passed to the remaining
    callbacks for that command, too.</dd>

    <dd class="tm">This procedure simply passes its parameters to the
    <code><b>lappend</b></code> command, called for the argument list of the
    respective widget operation.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>extend, argument, command, widget</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="replace">The <code><b>wcb::replace</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>wcb::replace</code> &ndash; Replace arguments of a widget command
    with new ones</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>wcb::replace</b> <i>first</i> <i>last</i> ?<i>arg</i> <i>arg</i> ...?
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This procedure is designed to be invoked from a before-callback for a
    widget command.&nbsp; It replaces the arguments having the indices
    <code><i>first</i></code> through <code><i>last</i></code> of that command
    with the optional <code><i>arg</i></code> parameters.&nbsp; The new
    argument list will be passed to the remaining callbacks for that command,
    too.&nbsp; The arguments are numbered from <code>0</code> (see the <a href=
    "#callback_table">table</a> in the description of the <code><b><a href=
    "#callback">wcb::callback</a></b></code> command).</dd>

    <dd class="tm">This procedure simply passes its parameters to the
    <code><b>lreplace</b></code> command, called for the argument list of the
    respective widget operation.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>replace, argument, command, widget</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="pathname">The <code><b>wcb::pathname</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>wcb::pathname</code> &ndash; Query the path name of the widget
    corresponding to a Tcl command name</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>wcb::pathname</b> <i>origCmd</i>
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This procedure returns the path name of the widget corresponding to the
    Tcl command name <code><i>origCmd</i></code> passed to a callback.</dd>

    <dd class="tm">When a before- or after-callback for a widget is invoked,
    the name of the original Tcl command associated with that widget is
    automatically appended to it as parameter.&nbsp; This procedure can be used
    within a callback to derive the path name of the widget from the command
    name passed to the callback as argument.&nbsp; It simply returns the string
    range obtained from <code><i>origCmd</i></code> by removing the
    <code>"::_"</code> prefix.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>path name, command, widget</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="changeEntryText">The <code><b>wcb::changeEntryText</b></code>
  Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>wcb::changeEntryText</code> &ndash; Change the text of a Tk or
    tile entry, BWidget Entry, Tk or tile spinbox, or tile combobox widget</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>wcb::changeEntryText</b> <i>widgetName string</i>
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>Replaces the text of the Tk or tile entry, BWidget Entry, Tk or tile
    spinbox, or tile combobox widget <code><i>widgetName</i></code> with
    <code><i>string</i></code>, by using the <code><b>delete</b></code> and
    <code><b>insert</b></code> operations.&nbsp; If the first subcommand is
    canceled by some before-<code><b>delete</b></code> callback then the
    procedure returns without inserting the new text; if the second operation
    is canceled by some before-<code><b>insert</b></code> callback then the
    command restores the original contents of the widget.</dd>

    <dd class="tm">The procedure keeps the position of the insertion
    cursor.&nbsp; The return value is <code>1</code> on success and
    <code>0</code> on failure, i.e., if one of the attempted operations was
    canceled by some before-callback.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>Tk entry, tile entry, BWidget Entry, Tk spinbox, tile spinbox, tile
    combobox, widget</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="postInsertEntryLen">The <code><b>wcb::postInsertEntryLen</b></code>
  Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>wcb::postInsertEntryLen</code> &ndash; Query the would-be length
    of the text in a Tk or tile entry, BWidget Entry, Tk or tile spinbox, or
    tile combobox widget after text insertion</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>wcb::postInsertEntryLen</b> <i>widgetName string</i>
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>Returns the length of the text that would be contained in the Tk or
    tile entry, BWidget Entry, Tk or tile spinbox, or tile combobox widget
    <code><i>widgetName</i></code> after inserting
    <code><i>string</i></code>.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>insert, Tk entry, tile entry, BWidget Entry, Tk spinbox, tile spinbox,
    tile combobox, widget</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="postInsertEntryText">The <code><b>wcb::postInsertEntryText</b></code>
  Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>wcb::postInsertEntryText</code> &ndash; Query the would-be text
    of a Tk or tile entry, BWidget Entry, Tk or tile spinbox, or tile combobox
    widget after text insertion</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>wcb::postInsertEntryText</b> <i>widgetName index string</i>
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>Returns the text that would be contained in the Tk or tile entry,
    BWidget Entry, Tk or tile spinbox, or tile combobox widget
    <code><i>widgetName</i></code> after inserting <code><i>string</i></code>
    before the character indicated by <code><i>index</i></code>.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>insert, Tk entry, tile entry, BWidget Entry, Tk spinbox, tile spinbox,
    tile combobox, widget</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="postDeleteEntryText">The <code><b>wcb::postDeleteEntryText</b></code>
  Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>wcb::postDeleteEntryText</code> &ndash; Query the would-be text
    of a Tk or tile entry, BWidget Entry, Tk or tile spinbox, or tile combobox
    widget after text deletion</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>wcb::postDeleteEntryText</b> <i>widgetName from</i> ?<i>to</i>?
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>Returns the text that would be contained in the Tk or tile entry,
    BWidget Entry, Tk or tile spinbox, or tile combobox widget
    <code><i>widgetName</i></code> after deleting the characters starting with
    the one indicated by the index <code><i>from</i></code> and stopping just
    before <code><i>to</i></code>.&nbsp; If <code><i>to</i></code> is not
    specified then the return value is the text that would be contained in the
    widget after deleting the single character given by
    <code><i>from</i></code>.</dd>

    <dd class="tm"><b>REMARK:</b>&nbsp; This command has a variable number (2
    or 3) of arguments, because the <code><b>delete</b></code> subcommand of
    the Tcl command associated with <code><i>widgetName</i></code> expects
    either one or two indices as arguments.&nbsp; For this reason, the correct
    way to invoke this command from within a before-<code><b>delete</b></code>
    callback is as shown in the following example:</dd>

    <dd>
      <blockquote>
        <pre>
proc myBeforeDeleteCallback {w args} {
    <span class="cmt">#
    # Get the text that would be contained in the widget after
    # deleting the characters specified by $args, which stands
    # for the one or two arguments passed to delete; pass these
    # arguments to wcb::postDeleteEntryText by expanding $args
    #</span>
    set newText [eval [list wcb::postDeleteEntryText $w] $args]
    if {!<i>some_condition_on_</i>$newText} {
        wcb::cancel
    }
}
</pre>
      </blockquote>
    </dd>

    <dd>The following alternative, more elegant solution requires Tcl/Tk 8.5 or
    later:</dd>

    <dd>
      <blockquote>
        <pre>
proc myBeforeDeleteCallback {w args} {
    <span class="cmt"># . . .</span>
    set newText [wcb::postDeleteEntryText $w {*}$args]
    . . .
}
</pre>
      </blockquote>
    </dd>

    <dt><b>KEYWORDS</b></dt>

    <dd>delete, Tk entry, tile entry, BWidget Entry, Tk spinbox, tile spinbox,
    tile combobox, widget</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="entrycb">Before-<code><b>insert</b></code> Callbacks for entry,
  spinbox, and combobox Widgets</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>wcb::checkStrFor*</code>, <code>wcb::convStrTo*</code>,
    <code>wcb::checkEntryFor*</code>, <code>wcb::checkEntryLen</code> &ndash;
    Before-<code><b>insert</b></code> callbacks for Tk entry, tile entry,
    BWidget Entry, Tk spinbox, tile spinbox, and tile combobox widgets</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>wcb::checkStrForRegExp</b>  <i>exp w idx str</i>

<b>wcb::checkStrForAlpha</b>   <i>    w idx str</i>
<b>wcb::checkStrForNum</b>     <i>    w idx str</i>
<b>wcb::checkStrForAlnum</b>   <i>    w idx str</i>

<b>wcb::convStrToUpper</b>     <i>    w idx str</i>
<b>wcb::convStrToLower</b>     <i>    w idx str</i>

<b>wcb::checkEntryForInt</b>   <i>    w idx str</i>
<b>wcb::checkEntryForUInt</b>  <i>max w idx str</i>
<b>wcb::checkEntryForReal</b>  <i>    w idx str</i>
<b>wcb::checkEntryForFixed</b> <i>cnt w idx str</i>

<b>wcb::checkEntryLen</b>      <i>len w idx str</i>
</pre>
    </dd>

    <dt class="tm"><b>DESCRIPTION</b></dt>

    <dd>The <code><b>wcb::checkStrForRegExp</b></code> callback checks whether
    the string <code><i>str</i></code> to be inserted into the Tk or tile
    entry, BWidget Entry, Tk or tile spinbox, or tile combobox widget
    <code><i>w</i></code> is matched by the regular expression
    <code><i>exp</i></code>; if not, it cancels the <code><b>insert</b></code>
    operation.</dd>

    <dd class="tm">The three other <code><b>wcb::checkStrFor*</b></code>
    callbacks check whether the string <code><i>str</i></code> to be inserted
    into the Tk or tile entry, BWidget Entry, Tk or tile spinbox, or tile
    combobox widget <code><i>w</i></code> is alphabetic, numeric, or
    alphanumeric, respectively; if not, they cancel the
    <code><b>insert</b></code> operation.&nbsp; These procedures just invoke
    the callback <code><b>wcb::checkStrForRegExp</b></code>, passing to it the
    Unicode-based patterns <code>{^[[:alpha:]]*$}</code>,
    <code>{^[[:digit:]]*$}</code>, and <code>{^[[:alnum:]]*$}</code> for Tk
    versions 8.1 or higher, and the ASCII patterns <code>{^[A-Za-z]*$}</code>,
    <code>{^[0-9]*$}</code>, and <code>{^[A-Za-z0-9]*$}</code> if Tk version
    8.0 is being used.</dd>

    <dd class="tm">The <code><b>wcb::convStrTo*</b></code> callbacks replace
    the string <code><i>str</i></code> to be inserted into the Tk or tile
    entry, BWidget Entry, Tk or tile spinbox, or tile combobox widget
    <code><i>w</i></code> with its uppercase or lowercase equivalent,
    respectively.</dd>

    <dd class="tm">The <code><b>wcb::checkEntryFor*</b></code> callbacks check
    whether the text contained in the Tk or tile entry, BWidget Entry, Tk or
    tile spinbox, or tile combobox widget <code><i>w</i></code> after inserting
    the string <code><i>str</i></code> before the character indicated by the
    index <code><i>idx</i></code> would represent (the starting part of) an
    integer number, unsigned integer no greater than <code><i>max</i></code>,
    real number, or real number in fixed-point format with at most
    <code><i>cnt</i></code> digits after the decimal point, respectively; if
    not, they cancel the <code><b>insert</b></code> operation.&nbsp;
    <code><i>max</i></code> and <code><i>cnt</i></code> should be nonnegative
    numbers or <code><b>*</b></code>;&nbsp; <code><i>max</i> =
    <b>*</b></code>&nbsp; means: no upper bound for the Tk or tile entry,
    BWidget Entry, Tk or tile spinbox, or tile combobox value, while&nbsp;
    <code><i>cnt</i> = <b>*</b></code>&nbsp; stands for an unlimited number of
    digits after the decimal point.</dd>

    <dd class="tm">The <code><b>wcb::checkEntryLen</b></code> callback checks
    whether the length of the text contained in the Tk or tile entry, BWidget
    Entry, Tk or tile spinbox, or tile combobox widget <code><i>w</i></code>
    after inserting the string <code><i>str</i></code> would be greater than
    <code><i>len</i></code>; if yes, it cancels the <code><b>insert</b></code>
    operation.</dd>

    <dd class="tm">These callback procedures are implemented in the file
    <code><b>wcbEntry.tcl</b></code>, contained in the
    <code><b>scripts</b></code> directory.&nbsp; They return an empty
    string.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>callback, insert, Tk entry, tile entry, BWidget Entry, Tk spinbox, tile
    spinbox, tile combobox, widget</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="textcb">Before-<code><b>insert</b></code> Callbacks for text and
  ctext Widgets</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>wcb::checkStrsFor*</code>, <code>wcb::convStrsTo*</code> &ndash;
    Before-<code><b>insert</b></code> callbacks for text and ctext widgets</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>wcb::checkStrsForRegExp</b> <i>exp w idx args</i>

<b>wcb::checkStrsForAlpha</b>  <i>    w idx args</i>
<b>wcb::checkStrsForNum</b>    <i>    w idx args</i>
<b>wcb::checkStrsForAlnum</b>  <i>    w idx args</i>

<b>wcb::convStrsToUpper</b>    <i>    w idx args</i>
<b>wcb::convStrsToLower</b>    <i>    w idx args</i>
</pre>
    </dd>

    <dt class="tm"><b>DESCRIPTION</b></dt>

    <dd>The <code><b>wcb::checkStrsForRegExp</b></code> callback checks whether
    the strings to be inserted into the text or ctext widget
    <code><i>w</i></code>, contained in the list <code><i>args</i></code> of
    the form&nbsp; <code><i>string</i> ?<i>tagList</i> <i>string</i>
    <i>tagList</i> ...?</code>,&nbsp; are matched by the regular expression
    <code><i>exp</i></code>; if not, it cancels the <code><b>insert</b></code>
    operation.</dd>

    <dd class="tm">The three other <code><b>wcb::checkStrsFor*</b></code>
    callbacks check whether the strings to be inserted into the text or ctext
    widget <code><i>w</i></code>, contained in the list
    <code><i>args</i></code> of the form&nbsp; <code><i>string</i>
    ?<i>tagList</i> <i>string</i> <i>tagList</i> ...?</code>,&nbsp; are
    alphabetic, numeric, or alphanumeric, respectively; if not, they cancel the
    <code><b>insert</b></code> operation.&nbsp; These procedures just invoke
    the callback <code><b>wcb::checkStrsForRegExp</b></code>, passing to it the
    Unicode-based patterns <code>{^[[:alpha:]\n]*$}</code>,
    <code>{^[[:digit:]\n]*$}</code>, and <code>{^[[:alnum:]\n]*$}</code> for Tk
    versions 8.1 or higher, and the ASCII patterns
    <code>"^\[A-Za-z\n]*$"</code>, <code>"^\[0-9\n]*$"</code>, and
    <code>"^\[A-Za-z0-9\n]*$"</code> if Tk version 8.0 is being used (in this
    case, the presence of the <code>"\n"</code> makes the regular expressions a
    bit ugly).</dd>

    <dd class="tm">The <code><b>wcb::convStrsTo*</b></code> callbacks replace
    the strings to be inserted into the text or ctext widget
    <code><i>w</i></code>, contained in the list <code><i>args</i></code> of
    the form&nbsp; <code><i>string</i> ?<i>tagList</i> <i>string</i>
    <i>tagList</i> ...?</code>,&nbsp; with their uppercase or lowercase
    equivalents, respectively.</dd>

    <dd class="tm">These callback procedures are implemented in the file
    <code><b>wcbText.tcl</b></code>, contained in the
    <code><b>scripts</b></code> directory.&nbsp; They return an empty
    string.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>callback, insert, text, ctext, widget</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>
</body>
</html>

<!DOCTYPE html>
<html>
<head>
  <title>The Scrolling Utilities Package Scrollutil 1.5</title>

  <meta name="Author" content="Csaba Nemethi">
  <meta name="Keywords" content=
  "mouse wheel event, binding, event handling, scrolling, scrollable widget container, focus, scrollarea, scrollsync, scrollableframe">

  <link rel="stylesheet" type="text/css" href="stylesheet.css">
</head>

<body>
  <div align="center">
    <h1>The Scrolling Utilities Package Scrollutil 1.5</h1>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:csaba.nemethi@t-online.de">csaba.nemethi@t-online.de</a>
    </address>
  </div>

  <hr>

  <h2>Contents</h2>

  <p><a href="scrollutil.html">Scrollutil Programmer's Guide</a></p>

  <p><a href="scrollarea.html">The <code>scrollutil::scrollarea</code> and
  <code>scrollutil::getscrollarea</code> Commands</a></p>

  <p><a href="scrollsync.html">The <code>scrollutil::scrollsync</code> and
  <code>scrollutil::getscrollsync</code> Commands</a></p>

  <p><a href="scrollableframe.html">The
  <code>scrollutil::scrollableframe</code> Command</a></p>

  <p><a href="wheelEvent.html">Commands Related to Mouse Wheel Event
  Handling</a></p>
</body>
</html>

<!DOCTYPE html>
<html>
<head>
  <title>The scrollutil::scrollableframe Command</title>

  <meta name="Author" content="Csaba Nemethi">
  <meta name="Keywords" content="scrollableframe, widget, frame, scrollable">

  <link rel="stylesheet" type="text/css" href="stylesheet.css">
</head>

<body>
  <div align="center">
    <h1>The <code><b>scrollutil::scrollableframe</b></code> Command</h1>

    <h2>For Scrollutil Version 1.5</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:csaba.nemethi@t-online.de">csaba.nemethi@t-online.de</a>
    </address>
  </div>

  <hr>

  <h2 id="contents">Contents</h2>

  <ul>
    <li><a href="#quick_ref">Quick Reference</a></li>

    <li><a href="#detailed_ref">Detailed Reference</a></li>

    <li><a href="#comparison">Comparison with BWidget ScrollableFrame and
    iwidgets::scrolledframe</a></li>
  </ul>

  <div align="center">
    <p><a href="index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="quick_ref">Quick Reference</h2>

  <dl>
    <dt><a href="#name">NAME</a></dt>

    <dd><code>scrollutil::scrollableframe</code> &ndash; Create and manipulate
    scrollableframe widgets</dd>

    <dt class="tm"><a href="#synopsis">SYNOPSIS</a></dt>

    <dd>
      <pre>
<b>scrollutil::scrollableframe</b> <i>pathName</i> ?<i>options</i>?
</pre>
    </dd>

    <dt><a href="#description">DESCRIPTION</a></dt>

    <dt class="tm"><a href="#std_options">STANDARD OPTIONS</a></dt>

    <dd>
      <pre>
<b>-background   -highlightbackground  -relief
-borderwidth  -highlightcolor       -xscrollcommand
-cursor       -highlightthickness   -yscrollcommand</b>
</pre>
    </dd>

    <dt><a href="#widget_options">WIDGET-SPECIFIC OPTIONS</a></dt>

    <dd><code><b><a href="#contentheight">-contentheight</a></b>
    <i>screenDistance</i></code></dd>

    <dd><code><b><a href="#contentwidth">-contentwidth</a></b>
    <i>screenDistance</i></code></dd>

    <dd><code><b><a href="#fitcontentheight">-fitcontentheight</a></b>
    <i>boolean</i></code></dd>

    <dd><code><b><a href="#fitcontentwidth">-fitcontentwidth</a></b>
    <i>boolean</i></code></dd>

    <dd><code><b><a href="#height">-height</a></b> <i>screenDistance</i></code></dd>

    <dd><code><b><a href="#takefocus">-takefocus</a></b>
    <b>0</b>|<b>1</b>|<b>""</b>|<i>command</i></code></dd>

    <dd><code><b><a href="#width">-width</a></b>
    <i>screenDistance</i></code></dd>

    <dd><code><b><a href="#xscrollincrement">-xscrollincrement</a></b>
    <i>screenDistance</i></code></dd>

    <dd><code><b><a href="#yscrollincrement">-yscrollincrement</a></b>
    <i>screenDistance</i></code></dd>

    <dt class="tm"><a href="#widget_command">WIDGET COMMAND</a></dt>

    <dd><code><i>pathName</i> <b><a href="#cget">cget</a></b>
    <i>option</i></code></dd>

    <dd><code><i>pathName</i> <b><a href="#configure">configure</a></b>
    ?<i>option</i>? ?<i>value</i> <i>option</i> <i>value</i> ...?</code></dd>

    <dd><code><i>pathName</i> <b><a href=
    "#contentframe">contentframe</a></b></code></dd>

    <dd>
      <code><i>pathName</i> <b><a href="#scan">scan</a></b> <i>option
      args</i></code>

      <dl>
        <dd><code><i>pathName</i> <b>scan mark</b> <i>x y</i></code></dd>

        <dd><code><i>pathName</i> <b>scan dragto</b> <i>x y</i>
        ?<i>gain</i>?</code> </dd>
      </dl>
    </dd>

    <dd><code><i>pathName</i> <b><a href="#see">see</a></b> <i>widget</i>
    ?<b>nw</b>|<b>ne</b>|<b>sw</b>|<b>se</b>?</code></dd>

    <dd>
      <code><i>pathName</i> <b><a href="#xview">xview</a></b>
      ?<i>args</i>?</code>

      <dl>
        <dd><code><i>pathName</i> <b>xview</b></code></dd>

        <dd><code><i>pathName</i> <b>xview moveto</b>
        <i>fraction</i></code></dd>

        <dd><code><i>pathName</i> <b>xview scroll</b> <i>number</i>
        <b>units</b>|<b>pages</b></code></dd>
      </dl>
    </dd>

    <dd>
      <code><i>pathName</i> <b><a href="#yview">yview</a></b>
      ?<i>args</i>?</code>

      <dl>
        <dd><code><i>pathName</i> <b>yview</b></code></dd>

        <dd><code><i>pathName</i> <b>yview moveto</b>
        <i>fraction</i></code></dd>

        <dd><code><i>pathName</i> <b>yview scroll</b> <i>number</i>
        <b>units</b>|<b>pages</b></code></dd>
      </dl>
    </dd>

    <dt class="tm"><a href="#bindings">BINDINGS</a></dt>

    <dt class="tm"><a href="#keywords">KEYWORDS</a></dt>

    <dd>scrollableframe, widget, frame, scrollable</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="detailed_ref">Detailed Reference</h2>

  <dl>
    <dt id="name"><b>NAME</b></dt>

    <dd><code>scrollutil::scrollableframe</code> &ndash; Create and manipulate
    scrollableframe widgets</dd>

    <dt class="tm" id="synopsis"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>scrollutil::scrollableframe</b> <i>pathName</i> ?<i>options</i>?
</pre>
    </dd>

    <dt id="description"><b>DESCRIPTION</b></dt>

    <dd>The <code><b>scrollutil::scrollableframe</b></code> command creates a
    new window named <code><i>pathName</i></code> and of the class
    <code><b>Scrollableframe</b></code>, and makes it into a
    <b>scrollableframe</b> widget.&nbsp; 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.&nbsp; The
    <code><b>scrollutil::scrollableframe</b></code> command returns its
    <code><i>pathName</i></code> argument.&nbsp; At the time this command is
    invoked, there must not exist a window named <code><i>pathName</i></code>,
    but <code><i>pathName</i></code>'s parent must exist.</dd>

    <dd class="tm">A scrollableframe is a mega-widget containing a <b>content
    frame</b>, whose dimensions may be larger than those of the widget
    itself.&nbsp; Arbitrary regions of this frame can be brought into view by
    scrolling, being that the scrollableframe widget supports the
    <code><b>-xscrollcommand</b></code> and <code><b>-yscrollcommand</b></code>
    configuration options and the associated Tcl command has the
    <code><b><a href="#xview">xview</a></b></code> and <code><b><a href=
    "#yview">yview</a></b></code> subcommands.&nbsp; The content frame may
    contain any number of arbitrary widgets.&nbsp; In other words, the
    <code><b>scrollutil::scrollableframe</b></code> command implements a
    <b>scrollable widget container</b>.</dd>

    <dd class="tm">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.&nbsp; The content frame can be
    accessed by means of the <code><b><a href=
    "#contentframe">contentframe</a></b></code> subcommand.&nbsp; Individual
    widgets contained in it can be made visible in the scrollableframe window
    with the aid of the <code><b><a href="#see">see</a></b></code>
    subcommand.&nbsp; In addition to scrolling, scrollableframe widgets also
    support scanning, with the aid of appropriate mouse event bindings that
    invoke the <code><b><a href="#scan">scan</a></b></code> subcommand.</dd>

    <dd class="tm">
      A scrollableframe widget is typically created within a <a href=
      "scrollarea.html">scrollarea</a>, like in the following example:

      <blockquote>
        <pre>
set sa [<a href="scrollarea.html#synopsis">scrollutil::scrollarea</a> ...]
set sf [<a href="#synopsis">scrollutil::scrollableframe</a> $sa.sf ...]
$sa <a href="scrollarea.html#setwidget">setwidget</a> $sf

set cf [$sf <a href="#contentframe">contentframe</a>]
<i>&lt;populate the content frame&gt;</i>

update idletasks
$sf <a href="#configure">configure</a> <a href=
"#width">-width</a> [winfo reqwidth $cf] <a href=
"#height">-height</a> ... <a href="#yscrollincrement">-yscrollincrement</a> ...

pack $sa -expand yes -fill both
</pre>
      </blockquote>
    </dd>

    <dt id="std_options"><b>STANDARD OPTIONS</b></dt>

    <dd>
      <pre>
<b>-background   -highlightbackground  -relief
-borderwidth  -highlightcolor       -xscrollcommand
-cursor       -highlightthickness   -yscrollcommand</b>
</pre>
    </dd>

    <dd>See the <b>options</b> manual entry for details on the standard Tk
    widget options.&nbsp; The <code><b>-background</b></code>,
    <code><b>-highlightbackground</b></code>,
    <code><b>-highlightcolor</b></code>, and
    <code><b>-highlightthickness</b></code> options are only supported by the
    Scrollutil package, but not by Scrollutil_tile.&nbsp; They have the same
    default values as the options of the same names for Tk frame widgets.&nbsp;
    The default values of the remaining standard options are:</dd>

    <dd>
      <pre>
<b>-borderwidth</b> 0 <b>-cursor</b> "" <b>-relief flat</b> <b>-xscrollcommand</b> "" <b>-yscrollcommand</b> ""
</pre>
    </dd>

    <dt id="widget_options"><b>WIDGET-SPECIFIC OPTIONS</b></dt>

    <dd id="contentheight">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
          <td><code><b>-contentheight</b></code></td>
        </tr>

        <tr>
          <td>Database Name:</td>
          <td><code><b>&nbsp;contentHeight</b></code></td>
        </tr>

        <tr>
          <td>Database Class:</td>
          <td><code><b>&nbsp;ContentHeight</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>Specifies the desired height for the content frame in any of the
        forms acceptable to <code><b>Tk_GetPixels</b></code>.&nbsp; 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.&nbsp; This
        option is only relevant if the value of the <code><b><a href=
        "#fitcontentheight">-fitcontentheight</a></b></code> option is false;
        otherwise the content frame will have the same height as the
        scrollableframe window, regardless of the value of the
        <code><b>-contentheight</b></code> option.&nbsp; The default is
        <code>0</code>, which is suitable for the vast majority of
        applications.</p>
      </blockquote>
    </dd>

    <dd id="contentwidth">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
          <td><code><b>-contentwidth</b></code></td>
        </tr>

        <tr>
          <td>Database Name:</td>
          <td><code><b>&nbsp;contentWidth</b></code></td>
        </tr>

        <tr>
          <td>Database Class:</td>
          <td><code><b>&nbsp;ContentWidth</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>Specifies the desired width for the content frame in any of the
        forms acceptable to <code><b>Tk_GetPixels</b></code>.&nbsp; 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.&nbsp; This
        option is only relevant if the value of the <code><b><a href=
        "#fitcontentwidth">-fitcontentwidth</a></b></code> option is false;
        otherwise the content frame will have the same width as the
        scrollableframe window, regardless of the value of the
        <code><b>-contentwidth</b></code> option.&nbsp; The default is
        <code>0</code>, which is suitable for the vast majority of
        applications.</p>
      </blockquote>
    </dd>

    <dd id="fitcontentheight">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
          <td><code><b>-fitcontentheight</b></code></td>
        </tr>

        <tr>
          <td>Database Name:</td>
          <td><code><b>&nbsp;fitContentHeight</b></code></td>
        </tr>

        <tr>
          <td>Database Class:</td>
          <td><code><b>&nbsp;FitContentHeight</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>Specifies a boolean value indicating whether or not the content
        frame should have the same height as the scrollableframe window.&nbsp;
        If true then the content frame's height will be kept in sync with that
        of the widget and the value of the <code><b><a href=
        "#contentheight">-contentheight</a></b></code> option will be
        ignored.&nbsp; The default is <code>0</code>.</p>
      </blockquote>
    </dd>

    <dd id="fitcontentwidth">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
          <td><code><b>-fitcontentwidth</b></code></td>
        </tr>

        <tr>
          <td>Database Name:</td>
          <td><code><b>&nbsp;fitContentWidth</b></code></td>
        </tr>

        <tr>
          <td>Database Class:</td>
          <td><code><b>&nbsp;FitContentWidth</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>Specifies a boolean value indicating whether or not the content
        frame should have the same width as the scrollableframe window.&nbsp;
        If true then the content frame's width will be kept in sync with that
        of the widget and the value of the <code><b><a href=
        "#contentwidth">-contentwidth</a></b></code> option will be
        ignored.&nbsp; The default is <code>0</code>.</p>
      </blockquote>
    </dd>

    <dd id="height">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
          <td><code><b>-height</b></code></td>
        </tr>

        <tr>
          <td>Database Name:</td>
          <td><code><b>&nbsp;height</b></code></td>
        </tr>

        <tr>
          <td>Database Class:</td>
          <td><code><b>&nbsp;Height</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>Specifies the desired height for the scrollableframe widget in any
        of the forms acceptable to <code><b>Tk_GetPixels</b></code>.&nbsp;
        Note that this sets the <i>inner</i> height, excluding the border and
        highlight rectangle (if any) drawn around the outside of the
        widget.&nbsp; The default is <code>100</code>, which should be
        overridden with a suitable application-specific value.</p>
      </blockquote>
    </dd>

    <dd id="takefocus">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
          <td><code><b>-takefocus</b></code></td>
        </tr>

        <tr>
          <td>Database Name:</td>
          <td><code><b>&nbsp;takeFocus</b></code></td>
        </tr>

        <tr>
          <td>Database Class:</td>
          <td><code><b>&nbsp;TakeFocus</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>This option determines whether the scrollableframe widget accepts
        the focus during keyboard traversal.&nbsp; It is almost identical to
        the standard option of the same name (see the <b>options</b> manual
        entry for details).&nbsp; 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
        (<code>Tab</code> and <code>Shift-Tab</code>).&nbsp; The default is
        <code>0</code>, being that a scrollableframe widget is esentially a
        frame used as a view for its content frame component.</p>
      </blockquote>
    </dd>

    <dd id="width">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
          <td><code><b>-width</b></code></td>
        </tr>

        <tr>
          <td>Database Name:</td>
          <td><code><b>&nbsp;width</b></code></td>
        </tr>

        <tr>
          <td>Database Class:</td>
          <td><code><b>&nbsp;Width</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>Specifies the desired width for the scrollableframe widget in any
        of the forms acceptable to <code><b>Tk_GetPixels</b></code>.&nbsp;
        Note that this sets the <i>inner</i> width, excluding the border and
        highlight rectangle (if any) drawn around the outside of the
        widget.&nbsp; The default is <code>100</code>, which should be
        overridden with a suitable application-specific value.</p>
      </blockquote>
    </dd>

    <dd id="xscrollincrement">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
          <td><code><b>-xscrollincrement</b></code></td>
        </tr>

        <tr>
          <td>Database Name:</td>
          <td><code><b>&nbsp;xScrollIncrement</b></code></td>
        </tr>

        <tr>
          <td>Database Class:</td>
          <td><code><b>&nbsp;ScrollIncrement</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>Specifies an increment for horizontal scrolling, in any of the forms
        acceptable to <code><b>Tk_GetPixels</b></code>.&nbsp; 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
        <code><b>xScrollIncrement</b></code>; furthermore, the units for
        horizontal scrolling (see the <code><b><a href=
        "#xview">xview</a></b></code> subcommad) will also be
        <code><b>xScrollIncrement</b></code>.&nbsp; If the value is less than
        or equal to zero then the horizontal scrolling is unconstrained.&nbsp;
        The default is <code>0</code>.</p>
      </blockquote>
    </dd>

    <dd id="yscrollincrement">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
          <td><code><b>-yscrollincrement</b></code></td>
        </tr>

        <tr>
          <td>Database Name:</td>
          <td><code><b>&nbsp;yScrollIncrement</b></code></td>
        </tr>

        <tr>
          <td>Database Class:</td>
          <td><code><b>&nbsp;ScrollIncrement</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>Specifies an increment for vertical scrolling, in any of the forms
        acceptable to <code><b>Tk_GetPixels</b></code>.&nbsp; 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
        <code><b>yScrollIncrement</b></code>; furthermore, the units for
        vertical scrolling (see the <code><b><a href=
        "#yview">yview</a></b></code> subcommad) will also be
        <code><b>yScrollIncrement</b></code>.&nbsp; If the value is less than
        or equal to zero then the vertical scrolling is unconstrained.&nbsp;
        The default is <code>0</code>.</p>
      </blockquote>
    </dd>

    <dt id="widget_command"><b>WIDGET COMMAND</b></dt>

    <dd>
      The <code><b>scrollutil::scrollableframe</b></code> command creates a new
      Tcl command whose name is <code><i>pathName</i></code>.&nbsp; This
      command may be used to invoke various operations on the widget.&nbsp; It
      has the following general form:

      <blockquote>
        <pre>
<i>pathName</i> <i>option</i> ?<i>arg</i> <i>arg</i> ...?
</pre>
      </blockquote>
    </dd>

    <dd><code><i>option</i></code> and the <code><i>arg</i></code>s determine
    the exact behavior of the command.&nbsp; The following commands are
    possible for scrollableframe widgets:</dd>

    <dd>
      <dl>
        <dt class="tm" id="cget"><code><i>pathName</i> <b>cget</b>
        <i>option</i></code></dt>

        <dd>Returns the current value of the configuration option given by
        <code><i>option</i></code>, which may have any of the values accepted
        by the <code><b>scrollutil::scrollableframe</b></code> command.</dd>

        <dt class="tm" id="configure"><code><i>pathName</i> <b>configure</b>
        ?<i>option</i>? ?<i>value</i> <i>option</i> <i>value</i>
        ...?</code></dt>

        <dd>Queries or modifies the configuration options of the widget.&nbsp;
        If no <code><i>option</i></code> is specified, the command returns a
        list describing all of the available options for
        <code><i>pathName</i></code> (see <code><b>Tk_ConfigureInfo</b></code>
        for information on the format of this list).&nbsp; If
        <code><i>option</i></code> is specified with no
        <code><i>value</i></code>, 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 <code><i>option</i></code> is
        specified).&nbsp; If one or more
        <code><i>option</i></code>-<code><i>value</i></code> 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.&nbsp; <code><i>option</i></code> may have any of the values
        accepted by the <code><b>scrollutil::scrollableframe</b></code>
        command.</dd>

        <dt class="tm" id="contentframe"><code><i>pathName</i>
        <b>contentframe</b></code></dt>

        <dd>Returns the path name of the widget's content frame.</dd>

        <dt class="tm" id="scan"><code><i>pathName</i> <b>scan</b> <i>option
        args</i></code></dt>

        <dd>This command is used to implement scanning on scrollableframe
        widgets.&nbsp; It has two forms, depending on
        <code><i>option</i></code>:</dd>

        <dd>
          <dl>
            <dt class="tm"><code><i>pathName</i> <b>scan mark</b> <i>x
            y</i></code></dt>

            <dd>Records <code><i>x</i></code> and <code><i>y</i></code> and the
            current view in the scrollableframe window; used in conjunction
            with later&nbsp; <code><b>scan</b> <b>dragto</b></code>&nbsp;
            commands.&nbsp; Typically this command is associated with a mouse
            button press in the widget and <code><i>x</i></code> and
            <code><i>y</i></code> are the coordinates of the mouse.&nbsp; It
            returns an empty string.</dd>

            <dt class="tm"><code><i>pathName</i> <b>scan dragto</b> <i>x y</i>
            ?<i>gain</i>?</code></dt>

            <dd>This command computes the difference between its
            <code><i>x</i></code> and <code><i>y</i></code> arguments (which
            are typically mouse coordinates) and the <code><i>x</i></code> and
            <code><i>y</i></code> arguments to the last&nbsp; <code><b>scan</b>
            <b>mark</b></code>&nbsp; command for the widget.&nbsp; It then
            adjusts the view by <code><i>gain</i></code> times the difference
            in coordinates, where <code><i>gain</i></code> defaults to
            <code>10</code>.&nbsp; 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.&nbsp;
            The return value is an empty string.</dd>
          </dl>
        </dd>

        <dt class="tm" id="see"><code><i>pathName</i> <b>see</b> <i>widget</i>
        ?<i>corner</i>?</code></dt>

        <dd>This command adjusts the view in the scrollableframe's window so
        that <code><i>widget</i></code> becomes visible in it.&nbsp; The
        specified widget must be a descendant of the content frame and must
        have the same toplevel.&nbsp; In addition, it must be managed by some
        geometry manager (such as <code><b>grid</b></code>,
        <code><b>pack</b></code>, <code><b>place</b></code>,
        <code><b>text</b></code>, or <code><b>canvas</b></code>).&nbsp; The
        optional <code><i>corner</i></code> argument specifies which corner of
        <code><i>widget</i></code> should become visible if it is too large to
        fit into the window.&nbsp; The possible values are
        <code><b>nw</b></code> (north-west), <code><b>ne</b></code>
        (north-east), <code><b>sw</b></code> (south-west), and
        <code><b>se</b></code> (south-east).&nbsp; The default corner is
        <code><b>nw</b></code>.</dd>

        <dd class="tm"><b>REMARK:</b>&nbsp; By using this subcommand you can
        make the keyboard navigation in the content frame more user-friendly,
        like in the following example, in which <code>$w</code> is a descendant
        of the content frame of the scrollableframe widget
        <code>$sf</code> (it is assumed that <code>$sf</code> doesn't contain
        <code>%</code> characters):</dd>

        <dd>
          <blockquote>
            <pre>
bind $w &lt;&lt;TraverseIn&gt;&gt; [list $sf <span class="red">see</span> %W]
</pre>
          </blockquote>
        </dd>

        <dd>If the widget <code>$w</code> was embedded into a <a href=
        "scrollarea.html">scrollarea</a> via the latter's <code><b><a href=
        "scrollarea.html#setwidget">setwidget</a></b></code> 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:</dd>

        <dd>
          <blockquote>
            <pre>
bind $w &lt;&lt;TraverseIn&gt;&gt; [list seeScrollarea $sf %W]

proc seeScrollarea {sf w} { $sf <span class="red">see</span> [<b><a href=
"scrollarea.html#getscrollarea">scrollutil::getscrollarea</a></b> $w] }
</pre>
          </blockquote>
        </dd>

        <dt id="xview"><code><i>pathName</i> <b>xview</b>
        ?<i>args</i>?</code></dt>

        <dd>This command is used to query and change the horizontal position of 
        the information displayed in the widget's window.&nbsp; It can take any
        of the following forms:</dd>

        <dd>
          <dl>
            <dt class="tm"><code><i>pathName</i> <b>xview</b></code></dt>

            <dd>Returns a list containing two elements.&nbsp; Each element is a
            real fraction between <code>0</code> and <code>1</code>; together
            they describe the horizontal span that is visible in the
            window.&nbsp; For example, if the first element is <code>0.2</code>
            and the second element is <code>0.6</code> 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.&nbsp; These are the same values passed to scrollbars via the
            <code><b>-xscrollcommand</b></code> option.</dd>

            <dt class="tm"><code><i>pathName</i> <b>xview moveto</b>
            <i>fraction</i></code></dt>

            <dd>Adjusts the view in the window so that
            <code><i>fraction</i></code> of the total width of the content
            frame is off-screen to the left.&nbsp; <code><i>fraction</i></code>
            must be a fraction between <code>0</code> and <code>1</code>.</dd>

            <dt class="tm"><code><i>pathName</i> <b>xview scroll</b> <i>number
            what</i></code></dt>

            <dd>This command shifts the view in the window left or right
            according to <code><i>number</i></code> and
            <code><i>what</i></code>.&nbsp; <code><i>number</i></code> must be
            an integer.&nbsp; <code><i>what</i></code> must be either
            <code><b>units</b></code> or <code><b>pages</b></code> or an
            abbreviation of one of these.&nbsp; If <code><i>what</i></code> is
            <code><b>units</b></code>, the view adjusts left or right in units
            of the <code><b><a href=
            "#xscrollincrement">xScrollIncrement</a></b></code> option if it is
            greater than zero, or in units of one-tenth the window's width
            otherwise.&nbsp; If <code><i>what</i></code> is
            <code><b>pages</b></code> then the view adjusts in units of
            nine-tenths the window's width.&nbsp; If <code><i>number</i></code>
            is negative then information farther to the left becomes visible;
            if it is positive then information farther to the right becomes
            visible.</dd>
          </dl>
        </dd>

        <dt class="tm" id="yview"><code><i>pathName</i> <b>yview</b>
        ?<i>args</i>?</code></dt>

        <dd>This command is used to query and change the vertical position of
        the information displayed in the widget's window.&nbsp; It can take any
        of the following forms:</dd>

        <dd>
          <dl>
            <dt class="tm"><code><i>pathName</i> <b>yview</b></code></dt>

            <dd>Returns a list containing two elements.&nbsp; Each element is a
            real fraction between <code>0</code> and <code>1</code>; together
            they describe the vertical span that is visible in the
            window.&nbsp; For example, if the first element is <code>0.2</code>
            and the second element is <code>0.6</code> 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.&nbsp; These are the same values passed to scrollbars via
            the <code><b>-yscrollcommand</b></code> option.</dd>

            <dt class="tm"><code><i>pathName</i> <b>yview moveto</b>
            <i>fraction</i></code></dt>

            <dd>Adjusts the view in the window so that
            <code><i>fraction</i></code> of the total height of the content
            frame is off-screen to the top.&nbsp; <code><i>fraction</i></code>
            must be a fraction between <code>0</code> and <code>1</code>.</dd>

            <dt class="tm"><code><i>pathName</i> <b>yview scroll</b> <i>number
            what</i></code></dt>

            <dd>This command shifts the view in the window up or down according
            to <code><i>number</i></code> and <code><i>what</i></code>.&nbsp;
            <code><i>number</i></code> must be an integer.&nbsp;
            <code><i>what</i></code> must be either <code><b>units</b></code>
            or <code><b>pages</b></code> or an abbreviation of one of
            these.&nbsp; If <code><i>what</i></code> is
            <code><b>units</b></code>, the view adjusts up or down in units of
            the <code><b><a href=
            "#yscrollincrement">yScrollIncrement</a></b></code> option if it is
            greater than zero, or in units of one-tenth the window's height
            otherwise.&nbsp; If <code><i>what</i></code> is
            <code><b>pages</b></code> then the view adjusts in units of
            nine-tenths the window's height.&nbsp; If
            <code><i>number</i></code> is negative then higher information
            becomes visible; if it is positive then lower information becomes
            visible.</dd>
          </dl>
        </dd>
      </dl>
    </dd>

    <dt class="tm" id="bindings"><b>BINDINGS</b></dt>

    <dd>Mouse button 1 may be used for scanning.&nbsp; If it is pressed and
    dragged over the scrollableframe window, the content frame drags at high
    speed in the direction the mouse moves.&nbsp; For the duration of the scan
    the cursor is set to one having the shape of a pointing hand.</dd>

    <dt class="tm" id="keywords"><b>KEYWORDS</b></dt>

    <dd>scrollableframe, widget, frame, scrollable</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="comparison">Comparison with BWidget ScrollableFrame and
  iwidgets::scrolledframe</h2>

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

  <table border="2" cellspacing="0" cellpadding="3">
    <tr bgcolor="#FFFFE0">
      <th align="left">scrollutil::scrollableframe</th>
      <th align="left">BWidget ScrollableFrame</th>
      <th align="left">iwidgets::scrolledframe</th>
    </tr>

    <tr>
      <td><code><b>-background</b></code></td>
      <td><code><b>-background</b></code></td>
      <td><code><b>-background</b></code></td>
    </tr>

    <tr>
      <td><code><b>-borderwidth</b></code></td>
      <td bgcolor="#e0e0e0"></td>
      <td><code><b>-borderwidth</b></code></td>
    </tr>

    <tr>
      <td><code><b>-cursor</b></code></td>
      <td bgcolor="#e0e0e0"></td>
      <td><code><b>-cursor</b></code></td>
    </tr>

    <tr>
      <td><code><b>-contentheight</b></code></td>
      <td><code><b>-areaheight</b></code></td>
      <td><code>[<i>pathName</i> <b>component canvas</b>] \<br>
      <b>itemconfigure frameTag -height</b> ...</code></td>
    </tr>

    <tr>
      <td><code><b>-contentwidth</b></code></td>
      <td><code><b>-areawidth</b></code></td>
      <td><code>[<i>pathName</i> <b>component canvas</b>] \<br>
      <b>itemconfigure frameTag -width</b> ...</code></td>
    </tr>

    <tr>
      <td><code><b>-fitcontentheight</b></code></td>
      <td><code><b>-constrainedheight</b></code></td>
      <td><code><b>bind</b> [<i>pathName</i> <b>component canvas</b>]
      <b>&lt;Configure&gt;</b> \<br>
      { <b>%W itemconfigure frameTag -height %h</b> }</code></td>
    </tr>

    <tr>
      <td><code><b>-fitcontentwidth</b></code></td>
      <td><code><b>-constrainedwidth</b></code></td>
      <td><code><b>bind</b> [<i>pathName</i> <b>component canvas</b>]
      <b>&lt;Configure&gt;</b> \<br>
      { <b>%W itemconfigure frameTag -width %w</b> }</code></td>
    </tr>

    <tr>
      <td><code><b>-height</b></code>&nbsp; (sets the <i>inner</i> height,
      excluding<br>
      the border and highlight rectangle, if any)</td>
      <td><code><b>-height</b></code>&nbsp; (inner height = total height)</td>
      <td><code><b>-height</b></code>&nbsp; (sets the <i>total</i> height,
      including<br>
      the border and horizontal scrollbar, if any)</td>
    </tr>

    <tr>
      <td><code><b>-highlightbackground</b></code></td>
      <td bgcolor="#e0e0e0"></td>
      <td bgcolor="#e0e0e0"></td>
    </tr>

    <tr>
      <td><code><b>-highlightcolor</b></code></td>
      <td bgcolor="#e0e0e0"></td>
      <td bgcolor="#e0e0e0"></td>
    </tr>

    <tr>
      <td><code><b>-highlightthickness</b></code></td>
      <td bgcolor="#e0e0e0"></td>
      <td bgcolor="#e0e0e0"></td>
    </tr>

    <tr>
      <td><code><b>-relief</b></code></td>
      <td bgcolor="#e0e0e0"></td>
      <td><code><b>-relief</b></code></td>
    </tr>

    <tr>
      <td><code><b>-takefocus</b></code></td>
      <td bgcolor="#e0e0e0"></td>
      <td bgcolor="#e0e0e0"></td>
    </tr>

    <tr>
      <td><code><b>-width</b></code>&nbsp; (sets the <i>inner</i> width,
      excluding<br>
      the border and highlight rectangle, if any)</td>
      <td><code><b>-width</b></code>&nbsp; (inner width = total width)</td>
      <td><code><b>-width</b></code>&nbsp; (sets the <i>total</i> width,
      including<br>
      the border and vertical scrollbar, if any)</td>
    </tr>

    <tr>
      <td><code><b>-xscrollcommand</b></code></td>
      <td><code><b>-xscrollcommand</b></code></td>
      <td bgcolor="#e0e0e0"></td>
    </tr>

    <tr>
      <td><code><b>-xscrollincrement</b></code></td>
      <td><code><b>-xscrollincrement</b></code></td>
      <td><code><b>-xscrollincrement</b></code> for <code>[<i>pathName</i>
      <b>component canvas</b>]</code></td>
    </tr>

    <tr>
      <td><code><b>-yscrollcommand</b></code></td>
      <td><code><b>-yscrollcommand</b></code></td>
      <td bgcolor="#e0e0e0"></td>
    </tr>

    <tr>
      <td><code><b>-yscrollincrement</b></code></td>
      <td><code><b>-yscrollincrement</b></code></td>
      <td><code><b>-yscrollincrement</b></code> for <code>[<i>pathName</i>
      <b>component canvas</b>]</code></td>
    </tr>

    <tr bgcolor="#FFFFE0">
      <td></td>
      <td></td>
      <td></td>
    </tr>

    <tr>
      <td><code><b>cget</b></code></td>
      <td><code><b>cget</b></code></td>
      <td><code><b>cget</b></code></td>
    </tr>

    <tr>
      <td><code><b>configure</b></code></td>
      <td><code><b>configure</b></code></td>
      <td><code><b>configure</b></code></td>
    </tr>

    <tr>
      <td><code><b>contentframe</b></code></td>
      <td><code><b>getframe</b></code></td>
      <td><code><b>childsite</b></code></td>
    </tr>

    <tr>
      <td><code><b>scan</b></code>&nbsp; (with mouse event bindings)</td>
      <td bgcolor="#e0e0e0"></td>
      <td bgcolor="#e0e0e0"></td>
    </tr>

    <tr>
      <td><code><b>see</b> <i>widget</i>
      ?<b>nw</b>|<b>ne</b>|<b>sw</b>|<b>se</b>?</code></td>
      <td><code><b>see</b> <i>widget</i>
      ?<b>top</b>|<b>bottom</b> ?<b>left</b>|<b>right</b>??</code></td>
      <td bgcolor="#e0e0e0"></td>
    </tr>

    <tr>
      <td><code><b>xview</b></code></td>
      <td><code><b>xview</b></code></td>
      <td><code><b>xview</b></code></td>
    </tr>

    <tr>
      <td><code><b>yview</b></code></td>
      <td><code><b>yview</b></code></td>
      <td><code><b>yview</b></code></td>
    </tr>

    <tr>
      <td><code><b>xview</b>|<b>yview</b> <b>moveto</b> 0|1</code></td>
      <td><code><b>xview</b>|<b>yview</b> <b>moveto</b> 0|1</code></td>
      <td><code><b>justify</b>
      <b>left</b>|<b>right</b>|<b>top</b>|<b>bottom</b></code><br>
      (shortcut for&nbsp; <code><b>xview</b>|<b>yview</b>
      <b>moveto</b> 0|1</code>)</td>
    </tr>
  </table>

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

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

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>
</body>
</html>

<!DOCTYPE html>
<html>
<head>
  <title>The scrollutil::scrollarea and scrollutil::getscrollarea
  Commands</title>

  <meta name="Author" content="Csaba Nemethi">
  <meta name="Keywords" content="scrollarea, widget, scrollbar">

  <link rel="stylesheet" type="text/css" href="stylesheet.css">
</head>

<body>
  <div align="center">
    <h1>The <code><b>scrollutil::scrollarea</b></code> and<br>
    <code><b>scrollutil::getscrollarea</b></code> Commands</h1>

    <h2>For Scrollutil Version 1.5</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:csaba.nemethi@t-online.de">csaba.nemethi@t-online.de</a>
    </address>
  </div>

  <hr>

  <h2 id="contents">Contents</h2>

  <ul>
    <li><a href="#quick_ref">The <code><b>scrollutil::scrollarea</b></code>
    Command &ndash; Quick Reference</a></li>

    <li><a href="#detailed_ref">The <code><b>scrollutil::scrollarea</b></code>
    Command &ndash; Detailed Reference</a></li>

    <li><a href="#getscrollarea">The
    <code><b>scrollutil::getscrollarea</b></code> Command</a></li>
  </ul>

  <div align="center">
    <p><a href="index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="quick_ref">The <code><b>scrollutil::scrollarea</b></code> Command
  &ndash; Quick Reference</h2>

  <dl>
    <dt><a href="#name">NAME</a></dt>

    <dd><code>scrollutil::scrollarea</code> &ndash; Create and manipulate
    scrollarea widgets</dd>

    <dt class="tm"><a href="#synopsis">SYNOPSIS</a></dt>

    <dd>
      <pre>
<b>scrollutil::scrollarea</b> <i>pathName</i> ?<i>options</i>?
</pre>
    </dd>

    <dt><a href="#description">DESCRIPTION</a></dt>

    <dt class="tm"><a href="#std_options">STANDARD OPTIONS</a></dt>

    <dd>
      <pre>
<b>-background   -highlightbackground  -relief
-borderwidth  -highlightcolor
-cursor       -highlightthickness</b>
</pre>
    </dd>

    <dt><a href="#widget_options">WIDGET-SPECIFIC OPTIONS</a></dt>

    <dd><code><b><a href="#lockinterval">-lockinterval</a></b>
    <i>milliseconds</i></code></dd>

    <dd><code><b><a href="#respectheader">-respectheader</a></b>
    <i>boolean</i></code></dd>

    <dd><code><b><a href="#respecttitlecolumns">-respecttitlecolumns</a></b>
    <i>boolean</i></code></dd>

    <dd><code><b><a href="#takefocus">-takefocus</a></b>
    <b>0</b>|<b>1</b>|<b>""</b>|<i>command</i></code></dd>

    <dd><code><b><a href="#xscrollbarmode">-xscrollbarmode</a></b>
    <b>static</b>|<b>dynamic</b>|<b>none</b></code></dd>

    <dd><code><b><a href="#yscrollbarmode">-yscrollbarmode</a></b>
    <b>static</b>|<b>dynamic</b>|<b>none</b></code></dd>

    <dt class="tm"><a href="#widget_command">WIDGET COMMAND</a></dt>

    <dd><code><i>pathName</i> <b><a href="#cget">cget</a></b>
    <i>option</i></code></dd>

    <dd><code><i>pathName</i> <b><a href="#configure">configure</a></b>
    ?<i>option</i>? ?<i>value</i> <i>option</i> <i>value</i> ...?</code></dd>

    <dd><code><i>pathName</i> <b><a href="#setwidget">setwidget</a></b>
    <i>widget</i></code></dd>

    <dd><code><i>pathName</i> <b><a href="#widget">widget</a></b></code></dd>

    <dt class="tm"><a href="#bindings">BINDINGS</a></dt>

    <dt class="tm"><a href="#keywords">KEYWORDS</a></dt>

    <dd>scrollarea, widget, scrollbar</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="detailed_ref">The <code><b>scrollutil::scrollarea</b></code>
  Command &ndash; Detailed Reference</h2>

  <dl>
    <dt id="name"><b>NAME</b></dt>

    <dd><code>scrollutil::scrollarea</code> &ndash; Create and manipulate
    scrollarea widgets</dd>

    <dt class="tm" id="synopsis"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>scrollutil::scrollarea</b> <i>pathName</i> ?<i>options</i>?
</pre>
    </dd>

    <dt id="description"><b>DESCRIPTION</b></dt>

    <dd>The <code><b>scrollutil::scrollarea</b></code> command creates a new
    window named <code><i>pathName</i></code> and of the class
    <code><b>Scrollarea</b></code>, and makes it into a <b>scrollarea</b>
    widget.&nbsp; Additional options, described below, 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.&nbsp; The <code><b>scrollutil::scrollarea</b></code>
    command returns its <code><i>pathName</i></code> argument.&nbsp; At the
    time this command is invoked, there must not exist a window named
    <code><i>pathName</i></code>, but <code><i>pathName</i></code>'s parent
    must exist.</dd>

    <dd class="tm">A scrollarea is a mega-widget consisting of a scrollable
    widget specified with the aid of the <code><b><a href=
    "#setwidget">setwidget</a></b></code> subcommand of the associated Tcl
    command as well as two scrollbars connected with that widget.&nbsp; These
    components are managed within the scrollarea using
    <code><b>grid</b></code>.&nbsp; The scrollbars, named
    <code><b>hsb</b></code> (with&nbsp; <code><b>-orient
    horizontal</b></code>)&nbsp; and <code><b>vsb</b></code> (with&nbsp;
    <code><b>-orient vertical</b></code>)&nbsp; are direct children of the
    scrollarea.&nbsp; The display mode of each scrollbar can be
    <code><b>static</b></code>, <code><b>dynamic</b></code>, or
    <code><b>none</b></code> (see the <code><b><a href=
    "#xscrollbarmode">-xscrollbarmode</a></b></code> and <code><b><a href=
    "#yscrollbarmode">-yscrollbarmode</a></b></code> configuration
    options).&nbsp; The <code><b>-takefocus</b></code> option of both
    scrollbars is set to <code>0</code>.&nbsp; In the Scrollutil_tile package
    the scrollbars are created as ttk::scrollbar widgets, except on Mac OS X
    when using a Tk release earlier than 8.6.10, where the native
    ttk::scrollbar widget of the <code><b>aqua</b></code> theme didn't yet look
    as expected.</dd>

    <dd class="tm">If the widget embedded into the scrollarea via
    <code><b>setwidget</b></code> is a <a href=
    "https://www.nemethi.de/tablelist/">tablelist</a> 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
    <code><b><a href=
    "#respectheader">-respectheader</a></b></code> and <code><b><a href=
    "#respecttitlecolumns">-respecttitlecolumns</a></b></code> configuration
    options.</dd>

    <dd class="tm">
      The following example shows the typical steps involved in creating a
      widget within a scrollarea:

      <blockquote>
        <pre>
set sa [<a href="scrollarea.html#synopsis">scrollutil::scrollarea</a> ...]
set lb [listbox $sa.lb ...]
$sa <a href="scrollarea.html#setwidget">setwidget</a> $lb

pack $sa -expand yes -fill both
</pre>
      </blockquote>
    </dd>

    <dt id="std_options"><b>STANDARD OPTIONS</b></dt>

    <dd>
      <pre>
<b>-background   -highlightbackground  -relief
-borderwidth  -highlightcolor
-cursor       -highlightthickness</b>
</pre>
    </dd>

    <dd>See the <b>options</b> manual entry for details on the standard Tk
    widget options.&nbsp; The <code><b>-background</b></code>,
    <code><b>-highlightbackground</b></code>,
    <code><b>-highlightcolor</b></code>, and
    <code><b>-highlightthickness</b></code> options are only supported by the
    Scrollutil package, but not by Scrollutil_tile.&nbsp; They have the same
    default values as the options of the same names for Tk frame widgets.&nbsp;
    The default values of the remaining standard options are:</dd>

    <dd>
      <pre>
<b>-borderwidth</b> 1 <b>-cursor</b> "" <b>-relief sunken</b>
</pre>
    </dd>

    <dd><b>REMARK:</b>&nbsp; When configuring the
    <code><b>-borderwidth</b></code> or <code><b>-relief</b></code> option, if
    as a result of this action the scrollarea has a positive
    <code><b>-borderwidth</b></code> value (e.g., the default <code>1</code>)
    and a <code><b>-relief</b></code> value other than <code><b>flat</b></code>
    (e.g., the default <code><b>sunken</b></code>), then the
    <code><b>-borderwidth</b></code> option of the widget embedded into the
    scrollarea via the <code><b><a href="#setwidget">setwidget</a></b></code>
    subcommand of the associated Tcl command will automatically be set to
    <code>0</code>, provided that the embedded widget supports this
    option.</dd>

    <dt class="tm" id="widget_options"><b>WIDGET-SPECIFIC OPTIONS</b></dt>

    <dd class="tm" id="lockinterval">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
          <td><code><b>-lockinterval</b></code></td>
        </tr>

        <tr>
          <td>Database Name:</td>
          <td><code><b>&nbsp;lockInterval</b></code></td>
        </tr>

        <tr>
          <td>Database Class:</td>
          <td><code><b>&nbsp;LockInterval</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>Specifies the time interval in milliseconds for which the scrollbars
        having the display mode <code><b>dynamic</b></code> (see the
        <code><b><a href="#xscrollbarmode">-xscrollbarmode</a></b></code> and
        <code><b><a href="#yscrollbarmode">-yscrollbarmode</a></b></code>
        options) will be protected from being unmapped after being mapped, in
        order to avoid any shimmering effects.&nbsp; 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.&nbsp; The same problem can arise
        due to a too small <code><b>-lockinterval</b></code> value.&nbsp; The
        default is <code>1</code>, which works as expected in the vast majority
        of cases.&nbsp; 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., <code>100</code>).</p>
      </blockquote>
    </dd>

    <dd class="tm" id="respectheader">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
          <td><code><b>-respectheader</b></code></td>
        </tr>

        <tr>
          <td>Database Name:</td>
          <td><code><b>&nbsp;respectHeader</b></code></td>
        </tr>

        <tr>
          <td>Database Class:</td>
          <td><code><b>&nbsp;RespectHeader</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>This option is only relevant if the widget embedded into the
        scrollarea with the aid of the <code><b><a href=
        "#setwidget">setwidget</a></b></code> subcommand of the associated Tcl
        command is a <a href="https://www.nemethi.de/tablelist/">tablelist</a>
        and the Tablelist version being used is 6.5 or later.&nbsp; 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.&nbsp;
        The default is <code>1</code> on the windowing systems
        <code><b>aqua</b></code> and <code><b>x11</b></code>, and
        <code>0</code> on <code><b>win32</b></code>.</p>
      </blockquote>
    </dd>

    <dd id="respecttitlecolumns">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
          <td><code><b>-respecttitlecolumns</b></code></td>
        </tr>

        <tr>
          <td>Database Name:</td>
          <td><code><b>&nbsp;respectTitleColumns</b></code></td>
        </tr>

        <tr>
          <td>Database Class:</td>
          <td><code><b>&nbsp;RespectTitleColumns</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>This option is only relevant if the widget embedded into the
        scrollarea with the aid of the <code><b><a href=
        "#setwidget">setwidget</a></b></code> subcommand of the associated Tcl
        command is a <a href="https://www.nemethi.de/tablelist/">tablelist</a>
        and the Tablelist version being used is 6.5 or later.&nbsp; 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 <code><b><a href=
        "https://www.nemethi.de/tablelist/tablelistWidget.html#titlecolumns">-titlecolumns</a></b></code>
        tablelist option is positive.&nbsp; The default is <code>1</code>.</p>
      </blockquote>
    </dd>

    <dd id="takefocus">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
          <td><code><b>-takefocus</b></code></td>
        </tr>

        <tr>
          <td>Database Name:</td>
          <td><code><b>&nbsp;takeFocus</b></code></td>
        </tr>

        <tr>
          <td>Database Class:</td>
          <td><code><b>&nbsp;TakeFocus</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>This option determines whether the scrollarea accepts the focus
        during keyboard traversal.&nbsp; It is almost identical to the standard
        option of the same name (see the <b>options</b> manual entry for
        details).&nbsp; The only difference is that not the scrollarea itself
        but the widget embedded into it via the <code><b><a href=
        "#setwidget">setwidget</a></b></code> subcommand of the associated Tcl
        command will receive the focus during keyboard traversal with the
        standard keys (<code>Tab</code> and <code>Shift-Tab</code>).&nbsp; The
        default is <code>0</code>, being that a scrollarea is esentially a
        frame containing the above-mentioned widget and two scrollbars.</p>
      </blockquote>
    </dd>

    <dd id="xscrollbarmode">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
          <td><code><b>-xscrollbarmode</b></code></td>
        </tr>

        <tr>
          <td>Database Name:</td>
          <td><code><b>&nbsp;xScrollbarMode</b></code></td>
        </tr>

        <tr>
          <td>Database Class:</td>
          <td><code><b>&nbsp;ScrollbarMode</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>Specifies the display mode to be used for the horizontal
        scrollbar.&nbsp; The allowed values are <code><b>static</b></code>,
        <code><b>dynamic</b></code>, and <code><b>none</b></code>.&nbsp; In
        <code><b>static</b></code> mode the scrollbar is displayed at all
        times.&nbsp; In <code><b>dynamic</b></code> mode (which is the default)
        the scrollbar is mapped and unmapped as needed.&nbsp; The display mode
        <code><b>none</b></code> disables the scrollbar display.</p>
      </blockquote>
    </dd>

    <dd id="yscrollbarmode">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
          <td><code><b>-yscrollbarmode</b></code></td>
        </tr>

        <tr>
          <td>Database Name:</td>
          <td><code><b>&nbsp;yScrollbarMode</b></code></td>
        </tr>

        <tr>
          <td>Database Class:</td>
          <td><code><b>&nbsp;ScrollbarMode</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>Specifies the display mode to be used for the vertical
        scrollbar.&nbsp; The allowed values are <code><b>static</b></code>,
        <code><b>dynamic</b></code>, and <code><b>none</b></code>.&nbsp; In
        <code><b>static</b></code> mode the scrollbar is displayed at all
        times.&nbsp; In <code><b>dynamic</b></code> mode (which is the default)
        the scrollbar is mapped and unmapped as needed.&nbsp; The display mode
        <code><b>none</b></code> disables the scrollbar display.</p>
      </blockquote>
    </dd>

    <dt class="tm" id="widget_command"><b>WIDGET COMMAND</b></dt>

    <dd>
      The <code><b>scrollutil::scrollarea</b></code> command creates a new Tcl
      command whose name is <code><i>pathName</i></code>.&nbsp; This command
      may be used to invoke various operations on the widget.&nbsp; It has the
      following general form:

      <blockquote>
        <pre>
<i>pathName</i> <i>option</i> ?<i>arg</i> <i>arg</i> ...?
</pre>
      </blockquote>
    </dd>

    <dd><code><i>option</i></code> and the <code><i>arg</i></code>s determine
    the exact behavior of the command.&nbsp; The following commands are
    possible for scrollarea widgets:</dd>

    <dd>
      <dl>
        <dt class="tm" id="cget"><code><i>pathName</i> <b>cget</b>
        <i>option</i></code></dt>

        <dd>Returns the current value of the configuration option given by
        <code><i>option</i></code>, which may have any of the values accepted
        by the <code><b>scrollutil::scrollarea</b></code> command.</dd>

        <dt class="tm" id="configure"><code><i>pathName</i> <b>configure</b>
        ?<i>option</i>? ?<i>value</i> <i>option</i> <i>value</i>
        ...?</code></dt>

        <dd>Queries or modifies the configuration options of the widget.&nbsp;
        If no <code><i>option</i></code> is specified, the command returns a
        list describing all of the available options for
        <code><i>pathName</i></code> (see <code><b>Tk_ConfigureInfo</b></code>
        for information on the format of this list).&nbsp; If
        <code><i>option</i></code> is specified with no
        <code><i>value</i></code>, 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 <code><i>option</i></code> is
        specified).&nbsp; If one or more
        <code><i>option</i></code>-<code><i>value</i></code> 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.&nbsp; <code><i>option</i></code> may have any of the values
        accepted by the <code><b>scrollutil::scrollarea</b></code>
        command.</dd>

        <dt class="tm" id="setwidget"><code><i>pathName</i> <b>setwidget</b>
        <i>widget</i></code></dt>

        <dd>The <code><i>widget</i></code> argument must be the path name of an
        existing widget or an empty string.&nbsp; 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
        <code><b>-xscrollcommand</b></code> and
        <code><b>-yscrollcommand</b></code> options to appropriate wrappers for
        the <code><b>set</b></code> command of the two scrollbars and setting
        the <code><b>-command</b></code> option of the scrollbars to&nbsp;
        <code>[<b>list</b> <i>widget</i> <b>xview</b>]</code>&nbsp; and&nbsp;
        <code>[<b>list</b> <i>widget</i> <b>yview</b>]</code>,&nbsp;
        respectively.&nbsp; If <code><i>widget</i></code> is an empty string
        then the widget passed to the most recent <code><b>setwidget</b></code>
        invocation (if any) is unmanaged and unconnected from the
        scrollbars.&nbsp; The return value is the argument passed to the
        previous successful invocation of this subcommand, or an empty string
        if there was no successful <code><b>setwidget</b></code> invocation
        before.</dd>

        <dd class="tm"><b>REMARK 1:</b>&nbsp; If <code><i>widget</i></code> is
        nonempty and the value of the <code><b><a href=
        "#xscrollbarmode">-xscrollbarmode</a></b></code> option is different
        from <code><b>none</b></code> then <code><i>widget</i></code> must be a
        horizontally scrollable widget, meaning that it must support the
        <code><b>-xscrollcommand</b></code> configuration option and the
        associated Tcl command must have the <code><b>xview</b></code>
        subcommand.&nbsp; Similarly, if <code><i>widget</i></code> is nonempty
        and the value of the <code><b><a href=
        "#yscrollbarmode">-yscrollbarmode</a></b></code> option is different
        from <code><b>none</b></code> then <code><i>widget</i></code> must be a
        vertically scrollable widget, meaning that it must support the
        <code><b>-yscrollcommand</b></code> configuration option and the
        associated Tcl command must have the <code><b>yview</b></code>
        subcommand.&nbsp; Consequently, if <code><i>widget</i></code> is an
        entry or ttk::entry then this subcommand will only be successful if the
        <code><b>-yscrollbarmode</b></code> option was previously set to
        <code><b>none</b></code>.</dd>

        <dd class="tm"><b>REMARK 2:</b>&nbsp; The widget identified by the
        <code><i>widget</i></code> argument must be a child of the scrollarea
        or of one of the latter's ascendants.&nbsp; This minor restriction is
        imposed by the <code><b>grid</b></code> geometry manager.</dd>

        <dd class="tm"><b>REMARK 3:</b>&nbsp; When the widget whose path name
        was passed to <code><b>setwidget</b></code> gets destroyed, this
        subcommand is automatically invoked with an empty string as
        argument.</dd>

        <dd class="tm"><b>REMARK 4:</b>&nbsp; This subcommand sets the
        <code><b>-highlightthickness</b></code> option of
        <code><i>widget</i></code> to <code>0</code> if
        <code><i>widget</i></code> supports this configuration option.&nbsp; In
        addition, if the scrollarea has a positive
        <code><b>-borderwidth</b></code> value (e.g., the default
        <code>1</code>) and a <code><b>-relief</b></code> value other than
        <code><b>flat</b></code> (e.g., the default <code><b>sunken</b></code>)
        then this subcommand sets the <code><b>-borderwidth</b></code> option
        of <code><i>widget</i></code> to <code>0</code>, provided that
        <code><i>widget</i></code> supports this option.</dd>

        <dt class="tm" id="widget"><code><i>pathName</i>
        <b>widget</b></code></dt>

        <dd>Returns the argument passed to the most recent successful
        invocation of the <code><b><a href=
        "#setwidget">setwidget</a></b></code> subcommand, or an empty string if
        there was no successful invocation of that subcommand yet.</dd>
      </dl>
    </dd>

    <dt class="tm" id="bindings"><b>BINDINGS</b></dt>

    <dd>When a new scrollarea is created, it has no default event bindings:
    scrollareas are not intended to be interactive.</dd>

    <dt class="tm" id="keywords"><b>KEYWORDS</b></dt>

    <dd>scrollarea, widget, scrollbar</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="getscrollarea">The <code><b>scrollutil::getscrollarea</b></code>
  Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>scrollutil::getscrollarea</code> &ndash; Query the scrollarea
    containing a given widget</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>scrollutil::gescrollarea</b> <i>widget</i>
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>Returns the path name of the scrollarea into which the widget given by
    the <code><i>widget</i></code> argument is embedded via the scrollarea's
    <code><b><a href="#setwidget">setwidget</a></b></code> subcommand, or an
    empty string if there is no such scrollarea widget.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>scrollarea, widget</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>
</body>
</html>

<!DOCTYPE html>
<html>
<head>
  <title>The scrollutil::scrollsync and scrollutil::getscrollsync
  Commands</title>

  <meta name="Author" content="Csaba Nemethi">
  <meta name="Keywords" content="scrollsync, widget, scrolling">

  <link rel="stylesheet" type="text/css" href="stylesheet.css">
</head>

<body>
  <div align="center">
    <h1>The <code><b>scrollutil::scrollsync</b></code> and<br>
    <code><b>scrollutil::getscrollsync</b></code> Commands</h1>

    <h2>For Scrollutil Version 1.5</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:csaba.nemethi@t-online.de">csaba.nemethi@t-online.de</a>
    </address>
  </div>

  <hr>

  <h2 id="contents">Contents</h2>

  <ul>
    <li><a href="#quick_ref">The <code><b>scrollutil::scrollsync</b></code>
    Command &ndash; Quick Reference</a></li>

    <li><a href="#detailed_ref">The <code><b>scrollutil::scrollsync</b></code>
    Command &ndash; Detailed Reference</a></li>

    <li><a href="#getscrollsync">The
    <code><b>scrollutil::getscrollsync</b></code> Command</a></li>
  </ul>

  <div align="center">
    <p><a href="index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="quick_ref">The <code><b>scrollutil::scrollsync</b></code> Command
  &ndash; Quick Reference</h2>

  <dl>
    <dt><a href="#name">NAME</a></dt>

    <dd><code>scrollutil::scrollsync</code> &ndash; Create and manipulate
    scrollsync widgets</dd>

    <dt class="tm"><a href="#synopsis">SYNOPSIS</a></dt>

    <dd>
      <pre>
<b>scrollutil::scrollsync</b> <i>pathName</i> ?<i>options</i>?
</pre>
    </dd>

    <dt><a href="#description">DESCRIPTION</a></dt>

    <dt class="tm"><a href="#std_options">STANDARD OPTIONS</a></dt>

    <dd>
      <pre>
<b>-background   -highlightbackground  -relief
-borderwidth  -highlightcolor       -xscrollcommand
-cursor       -highlightthickness   -yscrollcommand</b>
</pre>
    </dd>

    <dt><a href="#widget_options">WIDGET-SPECIFIC OPTIONS</a></dt>

    <dd><code><b><a href="#takefocus">-takefocus</a></b>
    <b>0</b>|<b>1</b>|<b>""</b>|<i>command</i></code></dd>

    <dt class="tm"><a href="#widget_command">WIDGET COMMAND</a></dt>

    <dd><code><i>pathName</i> <b><a href="#cget">cget</a></b>
    <i>option</i></code></dd>

    <dd><code><i>pathName</i> <b><a href="#configure">configure</a></b>
    ?<i>option</i>? ?<i>value</i> <i>option</i> <i>value</i> ...?</code></dd>

    <dd><code><i>pathName</i> <b><a href="#setwidgets">setwidgets</a></b>
    <i>widgetList</i></code></dd>

    <dd><code><i>pathName</i> <b><a href="#widgets">widgets</a></b></code></dd>

    <dd>
      <code><i>pathName</i> <b><a href="#xview">xview</a></b>
      ?<i>args</i>?</code>

      <dl>
        <dd><code><i>pathName</i> <b>xview</b></code></dd>

        <dd><code><i>pathName</i> <b>xview moveto</b>
        <i>fraction</i></code></dd>

        <dd><code><i>pathName</i> <b>xview scroll</b> <i>number</i>
        <b>units</b>|<b>pages</b></code></dd>
      </dl>
    </dd>

    <dd>
      <code><i>pathName</i> <b><a href="#yview">yview</a></b>
      ?<i>args</i>?</code>

      <dl>
        <dd><code><i>pathName</i> <b>yview</b></code></dd>

        <dd><code><i>pathName</i> <b>yview moveto</b>
        <i>fraction</i></code></dd>

        <dd><code><i>pathName</i> <b>yview scroll</b> <i>number</i>
        <b>units</b>|<b>pages</b></code></dd>
      </dl>
    </dd>

    <dt class="tm"><a href="#bindings">BINDINGS</a></dt>

    <dt class="tm"><a href="#keywords">KEYWORDS</a></dt>

    <dd>scrollsync, widget, scrolling</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="detailed_ref">The <code><b>scrollutil::scrollsync</b></code>
  Command &ndash; Detailed Reference</h2>

  <dl>
    <dt id="name"><b>NAME</b></dt>

    <dd><code>scrollutil::scrollsync</code> &ndash; Create and manipulate
    scrollsync widgets</dd>

    <dt class="tm" id="synopsis"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>scrollutil::scrollsync</b> <i>pathName</i> ?<i>options</i>?
</pre>
    </dd>

    <dt id="description"><b>DESCRIPTION</b></dt>

    <dd>The <code><b>scrollutil::scrollsync</b></code> command creates a new
    window named <code><i>pathName</i></code> and of the class
    <code><b>Scrollsync</b></code>, and makes it into a <b>scrollsync</b>
    widget.&nbsp; Additional options, described below, may be specified on the
    command line or in the option database to configure aspects of the
    scrollsync widget such as its borderwidth and relief.&nbsp; The
    <code><b>scrollutil::scrollsync</b></code> command returns its
    <code><i>pathName</i></code> argument.&nbsp; At the time this command is
    invoked, there must not exist a window named <code><i>pathName</i></code>,
    but <code><i>pathName</i></code>'s parent must exist.</dd>

    <dd class="tm">A scrollsync is a mega-widget, designed for scrolling
    several widgets simultaneously.&nbsp; It is both horizontally and
    vertically scrollable, meaning that it supports the
    <code><b>-xscrollcommand</b></code> and <code><b>-yscrollcommand</b></code>
    configuration options and the associated Tcl command has the
    <code><b><a href="#xview">xview</a></b></code> and <code><b><a href=
    "#yview">yview</a></b></code> subcommands.&nbsp; Whenever the
    horizontal/vertical position of the view in the window of one of the
    horizontally/vertically scrollable widgets contained in the list passed to
    the <code><b><a href="#setwidgets">setwidgets</a></b></code> subcommand of
    the associated Tcl command changes, the view in the windows of all the
    other horizontally/vertically scrollable elements of that list is
    automatically adjusted accordingly, thus making sure that the view's
    position in these windows is kept in sync.</dd>

    <dd class="tm">
      A scrollsync widget is typically created within a <a href=
      "scrollarea.html">scrollarea</a>, like in the following example:

      <blockquote>
        <pre>
set sa [<a href="scrollarea.html#synopsis">scrollutil::scrollarea</a> ...]
set ss [<a href="#synopsis">scrollutil::scrollsync</a> $sa.ss ...]
$sa <a href="scrollarea.html#setwidget">setwidget</a> $ss

set lb1 [listbox $ss.lb1 ...]
set lb2 [listbox $ss.lb2 ...]
$ss <a href="#setwidgets">setwidgets</a> [list $lb1 $lb2]

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

pack $sa -expand yes -fill both
</pre>
      </blockquote>
    </dd>

    <dt id="std_options"><b>STANDARD OPTIONS</b></dt>

    <dd>
      <pre>
<b>-background   -highlightbackground  -relief
-borderwidth  -highlightcolor       -xscrollcommand
-cursor       -highlightthickness   -yscrollcommand</b>
</pre>
    </dd>

    <dd>See the <b>options</b> manual entry for details on the standard Tk
    widget options.&nbsp; The <code><b>-background</b></code>,
    <code><b>-highlightbackground</b></code>,
    <code><b>-highlightcolor</b></code>, and
    <code><b>-highlightthickness</b></code> options are only supported by the
    Scrollutil package, but not by Scrollutil_tile.&nbsp; They have the same
    default values as the options of the same names for Tk frame widgets.&nbsp;
    The default values of the remaining standard options are:</dd>

    <dd>
      <pre>
<b>-borderwidth</b> 0 <b>-cursor</b> "" <b>-relief flat</b> <b>-xscrollcommand</b> "" <b>-yscrollcommand</b> ""
</pre>
    </dd>

    <dt id="widget_options"><b>WIDGET-SPECIFIC OPTIONS</b></dt>

    <dd id="takefocus">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
          <td><code><b>-takefocus</b></code></td>
        </tr>

        <tr>
          <td>Database Name:</td>
          <td><code><b>&nbsp;takeFocus</b></code></td>
        </tr>

        <tr>
          <td>Database Class:</td>
          <td><code><b>&nbsp;TakeFocus</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>This option determines whether the scrollsync widget accepts the
        focus during keyboard traversal.&nbsp; It is almost identical to the
        standard option of the same name (see the <b>options</b> manual entry
        for details).&nbsp; The only difference is that not the scrollsync
        widget itself but the first element of the widget list passed to the
        <code><b><a href="#setwidgets">setwidgets</a></b></code> subcommand of
        the associated Tcl command will receive the focus during keyboard
        traversal with the standard keys (<code>Tab</code> and
        <code>Shift-Tab</code>).&nbsp; The default is <code>0</code>, being
        that a scrollsync widget is esentially a frame containing the
        above-mentioned widgets.</p>
      </blockquote>
    </dd>

    <dt id="widget_command"><b>WIDGET COMMAND</b></dt>

    <dd>
      The <code><b>scrollutil::scrollsync</b></code> command creates a new Tcl
      command whose name is <code><i>pathName</i></code>.&nbsp; This command
      may be used to invoke various operations on the widget.&nbsp; It has the
      following general form:

      <blockquote>
        <pre>
<i>pathName</i> <i>option</i> ?<i>arg</i> <i>arg</i> ...?
</pre>
      </blockquote>
    </dd>

    <dd><code><i>option</i></code> and the <code><i>arg</i></code>s determine
    the exact behavior of the command.&nbsp; The following commands are
    possible for scrollsync widgets:</dd>

    <dd>
      <dl>
        <dt class="tm" id="cget"><code><i>pathName</i> <b>cget</b>
        <i>option</i></code></dt>

        <dd>Returns the current value of the configuration option given by
        <code><i>option</i></code>, which may have any of the values accepted
        by the <code><b>scrollutil::scrollsync</b></code> command.</dd>

        <dt class="tm" id="configure"><code><i>pathName</i> <b>configure</b>
        ?<i>option</i>? ?<i>value</i> <i>option</i> <i>value</i>
        ...?</code></dt>

        <dd>Queries or modifies the configuration options of the widget.&nbsp;
        If no <code><i>option</i></code> is specified, the command returns a
        list describing all of the available options for
        <code><i>pathName</i></code> (see <code><b>Tk_ConfigureInfo</b></code>
        for information on the format of this list).&nbsp; If
        <code><i>option</i></code> is specified with no
        <code><i>value</i></code>, 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 <code><i>option</i></code> is
        specified).&nbsp; If one or more
        <code><i>option</i></code>-<code><i>value</i></code> 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.&nbsp; <code><i>option</i></code> may have any of the values
        accepted by the <code><b>scrollutil::scrollsync</b></code>
        command.</dd>

        <dt class="tm" id="setwidgets"><code><i>pathName</i> <b>setwidgets</b>
        <i>widgetList</i></code></dt>

        <dd>Sets the widgets in whose windows the view's position is to be kept
        in sync.&nbsp; The <code><i>widgetList</i></code> argument must be a
        valid list consisting of path names of existing widgets.&nbsp; Whenever
        the horizontal/vertical position of the view in the window of one of
        the horizontally/vertically scrollable widgets contained in this list
        changes, the view in the windows of all the other
        horizontally/vertically scrollable elements of the list will be
        automatically adjusted accordingly, thus making sure that the view's
        position in these windows is kept in sync.&nbsp; The return value is
        the argument passed to the previous successful invocation of this
        subcommand, or an empty list if there was no successful
        <code><b>setwidgets</b></code> invocation before.</dd>

        <dd class="tm"><b>REMARK:</b>&nbsp; When one of the widgets whose path
        name is contained in <code><i>widgetList</i></code> gets destroyed,
        that widget is automatically removed from the internal list of widgets
        in whose windows the view's position is kept in sync.</dd>

        <dt class="tm" id="widgets"><code><i>pathName</i>
        <b>widgets</b></code></dt>

        <dd>Returns the argument passed to the most recent successful
        invocation of the <code><b><a href=
        "#setwidgets">setwidgets</a></b></code> subcommand, or an empty list if
        there was no successful invocation of that subcommand yet.</dd>

        <dt class="tm" id="xview"><code><i>pathName</i> <b>xview</b>
        ?<i>args</i>?</code></dt>

        <dd><code><i>pathName</i> <b>xview</b></code></dd>

        <dd><code><i>pathName</i> <b>xview moveto</b>
        <i>fraction</i></code></dd>

        <dd><code><i>pathName</i> <b>xview scroll</b> <i>number</i>
        <b>units</b>|<b>pages</b></code></dd>

        <dd class="tm">This command passes its arguments to the
        <code><b>xview</b></code> command of the current <b>master widget for
        the x axis</b> and returns the result of that command invocation.&nbsp;
        The master widget for the x axis is the element of the widget list
        passed to the <code><b><a href="#setwidgets">setwidgets</a></b></code>
        subcommand having the smallest relative view width among the
        horizontally scrollable widgets in that list, i.e., the least
        difference between the last and first elements of the two-element list
        returned by its <code><b>xview</b></code> command.&nbsp; This master
        widget can vary during program execution (in case of text widgets it
        can even change depending on the current vertical view position).</dd>

        <dt class="tm" id="yview"><code><i>pathName</i> <b>yview</b>
        ?<i>args</i>?</code></dt>

        <dd><code><i>pathName</i> <b>yview</b></code></dd>

        <dd><code><i>pathName</i> <b>yview moveto</b>
        <i>fraction</i></code></dd>

        <dd><code><i>pathName</i> <b>yview scroll</b> <i>number</i>
        <b>units</b>|<b>pages</b></code></dd>

        <dd class="tm">This command passes its arguments to the
        <code><b>yview</b></code> command of the current <b>master widget for
        the y axis</b> and returns the result of that command invocation.&nbsp;
        The master widget for the y axis is the element of the widget list
        passed to the <code><b><a href="#setwidgets">setwidgets</a></b></code>
        subcommand having the smallest relative view height among the
        vertically scrollable widgets in that list, i.e., the least difference
        between the last and first elements of the two-element list returned by
        its <code><b>yview</b></code> command.&nbsp; This master widget can
        vary during program execution.</dd>
      </dl>
    </dd>

    <dt class="tm" id="bindings"><b>BINDINGS</b></dt>

    <dd>When a new scrollsync widget is created, it has no default event
    bindings: scrollsync widgets are not intended to be interactive.</dd>

    <dt class="tm" id="keywords"><b>KEYWORDS</b></dt>

    <dd>scrollsync, widget, scrolling</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="getscrollsync">The <code><b>scrollutil::getscrollsync</b></code>
  Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>scrollutil::getscrollsync</code> &ndash; Query the scrollsync
    containing a given widget</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>scrollutil::gescrollsync</b> <i>widget</i>
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>Returns the path name of the scrollsync into which the widget given by
    the <code><i>widget</i></code> argument is embedded via the scrollsync's
    <code><b><a href="#setwidgets">setwidgets</a></b></code> subcommand, or an
    empty string if there is no such scrollsync widget.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>scrollsync, widget</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>
</body>
</html>

<!DOCTYPE html>
<html>
<head>
  <title>Scrollutil Programmer's Guide</title>

  <meta name="Author" content="Csaba Nemethi">
  <meta name="Keywords" content=
  "scrollarea, scrollsync, mouse wheel event, binding, event handling, scrolling, scrollable widget container, focus">

  <link rel="stylesheet" type="text/css" href="stylesheet.css">
</head>

<body>
  <div align="center">
    <h1>Scrollutil Programmer's Guide</h1>

    <h2>For Scrollutil Version 1.5</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:csaba.nemethi@t-online.de">csaba.nemethi@t-online.de</a>
    </address>
  </div>

  <hr>

  <h2 id="contents">Contents</h2>

  <h4><a href="#overview">Overview</a></h4>

  <ul>
    <li><a href="#ov_what">What Is Scrollutil?</a></li>

    <li><a href="#ov_get">How to Get It?</a></li>

    <li><a href="#ov_install">How to Install It?</a></li>

    <li><a href="#ov_use">How to Use It?</a></li>
  </ul>

  <h4><a href="#examples">Examples</a></h4>

  <ul>
    <li><a href="#ex_styleUtil">The Helper Script
    <code>styleUtil.tcl</code></a></li>

    <li><a href="#ex_ScrolledTablelist">A Scrolled tablelist Widget</a></li>

    <li><a href="#ex_ScrolledText">A Scrolled text Widget</a></li>

    <li><a href="#ex_SyncListboxes">Synchronizing Two listbox Widgets</a></li>

    <li><a href="#ex_SyncTablelists">Synchronizing Three tablelist
    Widgets</a></li>

    <li><a href="#ex_SuScrollableFrameDemo1">A Script Using a
    scrollutil::scrollableframe Widget</a></li>

    <li><a href="#ex_BwScrollableFrameDemo1">A Script Using a BWidget
    ScrollableFrame Widget</a></li>

    <li><a href="#ex_ScrolledFrameDemo1">A Script Using an
    iwidgets::scrolledframe Widget</a></li>

    <li><a href="#ex_SuScrollableFrameDemo2">A Script Using Two
    scrollutil::scrollableframe Widgets</a></li>

    <li><a href="#ex_BwScrollableFrameDemo2">A Script Using Two BWidget
    ScrollableFrame Widgets</a></li>

    <li><a href="#ex_ScrolledFrameDemo2">A Script Using Two
    iwidgets::scrolledframe Widgets</a></li>
  </ul>

  <div align="center">
    <p><a href="index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="overview">Overview</h2>

  <h3 id="ov_what">What Is Scrollutil?</h3>

  <p>Scrollutil is a library package for Tcl/Tk versions 8.0 or higher, written
  in pure Tcl/Tk code.&nbsp; It contains:</p>
  
  <ul>
    <li>the implementation of the <a href=
    "scrollarea.html"><b>scrollarea</b></a>, <a href=
    "scrollsync.html"><b>scrollsync</b></a>, and <a href=
    "scrollableframe.html"><b>scrollableframe</b></a> mega-widgets, including a
    general utility module for mega-widgets;</li>

    <li>the command <code><b><a href=
    "wheelEvent.html#add">scrollutil::addMouseWheelSupport</a></b></code>,
    which creates mouse wheel event bindings for a given binding tag.&nbsp;
    This command requires Tcl/Tk 8.4 or later;</li>

    <li>commands for <i>user-friendly</i> mouse wheel event handling in
    <b>scrollable widget containers</b> like scrollutil::scrollableframe,
    BWidget ScrollableFrame, and iwidgets::scrolledframe.&nbsp; These commands
    require Tcl/Tk versions 8.4 or higher on X11 and Mac OS X and Tk 8.6b2 or
    later on Windows;</li>

    <li>demo scripts illustrating the use of the Scrollutil package in
    connection with various scrollable widgets and the above-mentioned
    scrollable widget containers;</li>

    <li>this tutorial;</li>

    <li>reference pages in HTML format.</li>
  </ul>

  <p><b>The scrollutil::scrollarea mega-widget</b> greatly simplifies the
  creation of arbitrary scrolled widgets.&nbsp; It consists of a scrollable
  widget and two scrollbars connected with that widget.&nbsp; The display mode
  of each scrollbar can be <code>static</code>, <code>dynamic</code>, or
  <code>none</code>.&nbsp; 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 <a href=
  "https://www.nemethi.de/tablelist/">tablelist</a> widgets (this is freely
  configurable).</p>
  
  <p>The scrollutil::scrollarea widget is similar to BWidget ScrolledWindow and
  its snit-based equivalent widget::scrolledwindow, contributed by Jeffrey
  Hobbs and contained in tklib.&nbsp; The snit-based <a href=
  "http://web.tiscali.it/irrational/tcl/scrodget-2.1/">scrodget</a> package by
  Aldo Buratti and its TclOO-based equivalent <a href=
  "https://wiki.tcl-lang.org/page/A+Scrolled+Widget+implemented+with+TclOO">scrolledwidget</a>
  contributed by Johann Oberdorfer are further scrolled window implementations.
  However, <i>full</i> tablelist support is only provided by the scrollarea
  widget, which is free from external dependencies like BWidget, snit, or (for
  Tcl 8.5) TclOO.&nbsp; It is also free from the <a href=
  "https://wiki.tcl-lang.org/page/Scroll+bars+that+appear+only+when+needed">shimmering
  problem in connection with text widgets</a>, which the above-mentioned
  scrolled window implementations either share with the autoscroll package
  (contained in tklib) or circumvent in a suboptimal way.</p>

  <p><b>The scrollutil::scrollsync mega-widget</b> is designed for scrolling
  several widgets simultaneously.&nbsp; 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.&nbsp; This mega-widget is horizontally and vertically scrollable, hence
  it can be embedded into a scrollutil::scrollarea widget via the latter's
  <code>setwidget</code> subcommand.</p>

  <p><b>The scrollutil::scrollableframe mega-widget</b> is a scrollable widget
  container.&nbsp; It contains a content frame, whose dimensions are typically
  larger than those of the widget itself.&nbsp; 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.</p>
  
  <p>The scrollutil::scrollableframe widget is similar to BWidget
  ScrollableFrame and iwidgets::scrolledframe.&nbsp; However, unlike these
  widgets, which use a canvas for scrolling the content frame, it adjusts the
  view with the aid of the <code><b>place</b></code> geometry manager, just
  like the <code>scrolledframe::scrolledframe</code> command of the
  Scrolledframe package by Maurice Bredelet (ulis) and its optimized and
  enhanced version contributed by Keith Nash.&nbsp; For details on these
  commands see the wiki page</p>

  <blockquote>
    <address>
      <a href=
      "https://wiki.tcl-lang.org/page/A+scrolled+frame">https://wiki.tcl-lang.org/page/A+scrolled+frame</a>
    </address>
  </blockquote>

  <p>Scrollutil's canvas-free approach is more lightweight and integrates
  better in applications that use tile widgets.</p>

  <p>From the point of view of <b>the commands related to mouse wheel event
  handling</b> provided by the Scrollutil package, the scrollability of a
  widget or widget container window means that the associated Tcl command
  supports the&nbsp; <code>xview scroll <i>number</i> units</code>&nbsp;
  and&nbsp; <code>yview scroll <i>number</i> units</code>&nbsp;
  subcommands.&nbsp; 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.</p>

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

  <ul>
    <li>Create mouse wheel event bindings for the binding tag
    <code>"all"</code> or for the toplevel widgets (including <code>"."</code>)
    having scrollable widget containers, by invoking the <code><a href=
    "wheelEvent.html#create">scrollutil::createWheelEventBindings</a></code>
    command.&nbsp; In addition, register your scrollable widget containers for
    scrolling via these bindings with the aid of the <code><a href=
    "wheelEvent.html#enable">scrollutil::enableScrollingByWheel</a></code>
    command.&nbsp; The above-mentioned bindings handle the mouse wheel events
    by scrolling the (innermost) registered scrollable widget container that is
    an ascendant of the widget under the pointer and is contained in the
    latter's toplevel.</li>

    <li class="tm">Invoke the <code><a href=
    "wheelEvent.html#adapt">scrollutil::adaptWheelEventHandling</a></code>
    command for those widgets contained in registered scrollable widget
    containers that have mouse wheel event (class) bindings.&nbsp; This step
    eliminates the annoying and often dangerous double-handling effect, by
    modifying the mouse wheel event handling as follows:&nbsp; 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 <code>scrollutil::createWheelEventBindings</code>
    command.&nbsp; Without this step the mouse wheel events would scroll both
    the listbox, text, ttk::treeview, or tablelist widget under the pointer
    <i>and</i> the widget container to whose descendants the latter belongs, or
    they would select the next/previous value in the ttk::combobox or
    ttk::spinbox under the pointer <i>in addition to</i> scrolling the widget
    container.</li>

    <li class="tm">For some widgets it can be desirable to make the focus check
    within this modified event handling less restrictive.&nbsp; For example, if
    the widget under the pointer is an entry component of a <a href=
    "https://www.nemethi.de/mentry/">mentry</a> of type <code>"Date"</code>,
    <code>"Time"</code>, <code>"DateTime"</code>, <code>"IPAddr"</code>, or
    <code>"IPv6Addr"</code> and the focus is on any of its siblings, then the
    mouse wheel events sent to this entry should be handled by the entry widget
    itself rather than scrolling the widget container that is an ascendant of
    the mentry.&nbsp; The <code><a href=
    "wheelEvent.html#setFocusCkWin">scrollutil::setFocusCheckWindow</a></code>
    command covers exactly cases like this.</li>
  </ul>

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

  <h3 id="ov_get">How to Get It?</h3>

  <p>Scrollutil is available for free download from the Web page</p>

  <blockquote>
    <address>
      <a href="https://www.nemethi.de">https://www.nemethi.de</a>
    </address>
  </blockquote>

  <p>The distribution file is <code>scrollutil1.5.tar.gz</code> for UNIX and
  <code>scrollutil1_5.zip</code> for Windows.&nbsp; 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.</p>

  <p>Scrollutil is also included in tklib, which has the address</p>

  <blockquote>
    <address>
      <a href="https://core.tcl.tk/tklib">https://core.tcl.tk/tklib</a>
    </address>
  </blockquote>

  <h3 id="ov_install">How to Install It?</h3>

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

  <p>To install Scrollutil <i>on UNIX</i>, <code>cd</code> to the desired
  directory and unpack the distribution file
  <code>scrollutil1.5.tar.gz</code>:</p>

  <blockquote>
    <pre>
gunzip -c scrollutil1.5.tar.gz | tar -xf -
</pre>
  </blockquote>

  <p>On most UNIX systems this can be replaced with</p>

  <blockquote>
    <pre>
tar -zxf scrollutil1.5.tar.gz
</pre>
  </blockquote>

  <p>Both commands will create a directory named <code>scrollutil1.5</code>,
  with the subdirectories <code>demos</code>, <code>doc</code>, and
  <code>scripts</code>.</p>

  <p><i>On Windows</i>, use WinZip or some other program capable of unpacking
  the distribution file <code>scrollutil1_5.zip</code> into the directory
  <code>scrollutil1.5</code>, with the subdirectories <code>demos</code>,
  <code>doc</code>, and <code>scripts</code>.</p>

  <p>Notice that in tklib the Scrollutil <code>demos</code> directory is
  replaced with the subdirectory <code>scrollutil</code> of the
  <code>examples</code> directory.&nbsp; Please take this into account when
  reading the <a href="#examples">examples</a> below.</p>

  <h3 id="ov_use">How to Use It?</h3>

  <p>The Scrollutil distribution provides two packages, called
  <b>Scrollutil</b> and <b>Scrollutil_tile</b>.&nbsp; The main difference
  between the two is that Scrollutil_tile enables the tile-based,
  theme-specific appearance of scrollarea, scrollsync, and scrollableframe
  widgets; this package requires Tcl/Tk 8.4 or higher and tile 0.6 or
  higher.&nbsp; It is not possible to use both packages in one and the same
  application, because both are implemented in the same <code>scrollutil</code>
  namespace and provide identical commands.</p>

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

  <blockquote>
    <pre>
package require scrollutil ?<i>version</i>?
package require Scrollutil ?<i>version</i>?
</pre>
  </blockquote>

  <p>You can use either one of the two statements above because the file
  <code>scrollutil.tcl</code> contains both lines</p>

  <blockquote>
    <pre>
package provide scrollutil ...
package provide Scrollutil ...
</pre>
  </blockquote>

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

  <blockquote>
    <pre>
package require scrollutil_tile ?<i>version</i>?
package require Scrollutil_tile ?<i>version</i>?
</pre>
  </blockquote>

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

  <blockquote>
    <pre>
package provide scrollutil_tile ...
package provide Scrollutil_tile ...
</pre>
  </blockquote>

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

  <p>Since the packages Scrollutil and Scrollutil_tile are implemented in the
  <code>scrollutil</code> namespace, you must either invoke the</p>

  <blockquote>
    <pre>
namespace import scrollutil::<i>pattern</i> ?scrollutil::<i>pattern ...</i>?
</pre>
  </blockquote>

  <p>command to import the <i>procedures</i> you need, or use qualified names
  like <code>scrollutil::scrollarea</code>.&nbsp; In the <a href=
  "#examples">examples</a> below we have chosen the latter approach.</p>

  <p>To access Scrollutil <i>variables</i>, you <i>must</i> use qualified
  names.&nbsp; There are only three Scrollutil variables that are designed to
  be accessed outside the namespace <code>scrollutil</code>:</p>

  <ul>
    <li>The variable <code>scrollutil::version</code> holds the current version
    number of the Scrollutil package.</li>

    <li>The variable <code>scrollutil::library</code> holds the location of the
    Scrollutil installation directory.</li>

    <li>The read-only variable <code>scrollutil::usingTile</code> has the value
    <code>0</code> in the package Scrollutil and the value <code>1</code> in
    Scrollutil_tile.</li>
  </ul>

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

  <blockquote>
    <pre>
package require Tk 8.4
if {$::tk_version &lt; 8.5 || [regexp {^8\.5a[1-5]$} $::tk_patchLevel]} {
    package require tile 0.6
}
</pre>
  </blockquote>

  <p>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.</p>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="examples">Examples</h2>

  <h3 id="ex_styleUtil">The Helper Script <code>styleUtil.tcl</code></h3>

  <p>All the examples in the <code>demos</code> directory use tile (ttk)
  widgets and contain the line</p>

  <blockquote>
    <pre>
source styleUtil.tcl
</pre>
  </blockquote>

  <p>The script <code>styleUtil.tcl</code> patches a few ttk widget styles and
  defines the style <code>Small.Toolbutton</code>.&nbsp; In addition, on X11 it
  sets the theme to a slightly patched variant of the <code>clam</code>
  theme (having smaller ttk::button widgets as well as ttk::treeview and
  tablelist headers).</p>
  
  <p>The patch for the style <code>TCombobox</code> makes sure that the
  (readonly) ttk::combobox widgets of the themes <code>alt</code>,
  <code>clam</code>, and <code>default</code> will show whether they have the
  focus.&nbsp; This basic requirement, which makes the keyboard navigation more
  user-friendly, is already fulfilled by the themes <code>vista</code>,
  <code>xpnative</code>, and <code>aqua</code>.</p>

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

  <h3 id="ex_ScrolledTablelist">A Scrolled tablelist Widget</h3>

  <p>This example shows how you can greatly simplify the creation of a scrolled
  tablelist by using a <a href="scrollarea.html">scrollarea</a> widget.</p>

  <p>The file <code>ScrolledTablelist1.tcl</code> in the <code>demos</code>
  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:</p>

  <blockquote>
    <img src="ScrolledTablelist.png" alt="ScrolledTablelist" width="480"
    height="337">
  </blockquote>

  <p>The script achieves these requirements using traditional scrollbar
  management, which is shown below in <span class="red">red</span> color:</p>

  <blockquote>
    <pre>
package require Tk 8.5
package require tablelist_tile 6.3
source styleUtil.tcl

wm title . "Scrolled Tablelist"

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

. . .

<span class="cmt">#
# Manage the widgets within the frame
#</span>
<span class="red">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</span>

<span class="cmt">#
# Manage the frame
#</span>
pack $frm -expand yes -fill both -padx 10 -pady 10
pack $f   -expand yes -fill both
</pre>
  </blockquote>

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

  <blockquote>
    <pre>
package require Tk 8.5
package require tablelist_tile 6.5
<span class="red">package require scrollutil_tile</span>
source styleUtil.tcl

wm title . "Scrolled Tablelist"

<span class="cmt">#
# Create the tablelist within a scrollarea
#</span>
set f  [ttk::frame .f]
<span class="red">set sa [scrollutil::scrollarea $f.sa]</span>
set tbl $sa.tbl
tablelist::tablelist $tbl ...
. . .
<span class="red">$sa setwidget $tbl</span>

. . .

<span class="cmt">#
# Manage the scrollarea
#</span>
pack $sa -expand yes -fill both -padx 10 -pady 10
pack $f  -expand yes -fill both
</pre>
  </blockquote>

  <h3 id="ex_ScrolledText">A Scrolled text Widget</h3>

  <p>The file <code>ScrolledText.tcl</code> in the <code>demos</code> directory
  shows how the <a href="scrollarea.html">scrollarea</a> widget circumvents the
  potential shimmering effect in connection with text widgets.</p>

  <blockquote>
    <img src="ScrolledText.png" alt="ScrolledText" width="401" height="338">
  </blockquote>

  <p>Here is the relevant code, in which the lines related to the scrollarea
  widget are shown in <span class="red">red</span> color:</p>

  <blockquote>
    <pre>
<span class="red">package require scrollutil_tile</span>
source styleUtil.tcl

wm title . "Scrolled Text"

<span class="cmt">#
# Create a text widget within a scrollarea
#</span>
set f  [ttk::frame .f]
<span class="red">set sa [scrollutil::scrollarea $f.sa -lockinterval 10]</span>
set txt [text $sa.txt -font TkFixedFont -width 49 -height 12 \
         -spacing1 2 -spacing3 2 -wrap none]
<span class="red">$sa setwidget $txt</span>

<span class="cmt">#
# Populate the text widget and set the background color of line #25 to red
#</span>
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

. . .

<span class="cmt">#
# Manage the scrollarea
#</span>
pack $sa -expand yes -fill both -padx 10 -pady 10
pack $f  -expand yes -fill both

<span class="cmt">#
# Adjust the vertical view in the text window
# so that line #25 becomes the bottom line
#</span>
tkwait visibility $txt
after 100 [list $txt yview 14.0]
</pre>
  </blockquote>

  <p>The script creates a text widget <code>$txt</code> 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.&nbsp; This line has 50
  characters, hence it doesn't fit completely into the window, whose width is
  49 characters.&nbsp; Consequently, the command&nbsp; <code>$txt
  xview</code>&nbsp; will return the list&nbsp; <code>{0.0 0.98}</code>,&nbsp;
  hence the scrollarea's horizontal scrollbar will be mapped and will obscure
  most part of the bottom line.&nbsp; Since this line has <code>red</code>
  background, it is easy to see how much of it sticks out above the upper edge
  of the scrollbar.</p>

  <p>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.&nbsp; 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&nbsp; <code>$txt xview</code>&nbsp; will
  return&nbsp; <code>{0.0 1.0}</code>.&nbsp; Normally, this would cause the
  horizontal scrollbar to be unmapped.&nbsp; However, that would make line #25
  to the bottom line, thus causing the horizontal scrollbar to be mapped
  again.&nbsp; 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.&nbsp; In other words, the
  horizontal scrollbar would get mapped and unmapped in an endless loop, giving
  rise to an annoying flickering effect.&nbsp; The built-in locking mechanism
  of the scrollarea widget guards against such potential endless loops.&nbsp;
  To make sure that the locking will work as expected, we have set the
  <code><a href="scrollarea.html#lockinterval">-lockinterval</a></code>
  scrollarea option to <code>10</code> (recall that the default value is
  <code>1</code>).</p>

  <h3 id="ex_SyncListboxes">Synchronizing Two listbox Widgets</h3>

  <p>The file <code>SyncListboxes.tcl</code> in the <code>demos</code>
  directory creates two listboxes within a <a href=
  "scrollsync.html">scrollsync</a> widget, which in turn is embedded into a
  <a href="scrollarea.html">scrollarea</a>.</p>

  <blockquote>
    <img src="SyncListboxes.png" alt="SyncListboxes" width="320" height="305">
  </blockquote>

  <p>Here is the relevant code, in which the lines related to the scrollarea
  and scrollsync widgets are shown in <span class="red">red</span> color:</p>

  <blockquote>
    <pre>
<span class="red">package require scrollutil_tile</span>
source styleUtil.tcl

wm title . "European Countries"

. . .

set f  [ttk::frame .f]

. . .

<span class="cmt">#
# Create a scrollsync widget within a scrollarea
#</span>
<span class="red">set sa [scrollutil::scrollarea $f.sa]
set ss [scrollutil::scrollsync $sa.ss]
$sa setwidget $ss</span>

<span class="cmt">#
# Populate the scrollsync widget with two listboxes
#</span>

. . .

set lb1 [listbox $ss.lb1 -activestyle none -highlightthickness 0 -width 16]
set lb2 [listbox $ss.lb2 -activestyle none -highlightthickness 0 -width 16]
<span class="red">$ss setwidgets [list $lb1 $lb2]</span>

. . .

grid $lb1 $lb2 -sticky news -padx {0 2}
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 10 -pady {2 10}
pack $f  -expand yes -fill both

. . .
</pre>
  </blockquote>

  <h3 id="ex_SyncTablelists">Synchronizing Three tablelist Widgets</h3>

  <p>The file <code>SyncTablelists.tcl</code> in the <code>demos</code>
  directory creates three tablelists within a <a href=
  "scrollsync.html">scrollsync</a> widget, which in turn is embedded into a
  <a href="scrollarea.html">scrollarea</a>.</p>

  <blockquote>
    <img src="SyncTablelists.png" alt="SyncTablelists" width="548" height=
    "326">
  </blockquote>

  <p>The relevant code is similar to the one shown in the <a href=
  "#ex_SyncListboxes">previous example</a>:</p>

  <blockquote>
    <pre>
package require tablelist_tile
<span class="red">package require scrollutil_tile</span>
source styleUtil.tcl

wm title . "Synchronized Tablelists"

. . .

set f  [ttk::frame .f]

. . .

<span class="cmt">#
# Create a scrollsync widget within a scrollarea
#</span>
<span class="red">set sa [scrollutil::scrollarea $f.sa]
set ss [scrollutil::scrollsync $sa.ss]
$sa setwidget $ss</span>

<span class="cmt">#
# Populate the scrollsync widget with three tablelists
#</span>

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"]
    }
}
<span class="red">$ss setwidgets [list $tbl1 $tbl2 $tbl3]</span>

grid $tbl1 $tbl2 $tbl3 -sticky news -padx {0 2}
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 10 -pady {2 10}
pack $f  -expand yes -fill both

. . .
</pre>
  </blockquote>

  <p>Notice that column #1 of the three tablelist widgets is 40, 60, and 80
  characters wide, respectively.&nbsp; 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.</p>

  <h3 id="ex_SuScrollableFrameDemo1">A Script Using a
  scrollutil::scrollableframe Widget</h3>

  <p>The file <code>SuScrollableFrmDemo1.tcl</code> in the <code>demos</code>
  directory creates a <a href=
  "scrollableframe.html">scrollutil::scrollableframe</a> widget embedded into a
  <a href="scrollarea.html">scrollarea</a>, creates mouse wheel event bindings
  for the binding tag <code>"all"</code> with the aid of the <code><a href=
  "wheelEvent.html#create">scrollutil::createWheelEventBindings</a></code>
  command, and invokes the <code><a href=
  "wheelEvent.html#enable">scrollutil::enableScrollingByWheel</a></code>
  command for this scrollableframe, thus registering the latter for scrolling
  by these bindings.&nbsp; After that it 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 <code>Small.Toolbutton</code>
  (created by using the procedure <code>createToolbutton</code>, implemented in
  the file <code><a href="#ex_styleUtil">styleUtil.tcl</a></code>) for the less
  patient users, displaying the text "Resolve".</p>

  <blockquote>
    <img src="ScrollableFrmDemo1.png" alt="ScrollableFrmDemo1" width="407"
    height="373">
  </blockquote>

  <p>Here is the relevant code:</p>

  <blockquote>
    <pre>
<span class="red">package require scrollutil_tile</span>
source styleUtil.tcl

wm title . "European Capitals Quiz"

<span class="cmt">#
# Create a scrollableframe within a scrollarea
#</span>
set f  [ttk::frame .f]
<span class="red">set sa [scrollutil::scrollarea $f.sa]
set sf [scrollutil::scrollableframe $sa.sf]
$sa setwidget $sf</span>

<span class="cmt">#
# Create mouse wheel event bindings for the binding tag "all" and
# register the scrollableframe for scrolling by these bindings
#</span>
<span class="red">scrollutil::createWheelEventBindings all
scrollutil::enableScrollingByWheel $sf</span>

<span class="cmt">#
# Get the content frame and populate it
#</span>

<span class="red">set cf [$sf contentframe]</span>

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

    <span class="cmt">#
    # Make the keyboard navigation more user-friendly
    #</span>
    bind $w &lt;&lt;TraverseIn&gt;&gt; [list <span class="red">$sf see %W</span>]

    <span class="cmt">#
    # Adapt the handling of the mouse wheel events for the ttk::combobox widget
    #</span>
    <span class="red">scrollutil::adaptWheelEventHandling $w</span>

    . . .

    incr row
}

. . .
</pre>
  </blockquote>

  <p>We make the keyboard navigation more user-friendly with the aid of the
  <code><a href="scrollableframe.html#see">see</a></code> subcommand of the
  scrollableframe widget when handling the
  <code>&lt;&lt;TraverseIn&gt;&gt;</code> virtual event for the ttk::combobox
  and (not shown above) ttk::button widgets.&nbsp; In addition, we invoke the
  <code><a href=
  "wheelEvent.html#adapt">scrollutil::adaptWheelEventHandling</a></code>
  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.&nbsp; 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.</p>

  <p>With this script you can also test the scanning in the
  scrollableframe:&nbsp; 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.</p>

  <h3 id="ex_BwScrollableFrameDemo1">A Script Using a BWidget ScrollableFrame
  Widget</h3>

  <p>The file <code>BwScrollableFrmDemo1.tcl</code> in the <code>demos</code>
  directory creates a BWidget ScrollableFrame embedded into a <a href=
  "scrollarea.html">scrollarea</a> widget, creates mouse wheel event bindings
  for the binding tag <code>"all"</code> with the aid of the <code><a href=
  "wheelEvent.html#create">scrollutil::createWheelEventBindings</a></code>
  command, and invokes the <code><a href=
  "wheelEvent.html#enable">scrollutil::enableScrollingByWheel</a></code>
  command for this ScrollableFrame, thus registering the latter for scrolling
  by these bindings.&nbsp; After that it populates the content frame of the
  ScrollableFrame with the same widgets as
  <code>SuScrollableFrmDemo1.tcl</code> in the <a href=
  "#ex_SuScrollableFrameDemo1">previous example</a>.</p>

  <p>Here is the relevant code:</p>

  <blockquote>
    <pre>
package require BWidget
Widget::theme yes
<span class="red">package require scrollutil_tile</span>
source styleUtil.tcl

wm title . "European Capitals Quiz"

<span class="cmt">#
# Create a ScrollableFrame within a scrollarea
#</span>
set f  [ttk::frame .f]
<span class="red">set sa [scrollutil::scrollarea $f.sa]</span>
set sf [ScrollableFrame $sa.sf]
<span class="red">$sa setwidget $sf</span>

. . .

<span class="cmt">#
# Create mouse wheel event bindings for the binding tag "all" and
# register the ScrollableFrame for scrolling by these bindings
#</span>
<span class="red">scrollutil::createWheelEventBindings all
scrollutil::enableScrollingByWheel $sf</span>

<span class="cmt">#
# Get the content frame and populate it
#</span>

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

    <span class="cmt">#
    # Make the keyboard navigation more user-friendly
    #</span>
    bind $w &lt;&lt;TraverseIn&gt;&gt; [list $sf see %W]

    <span class="cmt">#
    # Adapt the handling of the mouse wheel events for the ttk::combobox widget
    #</span>
    <span class="red">scrollutil::adaptWheelEventHandling $w</span>

    . . .

    incr row
}

. . .
</pre>
  </blockquote>

  <h3 id="ex_ScrolledFrameDemo1">A Script Using an iwidgets::scrolledframe
  Widget</h3>

  <p>The file <code>ScrolledFrmDemo1.tcl</code> in the <code>demos</code>
  directory creates an iwidgets::scrolledframe widget, creates mouse wheel
  event bindings for the binding tag <code>"all"</code> with the aid of the
  <code><a href=
  "wheelEvent.html#create">scrollutil::createWheelEventBindings</a></code>
  command, and invokes the <code><a href=
  "wheelEvent.html#enable">scrollutil::enableScrollingByWheel</a></code>
  command for this scrolledframe, thus registering the latter for scrolling by
  these bindings.&nbsp; After that it populates the content frame of the
  scrolledframe with the same widgets as <code>SuScrollableFrmDemo1.tcl</code>
  and <code>BwScrollableFrmDemo1.tcl</code> in the two previous examples.</p>

  <p>Here is the relevant code:</p>

  <blockquote>
    <pre>
if {[catch {package require iwidgets} result1] != 0 &&
    [catch {package require Iwidgets} result2] != 0} {
    error "$result1; $result2"
}
source scrolledwidgetPatch.itk                  ;<span class="cmt"># adds ttk::scrollbar widgets</span>
<span class="red">package require scrollutil_tile</span>
source styleUtil.tcl

wm title . "European Capitals Quiz"

. . .

<span class="cmt">#
# Create a scrolledframe
#</span>
set f  [ttk::frame .f]
set sf [iwidgets::scrolledframe $f.sf -borderwidth 1 -relief sunken \
        -scrollmargin 0]
. . .

<span class="cmt">#
# Create mouse wheel event bindings for the binding tag "all"
# and register the scrolledframe for scrolling by these bindings
#</span>
<span class="red">scrollutil::createWheelEventBindings all
scrollutil::enableScrollingByWheel $sf</span>

<span class="cmt">#
# Get the content frame and populate it
#</span>

set cf [$sf childsite]
. . .

<i>&lt;exactly as in the two previous examples, except the stuff related to keyboard navigation&gt;</i>

. . .
</pre>
  </blockquote>

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

  <h3 id="ex_SuScrollableFrameDemo2">A Script Using Two
  scrollutil::scrollableframe Widgets</h3>

  <p>The script <code>SuScrollableFrmDemo2.tcl</code> in the <code>demos</code>
  directory creates a <a href=
  "scrollableframe.html">scrollutil::scrollableframe</a> widget embedded into a
  <a href="scrollarea.html">scrollarea</a> and then <code>source</code>s the
  script <code>SuScrollableFrmContent.tcl</code>, which populates the content
  frame of the scrollableframe with the following widgets:</p>

  <ul>
    <li>a series of ttk::label widgets;</li>

    <li>a scrolled text widget <code>$txt</code> within a scrollarea;</li>

    <li>a scrolled listbox widget <code>$lb</code> within a scrollarea;</li>

    <li>a ttk::combobox widget <code>$cb</code>;</li>

    <li>a ttk::spinbox widget <code>$sb</code>;</li>

    <li>a ttk::entry widget <code>$e</code>;</li>

    <li>a ttk::separator widget;</li>

    <li>a mentry widget <code>$me</code> of type <code>"Date"</code>;</li>

    <li>a scrolled tablelist widget <code>$tbl</code> within a scrollarea;</li>

    <li>a scrolled ttk::treeview widget <code>$tv</code> within a
    scrollarea.</li>
  </ul>

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

  <blockquote>
    <img src="ScrollableFrmDemo2.png" alt="ScrollableFrmDemo2" width="605"
    height="516">
  </blockquote>

  <p>Here is the relevant code:</p>

  <blockquote>
    <pre>
package require Tk 8.5.9                        ;<span class=
"cmt"># for ttk::spinbox</span>
package require mentry_tile 3.2                 ;<span class=
"cmt"># for mouse wheel support</span>
package require tablelist_tile 6.5              ;<span class=
"cmt"># for -(x|y)mousewheelwindow</span>
                                                ;<span class=
 "cmt"># and scrollutil::scrollarea</span>
<span class="red">package require scrollutil_tile</span>
source styleUtil.tcl

wm title . "Scrollutil Demo"

<span class="cmt">#
# Create a scrollableframe within a scrollarea
#</span>
set tf [ttk::frame .tf]
<span class="red">set sa [scrollutil::scrollarea $tf.sa]
set sf [scrollutil::scrollableframe $sa.sf]
$sa setwidget $sf</span>

<span class="cmt">#
# Get the content frame and populate it
#</span>
<span class="red">set cf [$sf contentframe]</span>
source SuScrollableFrmContent.tcl

<span class="cmt">#
# Make the keyboard navigation more user-friendly
#</span>
foreach w [list $cb $sb $e $me] {
    bind $w &lt;&lt;TraverseIn&gt;&gt; [list <span class="red">$sf see %W</span>]
}
foreach w [list $txt $lb $tbl $tv] {
    bind $w &lt;&lt;TraverseIn&gt;&gt; [list seeScrollarea $sf %W]
}
proc seeScrollarea {sf w} { <span class="red">$sf see [scrollutil::getscrollarea $w]</span> }
</pre>
  </blockquote>

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

  <p>Here is the additional stuff related to the mouse wheel events, using the
  Scrollutil commands described in the <a href="#ov_what">What Is
  Scrollutil?</a> section:</p>

  <blockquote>
    <pre>
<span class="cmt">#
# Create mouse wheel event bindings for the binding tag "all" and
# register the scrollableframe for scrolling by these bindings
#</span>
<span class="red">scrollutil::createWheelEventBindings all
scrollutil::enableScrollingByWheel $sf</span>

<span class="cmt">#
# 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"
#</span>
set entryList [$me entries]
<span class="red">scrollutil::adaptWheelEventHandling $txt $lb $cb $sb $tbl $tv {*}$entryList</span>

<span class="cmt">#
# For the entry components of the mentry widget
# set the "focus check window" to the mentry
#</span>
<span class="red">scrollutil::setFocusCheckWindow {*}$entryList $me</span>
</pre>
  </blockquote>

  <p>Notice that we have passed, among others, the tablelist widget to the
  <code><a href=
  "wheelEvent.html#adapt">scrollutil::adaptWheelEventHandling</a></code>
  command.&nbsp; This will only work for Tablelist versions 6.4 and later,
  because the command handles tablelist widgets by setting their
  <code>-xmousewheelwindow</code> and <code>-ymousewheelwindow</code> options
  to the path name of the containing toplevel window, and these options were
  introduced in Tablelist version 6.4.&nbsp; (For earlier Tablelist versions
  the command silently ignores any tablelist widget passed to it as
  argument.)</p>

  <p>As already mentioned, in the file <code>SuScrollableFrmContent.tcl</code>
  the scrolled text, listbox, tablelist, and ttk::treeview widgets are created
  within <a href="scrollarea.html">scrollarea</a> widgets:</p>

  <blockquote>
    <pre>
<span class="red">set _sa [scrollutil::scrollarea ...]</span>
set txt [text $_sa.txt -font TkFixedFont -width 73]
<span class="red">scrollutil::addMouseWheelSupport $txt
$_sa setwidget $txt</span>
grid $_sa ...

. . .

<span class="red">set _sa [scrollutil::scrollarea ...]</span>
set lb [listbox $_sa.lb -width 0]
<span class="red">$_sa setwidget $lb</span>
grid $_sa ...

. . .

<span class="red">set _sa [scrollutil::scrollarea ...]</span>
set tbl [tablelist::tablelist $_sa.tbl ...]
. . .
<span class="red">$_sa setwidget $tbl</span>
grid $_sa ...

. . .

<span class="red">set _sa [scrollutil::scrollarea ... -borderwidth 0]</span>
set tv [ttk::treeview $_sa.tv ...]
. . .
<span class="red">$_sa setwidget $tv</span>
grid $_sa ...
</pre>
  </blockquote>

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

  <p>For our text widget we prefer a mouse wheel event handling that scrolls
  the widget by lines rather than pixels, as done by the <code>Text</code>
  class bindings in Tk 8.5 and later; we achieve this by passing the path name
  <code>$txt</code> to the <code><a href=
  "wheelEvent.html#add">scrollutil::addMouseWeelSupport</a></code> command.</p>

  <p>The file <code>SuScrollableFrmContent.tcl</code> contains also the
  implementation of the procedure <code>configTablelist</code>, associated with
  the "Configure Tablelist Widget" button as the value of its
  <code>-command</code> option.&nbsp; This procedure opens a toplevel window
  that contains a <a href=
  "scrollableframe.html">scrollutil::scrollableframe</a> widget created
  with the&nbsp; <code><a href=
  "scrollableframe.html#fitcontentwidth">-fitcontentwidth</a> yes</code>&nbsp;
  setting within a <a href="scrollarea.html">scrollarea</a> and invokes the
  <code><a href=
  "wheelEvent.html#enable">scrollutil::enableScrollingByWheel</a></code>
  command for this scrollableframe, thus registering the latter for scrolling
  by the already created mouse wheel event bindings for the binding tag
  <code>"all"</code>.&nbsp; 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.&nbsp; The procedure handles the
  <code>&lt;&lt;TraverseIn&gt;&gt;</code> virtual event sent to one of these
  widgets with the aid of the scrollableframe's <code><a href=
  "scrollableframe.html#see">see</a></code> subcommand.&nbsp; Whenever a
  ttk::combobox or ttk::spinbox is created, the <code><a href=
  "wheelEvent.html#adapt">scrollutil::adaptWheelEventHandling</a></code>
  command is invoked for it, being that these widgets have built-in bindings
  for the mouse wheel events.</p>

  <p>The widgets populating the content frame are managed using
  <code>grid</code>.&nbsp; In case of the ttk::entry widgets we invoke
  <code>grid</code> with&nbsp; <code>-sticky we</code>.&nbsp; Due to this and
  the&nbsp; <code>-fitcontentwidth yes</code>&nbsp; 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.</p>

  <blockquote>
    <img src="TablelistConfig.png" alt="TablelistConfig" width="382"
    height="403">
  </blockquote>

  <h3 id="ex_BwScrollableFrameDemo2">A Script Using Two BWidget ScrollableFrame
  Widgets</h3>

  <p>The script <code>BwScrollableFrmDemo2.tcl</code> in the <code>demos</code>
  directory creates a BWidget ScrollableFrame embedded into a <a href=
  "scrollarea.html">scrollarea</a> widget and then <code>source</code>s the
  script <code>BwScrollableFrmContent.tcl</code>, which populates the content
  frame of the ScrollableFrame with the same widgets as
  <code>SuScrollableFrmContent.tcl</code> in the <a href=
  "#ex_SuScrollableFrameDemo2">previous example</a>.</p>

  <p>Here is the relevant code:</p>

  <blockquote>
    <pre>
package require Tk 8.5.9                        ;<span class=
"cmt"># for ttk::spinbox</span>
package require BWidget
Widget::theme yes
package require mentry_tile 3.2                 ;<span class=
"cmt"># for mouse wheel support</span>
package require tablelist_tile 6.5              ;<span class=
"cmt"># for -(x|y)mousewheelwindow</span>
                                                ;<span class=
 "cmt"># and scrollutil::scrollarea</span>
<span class="red">package require scrollutil_tile</span>
source styleUtil.tcl

wm title . "Scrollutil Demo"

<span class="cmt">#
# Create a ScrollableFrame within a scrollarea
#</span>
set tf [ttk::frame .tf]
<span class="red">set sa [scrollutil::scrollarea $tf.sa]</span>
set sf [ScrollableFrame $sa.sf]
<span class="red">$sa setwidget $sf</span>

. . .

<span class="cmt">#
# Get the content frame and populate it
#</span>
set cf [$sf getframe]
source BwScrollableFrmContent.tcl

<span class="cmt">#
# Make the keyboard navigation more user-friendly
#</span>
foreach w [list $cb $sb $e $me] {
    bind $w &lt;&lt;TraverseIn&gt;&gt; [list $sf see %W]
}
foreach w [list $txt $lb $tbl $tv] {
    bind $w &lt;&lt;TraverseIn&gt;&gt; [list seeScrollarea $sf %W]
}
proc seeScrollarea {sf w} { $sf see [<span class="red">scrollutil::getscrollarea $w</span>] }
</pre>
  </blockquote>

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

  <p>The file <code>BwScrollableFrmContent.tcl</code> contains also the
  implementation of the procedure <code>configTablelist</code>, associated with
  the "Configure Tablelist Widget" button as the value of its
  <code>-command</code> option.&nbsp; This procedure opens a toplevel window
  that contains a BWidget ScrollableFrame created with the&nbsp;
  <code>-constrainedwidth yes</code>&nbsp; setting within a <a href=
  "scrollarea.html">scrollarea</a> widget and invokes the <code><a href=
  "wheelEvent.html#enable">scrollutil::enableScrollingByWheel</a></code>
  command for this ScrollableFrame, thus registering the latter for scrolling
  by the already created mouse wheel event bindings for the binding tag
  <code>"all"</code>.&nbsp; 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.&nbsp; The procedure handles the
  <code>&lt;&lt;TraverseIn&gt;&gt;</code> virtual event sent to one of these
  widgets with the aid of the ScrollableFrame's <code>see</code>
  subcommand.&nbsp; Whenever a ttk::combobox or ttk::spinbox is created, the
  <code><a href=
  "wheelEvent.html#adapt">scrollutil::adaptWheelEventHandling</a></code>
  command is invoked for it, being that these widgets have built-in bindings
  for the mouse wheel events.</p>

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

  <h3 id="ex_ScrolledFrameDemo2">A Script Using Two iwidgets::scrolledframe
  Widgets</h3>

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

  <p>Here is the relevant code:</p>

  <blockquote>
    <pre>
package require Tk 8.5.9                        ;<span class=
"cmt"># for ttk::spinbox</span>
if {[catch {package require iwidgets} result1] != 0 &&
    [catch {package require Iwidgets} result2] != 0} {
    error "$result1; $result2"
}
source scrolledwidgetPatch.itk                  ;<span class=
"cmt"># adds ttk::scrollbar widgets</span>
package require mentry_tile 3.2                 ;<span class=
"cmt"># for mouse wheel support</span>
package require tablelist_tile 6.5              ;<span class=
"cmt"># for -(x|y)mousewheelwindow</span>
                                                ;<span class=
"cmt"># and scrollutil::scrollarea</span>
<span class="red">package require scrollutil_tile</span>
source styleUtil.tcl

wm title . "Scrollutil Demo"

. . .

<span class="cmt">#
# Create a scrolledframe
#</span>
set tf [ttk::frame .tf]
set sf [iwidgets::scrolledframe $tf.sf -borderwidth 1 -relief sunken \
        -scrollmargin 0]
. . .

<span class="cmt">#
# Get the content frame and populate it
#</span>
set cf [$sf childsite]
. . .
source ScrolledFrmContent.tcl
</pre>
  </blockquote>

  <p>The additional stuff related to the mouse wheel events contains exactly
  the same Scrollutil command invocations as the one in the two previous
  examples.</p>

  <p>The file <code>ScrolledFrmContent.tcl</code> contains also the
  implementation of the procedure <code>configTablelist</code>, associated with
  the "Configure Tablelist Widget" button as the value of its
  <code>-command</code> option.&nbsp; This procedure opens a toplevel window
  that contains an iwidgets::scrolledframe widget with a manually implemented
  equivalent of the&nbsp; <code><a href=
  "scrollableframe.html#fitcontentwidth">-fitcontentwidth</a> yes</code>&nbsp;
  <a href="scrollableframe.html">scrollutil::scrollableframe</a> and&nbsp;
  <code>-constrainedwidth yes</code>&nbsp; BWidget ScrollableFrame settings and
  invokes the <code><a href=
  "wheelEvent.html#enable">scrollutil::enableScrollingByWheel</a></code>
  command for this scrolledframe, thus registering the latter for scrolling by
  the already created mouse wheel event bindings for the binding tag
  <code>"all"</code>.&nbsp; 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.&nbsp; Whenever a ttk::combobox or ttk::spinbox is
  created, the <code><a href=
  "wheelEvent.html#adapt">scrollutil::adaptWheelEventHandling</a></code>
  command is invoked for it, being that these widgets have built-in bindings
  for the mouse wheel events.</p>

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

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>
</body>
</html>

/* generic class defining a top margin whose height equals the font size */
.tm {margin-top: 1em}

/* background, border, and padding for the <pre> tag */
pre {background: #F7F7F7; border: silver solid 1px; padding: 1px}

/* background for the <body> tag */
body {background: #FFFFFF}

/* color for the <span> tag */
span.red {color: #E00000}
span.cmt {color: #36648b}

<!DOCTYPE html>
<html>
<head>
  <title>Commands Related to Mouse Wheel Event Handling</title>

  <meta name="Author" content="Csaba Nemethi">
  <meta name="Keywords" content=
  "mouse wheel event, binding, event handling, scrolling, scrollable widget container, focus">

  <link rel="stylesheet" type="text/css" href="stylesheet.css">
</head>

<body>
  <div align="center">
    <h1>Commands Related to Mouse Wheel Event Handling</h1>

    <h2>For Scrollutil Version 1.5</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:csaba.nemethi@t-online.de">csaba.nemethi@t-online.de</a>
    </address>
  </div>

  <hr>

  <h2 id="contents">Contents</h2>

  <ul>
    <li><a href="#add">The
    <code><b>scrollutil::addMouseWheelSupport</b></code> Command</a></li>

    <li><a href="#create">The
    <code><b>scrollutil::createWheelEventBindings</b></code> Command</a></li>

    <li><a href="#enable">The
    <code><b>scrollutil::enableScrollingByWheel</b></code> Command</a></li>

    <li><a href="#adapt">The
    <code><b>scrollutil::adaptWheelEventHandling</b></code> Command</a></li>

    <li><a href="#setFocusCkWin">The
    <code><b>scrollutil::setFocusCheckWindow</b></code> Command</a></li>

    <li><a href="#focusCkWin">The
    <code><b>scrollutil::focusCheckWindow</b></code> Command</a></li>
  </ul>

  <div align="center">
    <p><a href="index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="add">The <code><b>scrollutil::addMouseWheelSupport</b></code>
  Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>scrollutil::addMouseWheelSupport</code> &ndash; Add mouse wheel
    support</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>scrollutil::addMouseWheelSupport</b> <i>tag</i> ?<i>axes</i>?
</pre>
    </dd>

    <dt><b>REQUIRED TK VERSION</b></dt>

    <dd>8.4 or higher.

    <dt class="tm"><b>DESCRIPTION</b></dt>

    <dd>Adds mouse wheel support to the widgets having the specified binding
    tag by creating bindings for the mouse wheel events along the axes given by
    the optional <code><i>axes</i></code> argument, which must be
    <code>xy</code> (the default, meaning both the x and y axis),
    <code>x</code> (meaning the x axis only), or <code>y</code> (meaning the y
    axis only).&nbsp; The binding scripts created by this command will scroll
    the window given by the <code><b>%W</b></code> event field with the aid of
    the&nbsp; <code><b>xview scroll</b> <i>number</i> <b>units</b></code>&nbsp;
    and&nbsp; <code><b>yview scroll</b> <i>number</i> <b>units</b></code>&nbsp;
    subcommands of the associated Tcl command.</dd>

    <dd class="tm"><b>REMARK 1:</b>&nbsp; If <code><i>tag</i></code> is the
    path name of a window then the binding scripts created by this command are
    terminated by an invocation of the <code><b>break</b></code> command, in
    order to prevent the processing of the mouse wheel events by further
    binding scripts.&nbsp; For example, if <code><i>tag</i></code> is the path
    name of a text widget then the terminating <code><b>break</b></code>
    command makes sure that the mouse wheel events will not <i>additionally</i>
    be processed by the class bindings (associated with the binding tag
    <code><b>Text</b></code>), which in Tk 8.5 and later trigger a scrolling by
    <i>pixels</i>, unlike the bindings created by this command, which scroll
    the widget by <i>units</i> (i.e., lines and characters).</dd>

    <dd class="tm"><b>REMARK 2:</b>&nbsp; The canvas widget has no built-in
    bindings, but you can use this command to add mouse wheel support to the
    widget class <code><b>Canvas</b></code> or individual canvas widgets.</dd>

    <dd class="tm"><b>REMARK 3:</b>&nbsp; The mouse wheel events along the
    vertical axis are <code><b>&lt;MouseWheel&gt;</b></code> on Windows,
    <code><b>&lt;MouseWheel&gt;</b></code> and
    <code><b>&lt;Option-MouseWheel&gt;</b></code> on Mac OS X, and
    <code><b>&lt;MouseWheel&gt;</b></code>,
    <code><b>&lt;Button-4&gt;</b></code> and
    <code><b>&lt;Button-5&gt;</b></code> on X11 (where
    <code><b>&lt;MouseWheel&gt;</b></code> is not triggered by the X server,
    but can be produced using&nbsp; <code><b>event generate</b></code>).&nbsp;
    The mouse wheel events along the horizontal axis are
    <code><b>&lt;Shift-MouseWheel&gt;</b></code> on Windows,
    <code><b>&lt;Shift-MouseWheel&gt;</b></code> and
    <code><b>&lt;Shift-Option-MouseWheel&gt;</b></code> on Mac OS X, and
    <code><b>&lt;Shift-MouseWheel&gt;</b></code>,
    <code><b>&lt;Shift-Button-4&gt;</b></code> and
    <code><b>&lt;Shift-Button-5&gt;</b></code> on X11 (where
    <code><b>&lt;Shift-MouseWheel&gt;</b></code> is not triggered by the X
    server, but can be produced using&nbsp; <code><b>event
    generate</b></code>).&nbsp; On X11, when using Tk 8.7a3 or later, there are
    two more mouse wheel events along the horizontal axis:
    <code><b>&lt;Button-6&gt;</b></code> and
    <code><b>&lt;Button-7&gt;</b></code>, which are handled just like
    <code><b>&lt;Shift-Button-4&gt;</b></code> and
    <code><b>&lt;Shift-Button-5&gt;</b></code>, respectively.&nbsp; These
    events are commonly triggered by left/right tilting the scroll wheel of a
    mouse having one or two additional (thumb) buttons.&nbsp; (In Tk versions
    8.6.x, with x >= 10, left/right tilting the scroll wheel of such a mouse
    gives rise to <code><b>&lt;Shift-MouseWheel&gt;</b></code> events on
    Windows and Mac OS X Aqua, and to
    <code><b>&lt;Shift-Button-4&gt;</b></code> and
    <code><b>&lt;Shift-Button-5&gt;</b></code> events on X11.)</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mouse wheel event, binding, scrolling</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="create">The <code><b>scrollutil::createWheelEventBindings</b></code>
  Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>scrollutil::createWheelEventBindings</code> &ndash; Create mouse
    wheel event bindings</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>scrollutil::createWheelEventBindings</b> ?<i>tag</i> <i>tag</i> ...?
</pre>
    </dd>

    <dt><b>REQUIRED TK VERSION</b></dt>

    <dd>8.4 or higher on X11 and Mac OS X; 8.6b2 or later on Windows.

    <dt class="tm"><b>DESCRIPTION</b></dt>

    <dd>Creates mouse wheel event bindings for the specified binding tags such
    that if the widget under the pointer is (a descendant of) one of the
    scrollable widget containers having the same toplevel as the widget and
    registered via <code><b><a href=
    "#enable">scrollutil::enableScrollingByWheel</a></b></code> then these
    events will trigger a scrolling of that widget container.&nbsp; In case of
    several nested registered scrollable widget containers fulfilling these
    conditions the innermost one will be scrolled.&nbsp; Each
    <code><i>tag</i></code> argument must be <code><b>all</b></code> or the
    path name of an existing toplevel widget (including
    <code><b>.</b></code>).</dd>

    <dd class="tm"><b>REMARK:</b>&nbsp; The reason for restricting the
    <code><i>tag</i></code> arguments to <code><b>all</b></code> and path names
    of existing toplevel widgets rather than supporting also tags like
    <code>"Scrollableframe"</code> (for scrollutil::scrollableframe),
    <code>"BwScrollableFrame"</code> (for BWidget ScrollableFrame) or
    <code>"Scrolledframe"</code> (for iwidgets::scrolledframe) is that the
    mouse wheel events should trigger a scrolling of the widget container under
    the pointer not only if the widget under the pointer is the widget
    container itself but also if it is a descendant of the latter (recall that
    for each window, the path name of its nearest toplevel ancestor and the tag
    <code><b>all</b></code> are contained in the window's default list of
    binding tags).</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mouse wheel event, binding, scrolling, scrollable widget container</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="enable">The <code><b>scrollutil::enableScrollingByWheel</b></code>
  Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>scrollutil::enableScrollingByWheel</code> &ndash; Register
    scrollable widget containers for scrolling by the mouse wheel</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>scrollutil::enableScrollingByWheel</b> ?<i>scrollableWidgetContainer</i> <i>scrollableWidgetContainer</i> ...?
</pre>
    </dd>

    <dt><b>REQUIRED TK VERSION</b></dt>

    <dd>8.4 or higher on X11 and Mac OS X; 8.6b2 or later on Windows.

    <dt class="tm"><b>DESCRIPTION</b></dt>

    <dd>Adds the specified scrollable widget containers to the internal list of
    widget containers that are registered for scrolling by the mouse wheel
    event bindings created by the <code><b><a href=
    "#create">scrollutil::createWheelEventBindings</a></b></code> command.</dd>

    <dd class="tm"><b>REMARK:</b>&nbsp; When a scrollable widget container
    whose path name was passed to this command gets destroyed, it is
    automatically removed from the above-mentioned internal list of registered
    widget containers.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mouse wheel event, binding, scrolling, scrollable widget container</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="adapt">The <code><b>scrollutil::adaptWheelEventHandling</b></code>
  Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>scrollutil::adaptWheelEventHandling</code> &ndash; Adapt mouse
    wheel event handling</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>scrollutil::adaptWheelEventHandling</b> ?<i>widget</i> <i>widget</i> ...?
</pre>
    </dd>

    <dt><b>REQUIRED TK VERSION</b></dt>

    <dd>8.4 or higher on X11 and Mac OS X; 8.6b2 or later on Windows.

    <dt class="tm"><b>DESCRIPTION</b></dt>

    <dd>For each <code><i>widget</i></code> argument, the command performs the
    following actions:</dd>

    <dd class="tm">
      <ul>
        <li>
          If <code><i>widget</i></code> is the path name of a <a href=
          "https://www.nemethi.de/tablelist/">tablelist</a> widget then it sets
          the latter's <code><b>-xmousewheelwindow</b></code> and
          <code><b>-ymousewheelwindow</b></code> options to the path name of
          the containing toplevel window, provided that the Tablelist version
          is 6.4 or later (for earlier Tablelist versions the command silently
          ignores any tablelist widget passed to it as argument).&nbsp; As a
          result, a mouse wheel event over the tablelist's body or edit window
          (more precisely, a mouse wheel event sent to any component of the
          tablelist having the binding tag <code><b>TablelistBody</b></code> or
          <code><b>TablelistEdit</b></code>) will be handled as follows:

          <ul class="tm">
            <li>If the focus is inside the tablelist widget then the event will
            scroll the tablelist or its edit window and no further processing
            of the event will take place.</li>

            <li class="tm">If the focus is outside the tablelist widget then no
            scrolling of the tablelist's body or edit window will happen.&nbsp;
            Instead, the event will be redirected to the containing toplevel
            window via&nbsp; <code><b>event generate</b></code>.&nbsp; This in
            turn will trigger a scrolling of the (innermost) widget container
            that is an ancestor of <code><i>widget</i></code> and has the same
            toplevel (if there is such a scrollable widget container), provided
            that the path name of the containing toplevel widget or the binding
            tag <code><b>all</b></code> was passed to the <code><b><a href=
            "#create">scrollutil::createWheelEventBindings</a></b></code>
            command and this widget container was registered for scrolling via
            <code><b><a href=
            "#enable">scrollutil::enableScrollingByWheel</a></b></code>.</li>
          </ul>
        </li>

        <li class="tm">
          Otherwise it locates the (first) binding tag that has mouse wheel
          event bindings and is different from both the path name of the
          containing toplevel window and <code><b>all</b></code>.&nbsp; If the
          search for this tag was successful then the command modifies the
          widget's list of binding tags by prepending the tag
          <code><b>WheeleventRedir</b></code> and appending the tag
          <code><b>WheeleventBreak</b></code> to this binding tag.&nbsp; As a
          result, a mouse wheel event sent to this widget will be handled as
          follows:

          <ul class="tm">
            <li>If the focus is on or inside the window&nbsp;
            <code>[<b><a href="#focusCkWin">focusCheckWindow</a></b>
            <i>widget</i>]</code>&nbsp; then the event will be handled by the
            binding script associated with this tag and no further processing
            of the event will take place.</li>

            <li class="tm">If the focus is outside the window&nbsp;
            <code>[<b>focusCheckWindow</b> <i>widget</i>]</code>&nbsp; then the
            event will be redirected to the containing toplevel window
            via&nbsp; <code><b>event generate</b></code>&nbsp; rather than
            being handled by the binding script associated with the
            above-mentioned tag.&nbsp; This in turn will trigger a scrolling of
            the (innermost) widget container that is an ancestor of
            <code><i>widget</i></code> and has the same toplevel (if there is
            such a scrollable widget container), provided that the path name of
            the containing toplevel widget or the binding tag
            <code><b>all</b></code> was passed to the <code><b><a href=
            "#create">scrollutil::createWheelEventBindings</a></b></code>
            command and this widget container was registered for scrolling via
            <code><b><a href=
            "#enable">scrollutil::enableScrollingByWheel</a></b></code>.</li>
          </ul>
        </li>
      </ul>
    </dd>

    <dd class="tm"><b>REMARK 1:</b>&nbsp; This command is designed to be
    invoked for widgets that have mouse wheel event bindings and are
    descendants of a scrollable widget container (although it does no harm if
    it is called for other widgets, too).&nbsp; The Tk and tile widgets having
    class bindings for mouse wheel events are: listbox, text, Tk core
    scrollbar, ttk::scrollbar, ttk::combobox, ttk::spinbox, and
    ttk::treeview.&nbsp; Examples of widgets with binding tags other than their
    class names that have mouse wheel event bindings are tablelist widgets as
    well as the entry components of <a href=
    "https://www.nemethi.de/mentry/">mentry</a> widgets of type
    <code>"Date"</code>, <code>"Time"</code>, <code>"DateTime"</code>,
    <code>"IPAddr"</code>, and <code>"IPv6Addr"</code> (for Mentry versions 3.2
    and above).</dd>

    <dd class="tm"><b>REMARK 2:</b>&nbsp; The mouse wheel event class bindings
    for the Tk core scrollbar on Windows and X11 were added in Tk 8.6.&nbsp;
    Prior to this Tk version there were such bindings only for the windowing
    systems <code><b>classic</b></code> and <code><b>aqua</b></code> on the
    Macintosh.&nbsp; Scrollutil eliminates this discrepancy by automatically
    creating the <code><b>Scrollbar</b></code> class bindings for mouse wheel
    events on Windows and X11.&nbsp; Note also that the ttk::scrollbar widget
    has no <i>built-in</i> class bindings for mouse wheel events, but
    Scrollutil automatically creates the missing bindings by copying the mouse
    wheel event bindings of the widget class <code><b>Scrollbar</b></code> to
    the binding tag <code><b>TScrollbar</b></code>.</dd>

    <dd class="tm"><b>REMARK 3:</b>&nbsp; As mentioned above, Tk core scrollbar
    and ttk::scrollbar widgets have class bindings for mouse wheel events,
    hence this command should be invoked for them in case they are descendants
    of a scrollable widget container.&nbsp; Since this task can become tedious,
    Scrollutil makes sure that if you pass a widget to this command and that
    widget is embedded into a <a href="scrollarea.html">scrollarea</a> via the
    latter's <code><b><a href=
    "scrollarea.html#setwidget">setwidget</a></b></code> subcommand, then this
    command will automatically be invoked for the scrollbars of that
    scrollarea, too.</dd>

    <dd class="tm"><b>REMARK 4:</b>&nbsp; When handling a mouse wheel event
    sent to a Tk core or tile scrollbar whose path name was passed to this
    command, if the focus is on or inside the associated widget then the event
    will be processed by the scrollbar rather than being redirected to the
    containing toplevel, just as if the focus were on the scrollbar
    itself.</dd>

    <dd class="tm"><b>REMARK 5:</b>&nbsp; Invoking this command for widgets
    that have mouse wheel event bindings and are descendants of a scrollable
    widget container is essential for a user-friendly mouse wheel event
    handling in scrollable widget containers.&nbsp; Without this step the mouse
    wheel events would scroll both the listbox, text, ttk::treeview, or 
    tablelist widget under the pointer <i>and</i> the widget container to whose
    descendants the latter belongs, or they would select the next/previous
    value in the ttk::combobox or ttk::spinbox under the pointer <i>in addition
    to</i> scrolling the widget container.&nbsp; After invoking this command,
    e.g, for a listbox within a scrollable widget container, the mouse wheel
    events over that widget will only scroll the listbox if it has the
    focus.&nbsp; Likewise, after invoking this command for a ttk::combobox or
    ttk::spinbox within a scrollable widget container, the mouse wheel events
    over that widget will only select its next/previous value if it has the
    focus.&nbsp; In both examples, if the focus is outside the widget in
    question then the mouse wheel events will scroll the widget container
    instead.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mouse wheel event, binding, event handling, scrolling, scrollable
    widget container, focus</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="setFocusCkWin">The
  <code><b>scrollutil::setFocusCheckWindow</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>scrollutil::setFocusCheckWindow</code> &ndash; Set the "focus
    check window"</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>scrollutil::setFocusCheckWindow</b> <i>widget</i> ?<i>widget</i> ...? <i>otherWidget</i>
</pre>
    </dd>

    <dt><b>REQUIRED TK VERSION</b></dt>

    <dd>8.4 or higher on X11 and Mac OS X; 8.6b2 or later on Windows.

    <dt class="tm"><b>DESCRIPTION</b></dt>

    <dd>For each <code><i>widget</i></code> argument, the command sets the
    associated "focus check window" to <code><i>otherWidget</i></code>.&nbsp;
    This is the window to be used in the binding scripts for the tag
    <code><b><a href="#adapt">WheeleventRedir</a></b></code> instead of the
    widget when checking whether the focus is on/inside or outside that
    window.&nbsp; For each <code><i>widget</i></code> argument,
    <code><i>otherWidget</i></code> must be an ancestor of or identical to 
    <code><i>widget</i></code>.</dd>

    <dd class="tm"><b>REMARK 1:</b>&nbsp; When a widget whose path name was
    passed to this command as one of its <code><i>widget</i></code> arguments
    gets destroyed, the association between the widget and its "focus check
    window" is automatically removed.</dd>

    <dd class="tm"><b>REMARK 2:</b>&nbsp; This command comes in handy if for
    some widgets you want to make the focus check within the binding scripts
    for the tag <code><b>WheeleventRedir</b></code> less restrictive.&nbsp; For
    example, if the widget under the pointer is an entry component of a
    <a href="https://www.nemethi.de/mentry/">mentry</a> <code><i>me</i></code>
    of type <code>"Date"</code>, <code>"Time"</code>, <code>"DateTime"</code>,
    <code>"IPAddr"</code>, or <code>"IPv6Addr"</code> and the focus is on any
    of its siblings, then the mouse wheel events sent to this entry should be
    handled by the entry widget itself rather than scrolling the widget
    container that is an ascendant of the mentry.&nbsp; You can achieve this by
    invoking</dd>

    <dd>
      <blockquote>
        <pre>
set entryList [$me <a href=
"https://www.nemethi.de/mentry/mentryWidget.html#entries">entries</a>]
eval <a href="#adapt">scrollutil::adaptWheelEventHandling</a> $entryList
eval <span class="red">scrollutil::setFocusCheckWindow</span>     $entryList [list $me]
</pre>
      </blockquote>
    </dd>

    <dd>With Tcl/Tk 8.5 or above, you can use the more compact form</dd>

    <dd>
      <blockquote>
        <pre>
set entryList [$me <a href=
"https://www.nemethi.de/mentry/mentryWidget.html#entries">entries</a>]
<a href="#adapt">scrollutil::adaptWheelEventHandling</a> {*}$entryList
<span class="red">scrollutil::setFocusCheckWindow</span>     {*}$entryList $me
</pre>
      </blockquote>
    </dd>

    <dd class="tm"><b>REMARK 3:</b>&nbsp; As a similar example, suppose that
    <code><i>ss</i></code> is a <a href="scrollsync.html">scrollsync</a>
    widget that was populated via its <code><b><a href=
    "scrollsync.html#setwidgets">setwidgets</a></b></code> subcommand with
    child widgets.&nbsp; Then, if the widget under the pointer is one of these
    children and the focus is on any of the other children passed to that
    subcommand, then the mouse wheel events sent to the child under the pointer
    should be handled by that child widget itself rather than scrolling the
    widget container that is an ascendant of the scrollsync.&nbsp; You can
    achieve this with the following code:</dd>

    <dd>
      <blockquote>
        <pre>
set widgetList [$ss <a href="scrollsync.html#widgets">widgets</a>]
eval <a href="#adapt">scrollutil::adaptWheelEventHandling</a> $widgetList
eval <span class="red">scrollutil::setFocusCheckWindow</span>     $widgetList [list $ss]
</pre>
      </blockquote>
    </dd>

    <dd>Again, with Tcl/Tk 8.5 or above, you can use the more compact form</dd>

    <dd>
      <blockquote>
        <pre>
set widgetList [$ss <a href="scrollsync.html#widgets">widgets</a>]
<a href="#adapt">scrollutil::adaptWheelEventHandling</a> {*}$widgetList
<span class="red">scrollutil::setFocusCheckWindow</span>     {*}$widgetList $ss
</pre>
      </blockquote>
    </dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>binding, focus, "focus check window"</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="focusCkWin">The <code><b>scrollutil::focusCheckWindow</b></code>
  Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>scrollutil::focusCheckWindow</code> &ndash; Query the "focus
    check window"</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>scrollutil::focusCheckWindow</b> <i>widget</i>
</pre>
    </dd>

    <dt><b>REQUIRED TK VERSION</b></dt>

    <dd>8.4 or higher on X11 and Mac OS X; 8.6b2 or later on Windows.

    <dt class="tm"><b>DESCRIPTION</b></dt>

    <dd>Returns the path name of the "focus check window" associated with the
    <code><i>widget</i></code> argument.&nbsp; This is the window that is used
    in the binding scripts for the tag <code><b><a href=
    "#adapt">WheeleventRedir</a></b></code> instead of the widget when checking
    whether the focus is on/inside or outside that window.&nbsp; If the command
    <code><b><a href=
    "#setFocusCkWin">scrollutil::setFocusCheckWindow</a></b></code> was not
    invoked for <code><i>widget</i></code> then the return value is
    <code><i>widget</i></code> itself.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>binding, focus, "focus check window"</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>
</body>
</html>

<!DOCTYPE html>
<html>
<head>
  <title>The Multi-Column Listbox and Tree Widget Package Tablelist 6.8</title>

  <meta name="Author" content="Csaba Nemethi">
  <meta name="Keywords" content=
  "tablelist, multi-column, listbox, tree, widget, tile">
</head>

<body>
  <div align="center">
    <h1>The Multi-Column Listbox and Tree Widget Package Tablelist 6.8</h1>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:csaba.nemethi@t-online.de">csaba.nemethi@t-online.de</a>
    </address>
  </div>

  <hr>

  <h2>Contents</h2>

  <p><a href="tablelist.html">Tablelist Programmer's Guide</a></p>

  <p><a href="tablelistWidget.html">The <code>tablelist::tablelist</code>
  Command</a></p>

  <p><a href="tablelistColSort.html">Commands for Interactive Sorting by One or
  More Columns</a></p>

  <p><a href="tablelistBinding.html">Commands Related to Binding
  Scripts</a></p>

  <p><a href="tablelistThemes.html">Commands Related to Tile Themes</a></p>

  <p><a href="tablelistTkCore.html">Interactive Tablelist Cell Editing Using Tk
  Core Widgets</a></p>

  <p><a href="tablelistTile.html">Interactive Tablelist Cell Editing Using Tile
  Widgets</a></p>

  <p><a href="tablelistBWidget.html">Interactive Tablelist Cell Editing Using
  the BWidget Package</a></p>

  <p><a href="tablelistIwidgets.html">Interactive Tablelist Cell Editing Using
  the Iwidgets Package</a></p>

  <p><a href="tablelistCombobox.html">Interactive Tablelist Cell Editing Using
  the combobox Package</a></p>

  <p><a href="tablelistCtext.html">Interactive Tablelist Cell Editing Using
  the ctext Package</a></p>

  <p><a href="tablelistMentry.html">Interactive Tablelist Cell Editing Using
  the Mentry Package</a></p>
</body>
</html>

/* generic class defining a top margin whose height equals the font size */
.tm {margin-top: 1em}

/* background, border, and padding for the <pre> tag */
pre {background: #F7F7F7; border: silver solid 1px; padding: 1px}

/* background for the <body> tag */
body {background: #FFFFFF}

/* color for the <span> tag */
span.red {color: #E00000}
span.cmt {color: #36648b}

<!DOCTYPE html>
<html>
<head>
  <title>Tablelist Programmer's Guide</title>

  <meta name="Author" content="Csaba Nemethi">
  <meta name="Keywords" content=
  "tablelist, multi-column, listbox, tree, widget, tile">

  <link rel="stylesheet" type="text/css" href="stylesheet.css">
</head>

<body>
  <div align="center">
    <h1>Tablelist Programmer's Guide</h1>

    <h2>For Tablelist Version 6.8</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:csaba.nemethi@t-online.de">csaba.nemethi@t-online.de</a>
    </address>
  </div>

  <hr>

  <h2 id="contents">Contents</h2>

  <h4><a href="#overview">Overview</a></h4>

  <ul>
    <li><a href="#ov_what">What Is Tablelist?</a></li>

    <li><a href="#ov_get">How to Get It?</a></li>

    <li><a href="#ov_install">How to Install It?</a></li>

    <li><a href="#ov_use">How to Use It?</a></li>

    <li><a href="#ov_tile">More on Tablelist_tile</a></li>
  </ul>

  <h4><a href="#examples">Examples</a></h4>

  <ul>
    <li><a href="#ex_config">A tablelist Widget for Displaying and Editing
    Configuration Options</a></li>

    <li><a href="#ex_browse">Two Widget Browsers Based on a tablelist</a></li>

    <li><a href="#ex_dirViewer">A Directory Viewer Based on a
    tablelist</a></li>

    <li><a href="#ex_styles">Improving the Look & Feel of a tablelist
    Widget</a></li>

    <li><a href="#ex_editing">Advanced Interactive tablelist Cell
    Editing</a></li>

    <li><a href="#ex_windows">A tablelist Widget Containing Embedded
    Windows</a></li>

    <li><a href="#ex_tile">Tile-Based Demo Scripts</a></li>
  </ul>

  <div align="center">
    <p><a href="index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="overview">Overview</h2>

  <h3 id="ov_what">What Is Tablelist?</h3>

  <p>Tablelist is a library package for Tcl/Tk versions 8.0 or higher, written
  in pure Tcl/Tk code.&nbsp; It contains:</p>

  <ul>
    <li>the implementation of the <a href=
    "tablelistWidget.html"><b>tablelist</b> mega-widget</a>, including a
    general utility module for mega-widgets;</li>

    <li>a demo script containing a useful procedure that displays the
    configuration options of an arbitrary widget in a tablelist and enables you
    to edit their values interactively;</li>

    <li>a demo script implementing a widget browser based on a tablelist used
    as multi-column listbox;</li>

    <li>a demo script implementing a widget browser based on a tablelist used
    as multi-column tree widget;</li>

    <li>a demo script implementing a directory viewer based on a tablelist used
    as multi-column tree widget;</li>

    <li>a demo script showing several ways to improve the appearance of a
    tablelist widget;</li>

    <li>four further demo scripts, illustrating the interactive cell editing
    with the aid of various widgets from the Tk core and from the packages
    tile, BWidget, Iwidgets, combobox (by Bryan Oakley), and Mentry;</li>

    <li>one further demo script, with a tablelist widget containing embedded
    windows;</li>

    <li>tile-based counterparts of the above-mentioned demo scripts;</li>

    <li>this tutorial;</li>

    <li>reference pages in HTML format.</li>
  </ul>

  <p>A tablelist is a multi-column listbox and tree widget.&nbsp; The width of
  each column can be dynamic (i.e., just large enough to hold all its elements,
  including the header) or static (specified in characters or pixels).&nbsp;
  The columns are, per default, resizable.&nbsp; The alignment of each column
  can be specified as <code>left</code>, <code>right</code>, or
  <code>center</code>.</p>

  <p>The columns, rows, and cells can be configured individually.&nbsp; Several
  of the global and column-specific options refer to the header titles,
  implemented as label widgets.&nbsp; For instance, the
  <code>-labelcommand</code> option specifies a Tcl command to be invoked when
  mouse button 1 is released over a header label.&nbsp; The most common value
  of this option sorts the items based on the respective column.</p>

  <p>The Tablelist package provides a great variety of tree styles controlling
  the look & feel of the column that displays the tree hierarchy with the aid
  of indentations and expand/collapse controls.</p>

  <p>Interactive editing of the elements of a tablelist widget can be enabled
  for individual cells and for entire columns.&nbsp; A great variety of widgets
  from the Tk core and from the packages tile, BWidget, Iwidgets, combobox,
  ctext, and Mentry (or Mentry_tile) is supported for being used as embedded
  edit window.&nbsp; In addition, a rich set of keyboard bindings is provided
  for a comfortable navigation between the editable cells.</p>

  <p>The Tcl command corresponding to a tablelist widget is very similar to the
  one associated with a normal listbox.&nbsp; There are column-, row-, and
  cell-specific counterparts of the <code>configure</code> and
  <code>cget</code> subcommands (<code>columnconfigure</code>,
  <code>rowconfigure</code>, <code>cellconfigure</code>, ...).&nbsp; They can
  be used, among others, to insert images into the cells and the header labels,
  or to insert embedded windows into the cells.&nbsp; The <code>index</code>,
  <code>nearest</code>, and <code>see</code> command options refer to the rows,
  but similar subcommands are provided for the columns and cells
  (<code>columnindex</code>, <code>cellindex</code>, ...).&nbsp; The items can
  be sorted with the <code>sort</code>, <code>sortbycolumn</code>, and
  <code>sortbycolumnlist</code> command options.</p>

  <p>The bindings defined for the body of a tablelist widget make it behave
  just like a normal listbox.&nbsp; This includes the support for the virtual
  event <code>&lt;&lt;ListboxSelect&gt;&gt;</code> (which is equivalent to
  <code>&lt;&lt;TablelistSelect&gt;&gt;</code>).&nbsp; In addition, versions
  2.3 or higher of the widget callback package Wcb (written in pure Tcl/Tk code
  as well) can be used to define callbacks for the <code>activate</code>,&nbsp;
  <code>selection set</code>,&nbsp; and&nbsp; <code>selection
  clear</code>&nbsp; commands, and Wcb versions 3.0 or higher also support
  callbacks for the <code>activatecell</code>,&nbsp; <code>cellselection
  set</code>,&nbsp; and&nbsp; <code>cellselection clear</code>&nbsp;
  commands.&nbsp; The download location of Wcb is</p>

  <blockquote>
    <address>
      <a href="https://www.nemethi.de">https://www.nemethi.de</a>
    </address>
  </blockquote>

  <h3 id="ov_get">How to Get It?</h3>

  <p>Tablelist is available for free download from the same URL as Wcb.&nbsp;
  The distribution file is <code>tablelist6.8.tar.gz</code> for UNIX and
  <code>tablelist6_8.zip</code> for Windows.&nbsp; 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.</p>

  <p>Tablelist is also included in tklib, which has the address</p>

  <blockquote>
    <address>
      <a href="https://core.tcl.tk/tklib">https://core.tcl.tk/tklib</a>
    </address>
  </blockquote>

  <h3 id="ov_install">How to Install It?</h3>

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

  <p>To install Tablelist <i>on UNIX</i>, <code>cd</code> to the desired
  directory and unpack the distribution file
  <code>tablelist6.8.tar.gz</code>:</p>

  <blockquote>
    <pre>
gunzip -c tablelist6.8.tar.gz | tar -xf -
</pre>
  </blockquote>

  <p>On most UNIX systems this can be replaced with</p>

  <blockquote>
    <pre>
tar -zxf tablelist6.8.tar.gz
</pre>
  </blockquote>

  <p>Both commands will create a directory named <code>tablelist6.8</code>,
  with the subdirectories <code>demos</code>, <code>doc</code>, and
  <code>scripts</code>.</p>

  <p><i>On Windows</i>, use WinZip or some other program capable of unpacking
  the distribution file <code>tablelist6_8.zip</code> into the directory
  <code>tablelist6.8</code>, with the subdirectories <code>demos</code>,
  <code>doc</code>, and <code>scripts</code>.</p>

  <p>The file <code>tablelistEdit.tcl</code> in the <code>scripts</code>
  directory is only needed for applications making use of interactive cell
  editing.&nbsp; Similarly, the file <code>tablelistMove.tcl</code> in the same
  directory is only required for scripts invoking the <code>move</code> or
  <code>movecolumn</code> command.&nbsp; Finally, the file
  <code>tablelistThemes.tcl</code> is only needed for applications using the
  package Tablelist_tile (see next section).</p>

  <p>Next, you should check the exact version number of your Tcl/Tk
  distribution, given by the <code>tcl_patchLevel</code> and
  <code>tk_patchLevel</code> variables.&nbsp; If you are using Tcl/Tk version
  8.2.X, 8.3.0 - 8.3.2, or 8.4a1, then you should upgrade your Tcl/Tk
  distribution to a higher release.&nbsp; This is because a bug in these Tcl
  versions (fixed in Tcl 8.3.3 and 8.4a2) causes excessive memory use when
  calling&nbsp; <code>info exists</code>&nbsp; on non-existent array elements,
  and Tablelist makes a lot of invocations of this command.</p>

  <p>If for some reason you cannot upgrade your Tcl/Tk version, then you should
  execute the Tcl script <code>repair.tcl</code> in the directory
  <code>scripts</code>.&nbsp; This script makes backup copies of several files
  contained in this directory, and then creates new versions of them by
  replacing all invocations of&nbsp; <code>info exists</code>&nbsp; for array
  elements with a call to the helper procedure
  <code>arrElemExists</code>.&nbsp; The patched files work with all Tcl/Tk
  releases starting with 8.0, but the original ones have a much better
  performance.</p>

  <p>Notice that in tklib the Tablelist <code>demos</code> directory is
  replaced with the subdirectory <code>tablelist</code> of the
  <code>examples</code> directory.&nbsp; Please take this into account when
  reading the <a href="#examples">examples</a> below.</p>

  <h3 id="ov_use">How to Use It?</h3>

  <p>The Tablelist distribution provides two packages, called <b>Tablelist</b>
  and <b>Tablelist_tile</b>.&nbsp; The main difference between the two is that
  Tablelist_tile enables the tile-based, theme-specific appearance of tablelist
  widgets; this package requires Tcl/Tk 8.4 or higher and tile 0.6 or
  higher.&nbsp; It is not possible to use both packages in one and the same
  application, because both are implemented in the same <code>tablelist</code>
  namespace and provide identical commands.</p>

  <p>To be able to access the commands and variables defined in the package
  Tablelist, your scripts must contain one of the lines</p>

  <blockquote>
    <pre>
package require tablelist ?<i>version</i>?
package require Tablelist ?<i>version</i>?
</pre>
  </blockquote>

  <p>You can use either one of the two statements above because the file
  <code>tablelist.tcl</code> contains both lines</p>

  <blockquote>
    <pre>
package provide tablelist ...
package provide Tablelist ...
</pre>
  </blockquote>

  <p>Likewise, to be able to access the commands and variables defined in the
  package Tablelist_tile, your scripts must contain one of the lines</p>

  <blockquote>
    <pre>
package require tablelist_tile ?<i>version</i>?
package require Tablelist_tile ?<i>version</i>?
</pre>
  </blockquote>

  <p>Again, you can use either one of the two statements above because the file
  <code>tablelist_tile.tcl</code> contains both lines</p>

  <blockquote>
    <pre>
package provide tablelist_tile ...
package provide Tablelist_tile ...
</pre>
  </blockquote>

  <p>You are free to remove one of the above lines from
  <code>tablelist.tcl</code> and <code>tablelist_tile.tcl</code>, respectively,
  if you want to prevent the corresponding packages from making themselves
  known under two different names each.&nbsp; Of course, by doing so you
  restrict the argument of&nbsp; <code>package require</code>&nbsp; to a single
  name per package.</p>

  <p>Please note that <b>ActiveTcl versions 8.5 and later use a modified
  package mechanism, which only exports the all-lowercase names
  <code>tablelist</code> and <code>tablelist_tile</code></b>.</p>

  <p><b>REMARK:</b>&nbsp; If you have an earlier Tablelist version as part of
  ActiveTcl 8.5 or above and the new Tablelist release 6.8, then it is highly
  recommended to specify the version number <code>6.8</code> in the&nbsp;
  <code>package require</code>&nbsp; command, because otherwise the interpreter
  will load the old Tablelist version included in ActiveTcl as Tcl
  Module.&nbsp; The <a href="#examples">examples</a> below use the
  statement&nbsp; <code>package require tablelist 6.8</code>,&nbsp; and their
  tile-based counterparts invoke the command&nbsp; <code>package require
  tablelist_tile 6.8</code>.</p>

  <p>Since the packages Tablelist and Tablelist_tile are implemented in the
  <code>tablelist</code> namespace, you must either invoke the</p>

  <blockquote>
    <pre>
namespace import tablelist::<i>pattern</i> ?tablelist::<i>pattern ...</i>?
</pre>
  </blockquote>

  <p>command to import the <i>procedures</i> you need, or use qualified names
  like <code>tablelist::tablelist</code>.&nbsp; In the examples below we have
  chosen the latter approach.</p>

  <p>To access Tablelist <i>variables</i>, you <i>must</i> use qualified
  names.&nbsp; There are only 5 Tablelist variables (and one more when using
  Tablelist_tile) that are designed to be accessed outside the namespace
  <code>tablelist</code>:</p>

  <ul>
    <li>The variable <code>tablelist::version</code> holds the current version
    number of the Tablelist and Tablelist_tile packages.</li>

    <li>The variable <code>tablelist::library</code> holds the location of the
    Tablelist installation directory.</li>

    <li>The variable <code>tablelist::scalingpct</code> holds the scaling
    percentage used by Tablelist when adapting the sizes of the tree styles
    <code>vistaAero</code>, <code>vistaClassic</code>, <code>win7Aero</code>,
    <code>win7Classic</code>, and <code>win10</code> to the display's DPI
    scaling level.&nbsp; The currently supported values are <code>100</code>,
    <code>125</code>, <code>150</code>, and <code>200</code>.&nbsp; You can use
    the value of this variable, e.g., if you want to create images of different
    sizes, depending on the DPI scaling factor.&nbsp; For example, if your
    application uses images of size 16 x 16 on an unscaled display and
    <code>tablelist::scalingpct</code> has the value <code>150</code>, then the
    image size for this display should be 24 x 24.</li>

    <li>The boolean variable <code>tablelist::strictTk</code> (having the
    default value <code>0</code>) controls the strict listbox-compatibility of
    the default bindings.</li>

    <li>The read-only boolean variable <code>tablelist::usingTile</code> has
    the value <code>0</code> in the package Tablelist and the value
    <code>1</code> in Tablelist_tile.</li>

    <li>In Tablelist_tile the array <code>tablelist::themeDefaults</code> holds
    the theme-specific default values of a series of Tablelist configuration
    options.</li>
  </ul>

  <h3 id="ov_tile">More on Tablelist_tile</h3>

  <p>A tablelist widget consists of a body (containing the items) and a header
  (displaying the column titles and optional header items).&nbsp; Both
  components are contained in a hull, implemented as a frame.&nbsp; The header
  has a rather complex structure, consisting, among others, of frame and label
  widgets.&nbsp; While in the Tablelist package all of these components are Tk
  widgets, the Tablelist_tile package uses both Tk and tile frame and label
  widgets.&nbsp; Due to several incompatibilities between Tk and tile, it is
  currently not possible to replace all Tk widgets making up a tablelist with
  their tile counterparts.</p>

  <p>From the above it follows that <b>the package Tablelist_tile will only
  work as expected if the Tk <code>frame</code> and <code>label</code> commands
  haven't been overridden by using&nbsp; <code>namespace import -force
  ttk::*</code>&nbsp; at global scope</b>.&nbsp; While earlier tile releases
  suggested using this command at global scope for the really adventurous, in
  newer tile versions this is considered a Really Bad Idea, causing many things
  to break.&nbsp; Instead, <b>you should explicitly invoke
  <code>ttk::frame</code>, <code>ttk::label</code>, etc. whenever you want to
  use a tile widget</b>.</p>

  <p><b>Overriding some other Tk widgets at global scope may be equally
  dangerous when using various widgets from the Tk core and from the packages
  BWidget, Iwidgets, combobox (by Bryan Oakley), ctext, and Mentry for
  interactive cell editing</b>, because these packages expect Tk widgets, which
  may not always be replaced by their tile counterparts.</p>

  <p>Another restriction to be taken into account is due to the fact that in
  earlier tile versions the&nbsp; <code>(ttk::)style theme use</code>&nbsp;
  command could only be used to set the current theme, but not to retrieve
  it.&nbsp; For this reason, the package Tablelist_tile makes use of the
  variable <code>ttk::currentTheme</code> or <code>tile::currentTheme</code>
  (depending on the tile version), which is set by the
  <code>ttk::setTheme</code> or <code>tile::setTheme</code> procedure.&nbsp;
  From this it follows that <b>the tile-based tablelist widgets will only have
  the expected appearance if the platform-specific default theme is either left
  unchanged or replaced with another theme by invoking the procedure
  <code>ttk::setTheme</code> or <code>tile::setTheme</code>, depending on the
  current tile version</b>.&nbsp; (See also the <code><a href=
  "tablelistThemes.html#setTheme">tablelist::setTheme</a></code> command.)</p>

  <p>After these cautions concerning the use of tile, the rest of this section
  describes the differences between the packages Tablelist and
  Tablelist_tile.</p>

  <p>The Tablelist_tile package checks whether the required Tk and tile
  versions are present, by executing the commands</p>

  <blockquote>
    <pre>
package require Tk 8.4
if {$::tk_version &lt; 8.5 || [regexp {^8\.5a[1-5]$} $::tk_patchLevel]} {
    package require tile 0.6
}
</pre>
  </blockquote>

  <p>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.</p>

  <p>Apart from this and the <code>_tile</code> suffix in the&nbsp;
  <code>package require</code>&nbsp; command, the only difference (from the
  programmer's point of view) between the packages Tablelist and Tablelist_tile
  is related to the supported configuration options:&nbsp; The
  <code>-highlightbackground</code>, <code>-highlightcolor</code>,
  <code>-highlightthickness</code>, <code>-labelbackground</code>,
  <code>-labelactivebackground</code>, <code>-labelactiveforeground</code>,
  <code>-labeldisabledforeground</code>, and <code>-labelheight</code> options
  (the latter at both widget and column levels), present in the Tablelist
  package, are not supported by Tablelist_tile.&nbsp; The first three are
  standard Tk widget options that are not available for tile widgets.&nbsp; The
  <code>-labelbackground</code> option stands for the <code>-background</code>
  option of the column labels, and current versions of the tile engine don't
  support setting the background color for these widgets with a special header
  layout.&nbsp; The remaining options stand for the
  <code>-activebackground</code>, <code>-activeforeground</code>,
  <code>-disabledforeground</code>, and <code>-height</code> options of the
  column labels, and these configuration options are not supported for tile
  label widgets.</p>

  <p>Also, take into account that in some themes, setting the
  <code>-labelborderwidth</code> option (at widget or column level) to a value
  other than the default might be ignored by tile and thus could cause
  alignment problems.&nbsp; This is because the border of tile widgets is drawn
  with theme-specific methods, which will not always produce the results known
  from Tk widgets.</p>

  <p>Finally, notice that, when using the <code>tileqt</code> theme, the
  version number of the <code>tile::theme::tileqt</code> package must be 0.4 or
  higher, and <code>tileqt</code> itself won't work with tile versions earlier
  than 0.7.</p>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="examples">Examples</h2>

  <h3 id="ex_config">A tablelist Widget for Displaying and Editing
  Configuration Options</h3>

  <p>The file <code>config.tcl</code> in the <code>demos</code> directory
  contains a procedure <code>demo::displayConfig</code> that displays the
  configuration options of an arbitrary widget in a tablelist contained in a
  newly created toplevel widget and allows you to edit these options.&nbsp;
  This procedure can prove to be quite useful during interactive GUI
  development.&nbsp; To test it, start <code>wish</code> and evaluate the file
  by using the <code>source</code> command as follows:</p>

  <ul>
    <li>
      If <code>wish</code> was started in the <code>demos</code> directory then
      it is sufficient to enter

      <blockquote>
        <pre>
source config.tcl
</pre>
      </blockquote>
    </li>

    <li>
      If <code>wish</code> was started in some other directory then you can use
      the <code>tablelist::library</code> variable to find the location of the
      file.&nbsp; For example, assuming that your Tablelist installation has
      the directory structure described in the <a href="#ov_install">How to
      install it?</a> section, the required commands are:

      <blockquote>
        <pre>
package require tablelist 6.8
source [file join $tablelist::library demos config.tcl]
</pre>
      </blockquote>
    </li>
  </ul>

  <p>In both cases, the script will print the following message to
  <code>stdout</code>:</p>

  <blockquote>
    <pre>
To display the configuration options of an arbitrary widget, enter

        demo::displayConfig &lt;widgetName&gt;
</pre>
  </blockquote>

  <p><code>&lt;widgetName&gt;</code> can be the path name of any already
  existing widget.&nbsp; For example, if you enter</p>

  <blockquote>
    <pre>
demo::displayConfig .
</pre>
  </blockquote>

  <p>then you will see that a tablelist widget <code>.configTop.tf.tbl</code>
  in a new toplevel window is created and its name is printed to
  <code>stdout</code>.&nbsp; If you then enter</p>

  <blockquote>
    <pre>
demo::displayConfig .configTop.tf.tbl
</pre>
  </blockquote>

  <p>then another toplevel window containing the tablelist widget
  <code>.configTop2.tf.tbl</code> will pop up.&nbsp; The latter looks like in
  the following figure:</p>

  <blockquote>
    <img src="config.png" alt="Configuration Options" width="835" height="402">
  </blockquote>

  <p>It is assumed that the Tcl command associated with the widget specified by
  <code>&lt;widgetName&gt;</code> has a <code>configure</code> subcommand
  which, when invoked without any argument, returns a list describing all of
  the available configuration options for the widget, in the common format
  known from the standard Tk widgets.&nbsp; The
  <code>demo::displayConfig</code> procedure inserts the items of this list
  into a scrolled tablelist with 5 dynamic-width columns and interactive sort
  capability, and returns the name of the newly created tablelist widget:</p>

  <blockquote>
    <pre>
package require tablelist 6.8

namespace eval demo {
    <span class="cmt">#
    # Get the current windowing system ("x11", "win32", "classic", or "aqua")
    # and add some entries to the Tk option database for the following
    # widget hierarchy within a toplevel widget of the class DemoTop:
    #
    # Name              Class
    # -----------------------------
    # tf                Frame
    #   tbl               Tabellist
    #   vsb, hsb          Scrollbar
    # bf                Frame
    #   b1, b2, b3        Button
    #</span>
    variable winSys
    if {[catch {tk windowingsystem} winSys] != 0} {
        switch $::tcl_platform(platform) {
            unix        { set winSys x11 }
            windows     { set winSys win32 }
            macintosh   { set winSys classic }
        }
    }
    if {[string compare $winSys "x11"] == 0} {
        <span class="cmt">#
        # Create the font TkDefaultFont if not yet present
        #</span>
        catch {font create TkDefaultFont -family Helvetica -size -12}

        option add *DemoTop*Font                        TkDefaultFont
        option add *DemoTop*selectBackground            #5294e2
        option add *DemoTop*selectForeground            white
    }
    option add *DemoTop.tf.borderWidth                  1
    option add *DemoTop.tf.relief                       sunken
    option add *DemoTop.tf.tbl.borderWidth              0
    option add *DemoTop.tf.tbl.highlightThickness       0
    option add *DemoTop.tf.tbl.background               white
    option add *DemoTop.tf.tbl.stripeBackground         #f0f0f0
    option add *DemoTop.tf.tbl.setGrid                  yes
    option add *DemoTop.tf.tbl*Entry.background         white
    option add *DemoTop.bf.Button.width                 10
}

<span class="cmt">#------------------------------------------------------------------------------
# demo::displayConfig
#
# Displays the configuration options of the widget w in a tablelist widget
# contained in a newly created toplevel widget.  Returns the name of the
# tablelist widget.
#------------------------------------------------------------------------------</span>
proc demo::displayConfig w {
    if {![winfo exists $w]} {
        bell
        tk_messageBox -title "Error" -icon error -message \
            "Bad window path name \"$w\""
        return ""
    }

    <span class="cmt">#
    # Create a toplevel widget of the class DemoTop
    #</span>
    set top .configTop
    for {set n 2} {[winfo exists $top]} {incr n} {
        set top .configTop$n
    }
    toplevel $top -class DemoTop
    wm title $top "Configuration Options of the [winfo class $w] Widget \"$w\""

    <span class="cmt">#
    # Create a scrolled tablelist widget with 5 dynamic-width
    # columns and interactive sort capability within the toplevel
    #</span>
    set tf $top.tf
    frame $tf
    set tbl $tf.tbl
    set vsb $tf.vsb
    set hsb $tf.hsb
    tablelist::tablelist $tbl \
        -columns {0 "Command-Line Name"
                  0 "Database/Alias Name"
                  0 "Database Class"
                  0 "Default Value"
                  0 "Current Value"} \
        -labelcommand tablelist::sortByColumn -sortcommand demo::compareAsSet \
        -editendcommand demo::applyValue -height 15 -width 100 -stretch all \
        -xscrollcommand [list $hsb set] -yscrollcommand [list $vsb set]
    if {[$tbl cget -selectborderwidth] == 0} {
        $tbl configure -spacing 1
    }
    $tbl columnconfigure 3 -maxwidth 30
    $tbl columnconfigure 4 -maxwidth 30 -editable yes
    scrollbar $vsb -orient vertical   -command [list $tbl yview]
    scrollbar $hsb -orient horizontal -command [list $tbl xview]

    <span class="cmt">#
    # Create three buttons within a frame child of the toplevel widget
    #</span>
    set bf $top.bf
    frame $bf
    set b1 $bf.b1
    set b2 $bf.b2
    set b3 $bf.b3
    button $b1 -text "Refresh"     -command [list demo::putConfig $w $tbl]
    button $b2 -text "Sort as Set" -command [list $tbl sort]
    button $b3 -text "Close"       -command [list destroy $top]

    <span class="cmt">#
    # Manage the widgets
    #</span>
    grid $tbl -row 0 -rowspan 2 -column 0 -sticky news
    variable winSys
    if {[string compare $winSys "win32"] == 0} {
        grid $vsb -row 0 -rowspan 2 -column 1 -sticky ns
    } else {
        grid [$tbl cornerpath] -row 0 -column 1 -sticky ew
        grid $vsb              -row 1 -column 1 -sticky ns
    }
    grid $hsb -row 2 -column 0 -sticky ew
    grid rowconfigure    $tf 1 -weight 1
    grid columnconfigure $tf 0 -weight 1
    pack $b1 $b2 $b3 -side left -expand yes -pady 10
    pack $bf -side bottom -fill x
    pack $tf -side top -expand yes -fill both

    <span class="cmt">#
    # Populate the tablelist with the configuration options of the given widget
    #</span>
    putConfig $w $tbl
    return $tbl
}
</pre>
  </blockquote>

  <p>The procedure invokes the <code><a href=
  "tablelistWidget.html">tablelist::tablelist</a></code> command to create a
  tablelist widget.&nbsp; The value of the <code><a href=
  "tablelistWidget.html#columns">-columns</a></code> option passed to this
  command specifies the widths, titles, and alignments of the 5 columns.&nbsp;
  The width of each column is given as <code>0</code>, specifying that the
  column's width is to be made just large enough to hold all the elements in
  the column, including its title, which is the string following the
  width.&nbsp; We have omitted the alignment specifications (which can
  optionally follow the titles), because the columns shall all be
  left-justified.</p>

  <p>Since all columns are of dynamic width and left-aligned, instead of
  <code>-columns</code> we could have used the <code><a href=
  "tablelistWidget.html#columntitles">-columntitles</a></code> option as
  follows:</p>

  <blockquote>
    <pre>
    tablelist::tablelist $tbl \
        -columntitles {"Command-Line Name"
                       "Database/Alias Name"
                       "Database Class"
                       "Default Value"
                       "Current Value"} \
        . . .
</pre>
  </blockquote>

  <p>The command <code><a href=
  "tablelistColSort.html#sortByColumn">tablelist::sortByColumn</a></code>,
  specified as the value of the <code><a href=
  "tablelistWidget.html#labelcommand">-labelcommand</a></code> option, will be
  invoked whenever mouse button 1 is released over one of the labels.&nbsp;
  This command sorts the items based on the column corresponding to that label,
  in the right order, by invoking the <code><a href=
  "tablelistWidget.html#sortbycolumn">sortbycolumn</a></code> subcommand of the
  Tcl command associated with the tablelist widget.</p>

  <p>As seen from the creation of the button displaying the text&nbsp;
  <code>"Sort as Set"</code>,&nbsp; the items will also be sorted by invoking
  the <code><a href="tablelistWidget.html#sort">sort</a></code>
  subcommand.&nbsp; This makes it necessary to specify a command to be used for
  the comparison of the items, as the value of the <code><a href=
  "tablelistWidget.html#sortcommand">-sortcommand</a></code> option.&nbsp; In
  our example this is the <code>demo::compareAsSet</code> procedure shown
  below.</p>

  <p>The <code><a href=
  "tablelistWidget.html#editendcommand">-editendcommand</a></code> option
  specifies the command to be invoked automatically whenever the interactive
  editing of a cell's content is finished and the final content of the
  temporary embedded entry widget used for the editing are different from its
  original one.&nbsp; Per default, the elements of a tablelist widget can only
  be edited programmatically, but we enable the interactive editing for the
  cells of the last column with the aid of the <code><a href=
  "tablelistWidget.html#col_editable">-editable</a></code> column configuration
  option.</p>

  <p>By specifying the value <code>all</code> for the <code><a href=
  "tablelistWidget.html#stretch">-stretch</a></code> configuration option we
  make sure that all of the columns will be stretched to eliminate the blank
  space that might appear at the right of the table.</p>

  <p>If the default value of the <code>-selectborderwidth</code> option is
  <code>0</code> (this is the case on the Windows and Macintosh platforms, and
  also in an X11 envronment with Tk 8.5 or above) then we use the
  <code><a href="tablelistWidget.html#spacing">-spacing</a></code> option to
  provide some additional space above and below the rows.</p>

  <p>For the last two columns of the tablelist we use the <code><a href=
  "tablelistWidget.html#col_maxwidth">-maxwidth</a></code> column configuration
  option, to make sure that the dynamic widths of these columns won't exceed 30
  average-width characters.</p>

  <p>Besides the options given on the command line, our tablelist widget will
  automatically inherit the ones contained in the Tk option database entries
  specified in the namespace initialization preceding the
  <code>demo::displayConfig</code> procedure.&nbsp; The database name
  <code>stripeBackground</code> corresponds to the <code><a href=
  "tablelistWidget.html#stripebackground">-stripebackground</a></code>
  configuration option.&nbsp; According to this entry, every other row of the
  tablelist widget will be displayed in the background color
  <code>#f0f0f0</code>, which improves the readability of the items and gives
  the widget a nice appearance.</p>

  <p>The option database entries for <code>*DemoTop.tf.borderWidth</code>,
  <code>*DemoTop.tf.relief</code>, <code>*DemoTop.tf.tbl.borderWidth</code>,
  and <code>*DemoTop.tf.tbl.highlightThickness</code> are implicitly used when
  managing the tablelist widget and the two scrollbars with the aid of
  <code>grid</code>.&nbsp; Notice how the <code><a href=
  "tablelistWidget.html#cornerpath">cornerpath</a></code> subcommand enables us
  to achieve a native look & feel with respect to the vertical scrollbar on the
  windowing systems other than <code>win32</code> (i.e., <code>aqua</code> and
  <code>x11</code>).</p>

  <p>We populate the tablelist by invoking the <code>demo::putConfig</code>
  procedure discussed below.&nbsp; The same script is associated with the
  <b>Refresh</b> button, as the value of its <code>-command</code>
  configuration option.&nbsp; This procedure is implemented as follows:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# demo::putConfig
#
# Outputs the configuration options of the widget w into the tablelist widget
# tbl.
#------------------------------------------------------------------------------</span>
proc demo::putConfig {w tbl} {
    if {![winfo exists $w]} {
        bell
        tk_messageBox -title "Error" -icon error -message \
            "Bad window path name \"$w\"" -parent [winfo toplevel $tbl]
        return ""
    }

    <span class="cmt">#
    # Display the configuration options of w in the tablelist widget tbl
    #</span>
    $tbl delete 0 end
    foreach configSet [$w configure] {
        <span class="cmt">#
        # Insert the list configSet into the tablelist widget
        #</span>
        $tbl insert end $configSet

        if {[llength $configSet] == 2} {
            $tbl rowconfigure end -foreground gray50 -selectforeground gray75
            $tbl cellconfigure end -editable no
        } else {
            <span class="cmt">#
            # Change the colors of the first and last cell of the row
            # if the current value is different from the default one
            #</span>
            set default [lindex $configSet 3]
            set current [lindex $configSet 4]
            if {[string compare $default $current] != 0} {
                foreach col {0 4} {
                    $tbl cellconfigure end,$col \
                         -foreground red -selectforeground yellow
                }
            }
        }
    }

    $tbl sortbycolumn 0
    $tbl activate 0
    $tbl attrib widget $w
}
</pre>
  </blockquote>

  <p>After deleting the current items of the tablelist widget <code>tbl</code>,
  the procedure inserts the items of the list returned by the
  <code>configure</code> subcommand of the Tcl command associated with the
  widget <code>w</code>.&nbsp; For each option that is merely an abbreviated
  form of some other one, we use the <code><a href=
  "tablelistWidget.html#rowconfigure">rowconfigure</a></code> tablelist
  subcommand to change the normal and selection foreground colors of the item
  just appended, and we disable the interactive editing in the last inserted
  cell by using the <code><a href=
  "tablelistWidget.html#cell_editable">-editable</a></code> cell configuration
  option.&nbsp; The <code><a href=
  "tablelistWidget.html#cellconfigure">cellconfigure</a></code> tablelist
  operation is also invoked for each real option whose current value is
  different from the default one, to change the values of the
  <code>-foreground</code> and <code>-selectforeground</code> options of the
  cells no. 0 and 4, containing the command-line name of the option and its
  current value.</p>

  <p>Each tablelist widget may have any number of private <b>attributes</b>,
  which can be set and retrieved with the aid of the <code><a href=
  "tablelistWidget.html#attrib">attrib</a></code> subcommand of the Tcl command
  corresponding to the widget.&nbsp; The <code>demo::putConfig</code> procedure
  sets the <code>widget</code> attribute to the name of the widget whose
  options are displayed in the tablelist.</p>

  <p>The implementation of the comparison command
  <code>demo::compareAsSet</code> mentioned above is quite simple:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# demo::compareAsSet
#
# Compares two items of a tablelist widget used to display the configuration
# options of an arbitrary widget.  The item in which the current value is
# different from the default one is considered to be less than the other; if
# both items fulfil this condition or its negation then string comparison is
# applied to the two option names.
#------------------------------------------------------------------------------</span>
proc demo::compareAsSet {item1 item2} {
    foreach {opt1 dbName1 dbClass1 default1 current1} $item1 \
            {opt2 dbName2 dbClass2 default2 current2} $item2 {
        set changed1 [expr {[string compare $default1 $current1] != 0}]
        set changed2 [expr {[string compare $default2 $current2] != 0}]
        if {$changed1 == $changed2} {
            return [string compare $opt1 $opt2]
        } elseif {$changed1} {
            return -1
        } else {
            return 1
        }
    }
}
</pre>
  </blockquote>

  <p>Finally, here is the implementation of the <code>demo::applyValue</code>
  procedure, specified as the value of the <code>-editendcommand</code>
  option:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# demo::applyValue
#
# Applies the new value of the configuraton option contained in the given row
# of the tablelist widget tbl to the widget whose options are displayed in it,
# and updates the colors of the first and last cell of the row.
#------------------------------------------------------------------------------</span>
proc demo::applyValue {tbl row col text} {
    <span class="cmt">#
    # Try to apply the new value of the option contained in
    # the given row to the widget whose options are displayed
    # in the tablelist; reject the value if the attempt fails
    #</span>
    set w [$tbl attrib widget]
    set opt [$tbl cellcget $row,0 -text]
    if {[catch {$w configure $opt $text} result] != 0} {
        bell
        tk_messageBox -title "Error" -icon error -message $result \
            -parent [winfo toplevel $tbl]
        $tbl rejectinput
        return ""
    }

    <span class="cmt">#
    # Replace the new option value with its canonical form and
    # update the colors of the first and last cell of the row
    #</span>
    set text [$w cget $opt]
    set default [$tbl cellcget $row,3 -text]
    if {[string compare $default $text] == 0} {
        foreach col {0 4} {
            $tbl cellconfigure $row,$col \
                 -foreground "" -selectforeground ""
        }
    } else {
        foreach col {0 4} {
            $tbl cellconfigure $row,$col \
                 -foreground red -selectforeground yellow
        }
    }

    return $text
}
</pre>
  </blockquote>

  <p>The procedure retrieves the name of the widget whose options are displayed
  in the tablelist, as the value of its <code>widget</code> attribute, and
  invokes the <code><a href="tablelistWidget.html#cellcget">cellcget</a></code>
  tablelist subcommand to get the name of the option specified in the first
  cell of the row whose last element was just edited.&nbsp; Next, it tries to
  apply the new value of the option to the widget, and invokes the
  <code><a href="tablelistWidget.html#rejectinput">rejectinput</a></code>
  subcommand if the attempt fails.&nbsp; Otherwise it replaces the new option
  value with its canonical form and updates the normal and selection foreground
  colors of the cells no. 0 and 4.&nbsp; The canonical form of the option value
  is given by the <code>cget</code> subcommand of the Tcl command associated
  with that widget.&nbsp; For example, a boolean value will always be replaced
  with <code>1</code> or <code>0</code>, even if the entry contains the string
  <code>yes</code> or <code>no</code>.&nbsp; The procedure returns this
  canonical option value, thus making sure that the latter will become the new
  content of the cell that was just edited.</p>

  <h3 id="ex_browse">Two Widget Browsers Based on a tablelist</h3>

  <p>The files <code>browse.tcl</code> and <code>browseTree.tcl</code> in the
  <code>demos</code> directory contain a procedure
  <code>demo::displayChildren</code> that displays information about the
  children of an arbitrary widget in a tablelist contained in a newly created
  toplevel widget.&nbsp; To test it, start <code>wish</code> and evaluate the
  chosen file by using the <code>source</code> command, in a similar way as in
  the case of the <a href="#ex_config">previous example</a>.</p>

  <p>Both scripts will print the following message to <code>stdout</code>:</p>

  <blockquote>
    <pre>
To display information about the children of an arbitrary widget, enter

        demo::displayChildren &lt;widgetName&gt;
</pre>
  </blockquote>

  <p><code>&lt;widgetName&gt;</code> can be the path name of any already
  existing widget.&nbsp; For example, if you enter</p>

  <blockquote>
    <pre>
demo::displayChildren .
</pre>
  </blockquote>

  <p>then you will see that a tablelist widget <code>.browseTop.tf.tbl</code>
  in a new toplevel window is created and its name is printed to
  <code>stdout</code>.</p>

  <p>The tablelist created by the procedure <code>demo::displayChildren</code>
  in the file <code>browse.tcl</code> is a multi-column listbox:</p>

  <blockquote>
    <img src="browse.png" alt="Widget Browser" width="605" height="299">
  </blockquote>

  <p>The tablelist created by the procedure of the same name in the file
  <code>browseTree.tcl</code> is a multi-column tree widget:</p>

  <blockquote>
    <img src="browseTree.png" alt="Widget Browser" width="619" height="299">
  </blockquote>

  <p>The <code>demo::displayChildren</code> command inserts some data of the
  children of the widget specified by <code>&lt;widgetName&gt;</code> into a
  vertically scrolled tablelist with 9 dynamic-width columns and interactive
  sort capability, and returns the name of the newly created tablelist
  widget.&nbsp; By double-clicking an item (e.g., the one containing the path
  name <code>.browseTop</code> in <code>browse.tcl</code> and the name
  <code>browseTop</code> in <code>browseTree.tcl</code>) or invoking the first
  entry of a pop-up menu within the body of the tablelist, you can display the
  data of the children of the widget corresponding to the selected item, and
  with the second menu entry you can display its configuration options (see the
  <a href="#ex_config">previous example</a> for details).&nbsp; To go one level
  up, click on the <b>Parent</b> button.</p>

  <p>There is a lot of code common to the scripts <code>browse.tcl</code> and
  <code>browseTree.tcl</code>.&nbsp; We will restrict the description below to
  the second one, which requires Tk 8.3 or later, due to the use of several
  tree-related tablelist options and subcommands.</p>

  <blockquote>
    <pre>
package require Tk 8.3
package require tablelist 6.8

namespace eval demo {
    variable dir [file dirname [info script]]

    <span class="cmt">#
    # Create two images, needed in the procedure putChildren
    #</span>
    variable leafImg [image create bitmap -file [file join $dir leaf.xbm] \
                      -background coral -foreground gray50]
    variable compImg [image create bitmap -file [file join $dir comp.xbm] \
                      -background yellow -foreground gray50]
}

source [file join $demo::dir config.tcl]

<span class="cmt">#------------------------------------------------------------------------------
# demo::displayChildren
#
# Displays information on the children of the widget w in a tablelist widget
# contained in a newly created toplevel widget.  Returns the name of the
# tablelist widget.
#------------------------------------------------------------------------------</span>
proc demo::displayChildren w {
    if {![winfo exists $w]} {
        bell
        tk_messageBox -title "Error" -icon error -message \
            "Bad window path name \"$w\""
        return ""
    }

    <span class="cmt">#
    # Create a toplevel widget of the class DemoTop
    #</span>
    set top .browseTop
    for {set n 2} {[winfo exists $top]} {incr n} {
        set top .browseTop$n
    }
    toplevel $top -class DemoTop

    <span class="cmt">#
    # Create a vertically scrolled tablelist widget with 9 dynamic-width
    # columns and interactive sort capability within the toplevel
    #</span>
    set tf $top.tf
    frame $tf
    set tbl $tf.tbl
    set vsb $tf.vsb
    tablelist::tablelist $tbl \
        -columns {0 "Name"      left
                  0 "Class"     left
                  0 "X"         right
                  0 "Y"         right
                  0 "Width"     right
                  0 "Height"    right
                  0 "Mapped"    center
                  0 "Viewable"  center
                  0 "Manager"   left} \
        -expandcommand demo::expandCmd -labelcommand demo::labelCmd \
        -yscrollcommand [list $vsb set] -setgrid no -width 0
    if {[$tbl cget -selectborderwidth] == 0} {
        $tbl configure -spacing 1
    }
    foreach col {2 3 4 5} {
        $tbl columnconfigure $col -sortmode integer
    }
    foreach col {6 7} {
        $tbl columnconfigure $col -formatcommand demo::formatBoolean
    }
    scrollbar $vsb -orient vertical -command [list $tbl yview]

    <span class="cmt">#
    # When displaying the information about the children of any
    # ancestor of the label widgets, the widths of some of the
    # labels and thus also the widths and x coordinates of some
    # children may change.  For this reason, make sure the items
    # will be updated after any change in the sizes of the labels
    #</span>
    foreach l [$tbl labels] {
        bind $l &lt;Configure&gt; [list demo::updateItemsDelayed $tbl]
    }
    bind $tbl &lt;Configure&gt; [list demo::updateItemsDelayed $tbl]

    <span class="cmt">#
    # Create a pop-up menu with two command entries; bind the script
    # associated with its first entry to the &lt;Double-1&gt; event, too
    #</span>
    set menu $top.menu
    menu $menu -tearoff no
    $menu add command -label "Display Children" \
                      -command [list demo::putChildrenOfSelWidget $tbl]
    $menu add command -label "Display Config" \
                      -command [list demo::dispConfigOfSelWidget $tbl]
    set bodyTag [$tbl bodytag]
    bind $bodyTag &lt;Double-1&gt;   [list demo::putChildrenOfSelWidget $tbl]
    bind $bodyTag &lt;&lt;Button3&gt;&gt;  [bind TablelistBody &lt;Button-1&gt;]
    bind $bodyTag &lt;&lt;Button3&gt;&gt; +[bind TablelistBody &lt;ButtonRelease-1&gt;]
    bind $bodyTag &lt;&lt;Button3&gt;&gt; +[list demo::postPopupMenu $top %X %Y]

    <span class="cmt">#
    # Create three buttons within a frame child of the toplevel widget
    #</span>
    set bf $top.bf
    frame $bf
    set b1 $bf.b1
    set b2 $bf.b2
    set b3 $bf.b3
    button $b1 -text "Refresh"
    button $b2 -text "Parent"
    button $b3 -text "Close" -command [list destroy $top]

    <span class="cmt">#
    # Manage the widgets
    #</span>
    . . .

    <span class="cmt">#
    # Populate the tablelist with the data of the given widget's children
    #</span>
    putChildren $w $tbl root
    return $tbl
}
</pre>
  </blockquote>

  <p>The procedure invokes the <code><a href=
  "tablelistWidget.html">tablelist::tablelist</a></code> command to create a
  tablelist widget.&nbsp; The value of the <code><a href=
  "tablelistWidget.html#columns">-columns</a></code> option passed to this
  command specifies the widths, titles, and alignments of the 9 columns.&nbsp;
  The width of each column is given as <code>0</code>, specifying that the
  column's width is to be made just large enough to hold all the elements in
  the column, including its title, which is the string following the
  width.&nbsp; Each of the titles is followed by an alignment, which indicates
  how to justify both the elements and the title of the respective column.</p>

  <p>We want to display not only the data of the given widget's children, but
  also those of its further descendants.&nbsp; To this end, we need a command
  to be invoked whenever an item corresponding to a widget with children gets
  expanded.&nbsp; This command is specified as the value of the <code><a href=
  "tablelistWidget.html#expandcommand">-expandcommand</a></code> option.&nbsp;
  As discussed later, the <code>demo::expandCmd</code> procedure will insert
  the children of the row that is about to be expanded, if it has no children
  yet.</p>

  <p>The command <code>demo::labelCmd</code>, specified as the value of the
  <code><a href="tablelistWidget.html#labelcommand">-labelcommand</a></code>
  option, will be invoked whenever mouse button 1 is released over one of the
  labels.&nbsp; We will discuss this procedure later.</p>

  <p>We specify the value <code>0</code> for the widget's <code><a href=
  "tablelistWidget.html#width">-width</a></code> option, meaning that the
  tablelist's width shall be made just large enough to hold all its
  columns.</p>

  <p>After creating the tablelist widget, we make sure that the elements of its
  columns 2, 3, 4, and 5 (displaying the x and y coordinates as well as the
  widths and heights of the children) will be compared as integers when sorting
  the items based on one of these columns.&nbsp; We do this with the aid of the
  <code><a href=
  "tablelistWidget.html#columnconfigure">columnconfigure</a></code> tablelist
  operation.</p>

  <p>The same <code>columnconfigure</code> subcommand enables us to specify
  that, when displaying the elements of columns 6 and 7 (having the titles
  <code>"Mapped"</code> and <code>"Viewable"</code>, respectively), the boolean
  values <code>1</code> and <code>0</code> will be replaced with the strings
  <code>"yes"</code> and <code>"no"</code>, returned by the
  <code>demo::formatBoolean</code> command shown below.</p>

  <p>After creating the vertical scrollbar, we iterate over the elements of the
  list containing the path names of all header labels of the tablelist widget,
  returned by the <code><a href="tablelistWidget.html#labels">labels</a></code>
  subcommand of the Tcl command corresponding to the widget.&nbsp; For each
  element of the list, we bind the procedure
  <code>demo::updateItemsDelayed</code> to the <code>&lt;Configure&gt;</code>
  event.&nbsp; In this way we make sure the procedure will be invoked whenever
  the header label indicated by that list element changes size.</p>

  <p>The four invocations of the <code>bind</code> command following the
  creation of the pop-up menu make use of a binding tag whose name depends on
  the path name of the tablelist widget and is returned by the <code><a href=
  "tablelistWidget.html#bodytag">bodytag</a></code> subcommand of the Tcl
  command associated with the tablelist widget.&nbsp; The advantage of using
  this tag instead of the path name of the tablelist's body is that this
  binding tag is associated not only with the body but also with the separator
  frames and with the labels displaying embedded images.&nbsp; This is
  important in our example because we want to make sure the
  <code>&lt;&lt;Button3&gt;&gt;</code> and <code>&lt;Double-1&gt;</code> events
  will be handled in the same way within a label containing an embedded image
  as in the rest of the tablelist's body.&nbsp; Both the <code><a href=
  "tablelistWidget.html#button3">&lt;&lt;Button3&gt;&gt;</a></code> virtual
  event (used in the first three <code>bind</code> commands) and the
  <code><a href="tablelistWidget.html#body_bindings">TablelistBody</a></code>
  binding tag (used in the first binding script) are created by the Tablelist
  package.&nbsp; The first three <code>bind</code> commands make sure that a
  <code>&lt;&lt;Button3&gt;&gt;</code> virtual event will select and activate
  the nearest item and will post a pop-up menu with two command entries that
  refer to the widget described by that item.</p>

  <p>We populate the tablelist by invoking the <code>demo::putChildren</code>
  procedure, implemented as follows:</p>

  <blockquote id="putChildren">
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# demo::putChildren
#
# Outputs the data of the children of the widget w into the tablelist widget
# tbl, as child items of the one identified by nodeIdx.
#------------------------------------------------------------------------------</span>
proc demo::putChildren {w tbl nodeIdx} {
    . . .

    if {[string compare $nodeIdx "root"] == 0} {
        set top [winfo toplevel $tbl]
        wm title $top "Children of the [winfo class $w] Widget \"$w\""

        $tbl resetsortinfo
        $tbl delete 0 end
        set row 0
    } else {
        set row [expr {$nodeIdx + 1}]
    }

    <span class="cmt">#
    # Display the data of the children of the
    # widget w in the tablelist widget tbl
    #</span>
    variable leafImg
    variable compImg
    foreach c [winfo children $w] {
        <span class="cmt">#
        # Insert the data of the current child into the tablelist widget
        #</span>
        set item {}
        lappend item \
                [winfo name $c] [winfo class $c] [winfo x $c] [winfo y $c] \
                [winfo width $c] [winfo height $c] [winfo ismapped $c] \
                [winfo viewable $c] [winfo manager $c]
        $tbl insertchild $nodeIdx end $item

        <span class="cmt">#
        # Insert an image into the first cell of the row; mark the
        # row as collapsed if the child widget has children itself
        #</span>
        if {[llength [winfo children $c]] == 0} {
            $tbl cellconfigure end,0 -image $leafImg
        } else {
            $tbl cellconfigure end,0 -image $compImg
            $tbl collapse $row
        }

        $tbl rowattrib $row pathName $c
        incr row
    }

    if {[string compare $nodeIdx "root"] == 0} {
        <span class="cmt">#
        # Configure the "Refresh" and "Parent" buttons
        #</span>
        $top.bf.b1 configure -command [list demo::refreshView $w $tbl]
        set b2 $top.bf.b2
        set p [winfo parent $w]
        if {[string compare $p ""] == 0} {
            $b2 configure -state disabled
        } else {
            $b2 configure -state normal -command \
                [list demo::putChildren $p $tbl root]
        }
    }
}
</pre>
  </blockquote>

  <p>The last argument of this procedure indicates the tree node to become the
  parent of the items displaying the data of the children of the widget passed
  as first argument.&nbsp; If this parent is the invisible <code>root</code>
  node then we first reset the sorting information by invoking the
  <code><a href="tablelistWidget.html#resetsortinfo">resetsortinfo</a></code>
  tablelist subcommand and delete the current items of the tablelist widget
  <code>tbl</code>.&nbsp; The procedure then iterates over the children of the
  specified widget and inserts the items built from some data retrieved by
  using the <code>winfo</code> command.&nbsp; Each new item is added to the end
  of the parent node's list of children with the aid of the <code><a href=
  "tablelistWidget.html#insertchildren">insertchild(ren)</a></code>
  subcommand.</p>

  <p>For each child widget, we invoke the <code><a href=
  "tablelistWidget.html#cellconfigure">cellconfigure</a></code> tablelist
  operation to set the value of the <code>-image</code> option of the
  corresponding row's first cell, containing the leaf name of the child.&nbsp;
  In this way, the procedure inserts the image <code>$leafImg</code> or
  <code>$compImg</code> into the first cell, depending on whether the child in
  question is a leaf or a composite widget.&nbsp; (Remember that both images
  were created outside this procedure, within the initialization of the
  <code>demo</code> namespace.)</p>

  <p>We mark every newly created row corresponding to a child widget that has
  children itself as collapsed by invoking the <code><a href=
  "tablelistWidget.html#collapse">collapse</a></code> subcommand.&nbsp; This
  will prepend an expand/collapse control to the content of the first column,
  whose column index <code>0</code> is the default value of the <code><a href=
  "tablelistWidget.html#treecolumn">-treecolumn</a></code> configuration
  option.</p>

  <p>We use the <code><a href=
  "tablelistWidget.html#rowattrib">rowattrib</a></code> tablelist subcommand to
  remember the full path name of every child widget as a private attribute
  associated with the corresponding tablelist row, because it will be needed at
  several places later on.</p>

  <p>As mentioned above, the <code>demo::expandCmd</code> procedure will be
  invoked automatically when expanding a row that contains an expand/collapse
  control:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# demo::expandCmd
#
# Outputs the data of the children of the widget whose leaf name is displayed
# in the first cell of the specified row of the tablelist widget tbl, as child
# items of the one identified by row.
#------------------------------------------------------------------------------</span>
proc demo::expandCmd {tbl row} {
    if {[$tbl childcount $row] == 0} {
        set w [$tbl rowattrib $row pathName]
        putChildren $w $tbl $row

        <span class="cmt">#
        # Apply the last sorting (if any) to the new items
        #</span>
        $tbl refreshsorting $row
    }
}
</pre>
  </blockquote>

  <p>The procedure invokes the <code><a href=
  "tablelistWidget.html#childcount">childcount</a></code> subcommand to check
  whether the children of the row that is about to be expanded have already
  been inserted into the tablelist widget, and inserts them if this is not the
  case.&nbsp; It also makes sure that the child items will be displayed in the
  order corresponding to the last sorting (if any), with the aid of the
  <code><a href="tablelistWidget.html#refreshsorting">refreshsorting</a></code>
  tablelist subcommand.&nbsp; Any sorting (if needed) will only be performed on
  the child items just inserted into the tablelist widget.</p>

  <p>The <code>demo::formatBoolean</code> and <code>demo::labelCmd</code>
  procedures mentioned above are trivial:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# demo::formatBoolean
#
# Returns "yes" or "no", according to the specified boolean value.
#------------------------------------------------------------------------------</span>
proc demo::formatBoolean val {
    return [expr {$val ? "yes" : "no"}]
}

<span class="cmt">#------------------------------------------------------------------------------
# demo::labelCmd
#
# Sorts the content of the tablelist widget tbl by its col'th column and makes
# sure the items will be updated 500 ms later (because one of the items might
# refer to a canvas containing the arrow that displays the sorting order).
#------------------------------------------------------------------------------</span>
proc demo::labelCmd {tbl col} {
    tablelist::sortByColumn $tbl $col
    updateItemsDelayed $tbl
}
</pre>
  </blockquote>

  <p>The command <code><a href=
  "tablelistColSort.html#sortByColumn">tablelist::sortByColumn</a></code> sorts
  the items of the tablelist widget by the specified column in the right order,
  by invoking the <code><a href=
  "tablelistWidget.html#sortbycolumn">sortbycolumn</a></code> subcommand of the
  Tcl command associated with the tablelist widget.</p>

  <p>The implementation of the <code>demo::updateItemsDelayed</code> command,
  invoked in this procedure and already encountered in the
  <code>demo::displayChildren</code> procedure above, is quite simple:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# demo::updateItemsDelayed
#
# Arranges for the items of the tablelist widget tbl to be updated 500 ms later.
#------------------------------------------------------------------------------</span>
proc demo::updateItemsDelayed tbl {
    <span class="cmt">#
    # Schedule the demo::updateItems command for execution
    # 500 ms later, but only if it is not yet pending
    #</span>
    if {[string compare [$tbl attrib afterId] ""] == 0} {
        $tbl attrib afterId [after 500 [list demo::updateItems $tbl]]
    }
}

<span class="cmt">#------------------------------------------------------------------------------
# demo::updateItems
#
# Updates the items of the tablelist widget tbl.
#------------------------------------------------------------------------------</span>
proc demo::updateItems tbl {
    <span class="cmt">#
    # Reset the tablelist's "afterId" attribute
    #</span>
    $tbl attrib afterId ""

    <span class="cmt">#
    # Update the items
    #</span>
    set rowCount [$tbl size]
    for {set row 0} {$row &lt; $rowCount} {incr row} {
        set c [$tbl cellcget $row,0 -text]
        if {![winfo exists $c]} {
            continue
        }

        set item {}
        lappend item \
                [winfo name $c] [winfo class $c] [winfo x $c] [winfo y $c] \
                [winfo width $c] [winfo height $c] [winfo ismapped $c] \
                [winfo viewable $c] [winfo manager $c]
        $tbl rowconfigure $row -text $item
    }

    <span class="cmt">#
    # Repeat the last sort operation (if any)
    #</span>
    $tbl refreshsorting
}
</pre>
  </blockquote>

  <p>As already mentioned in the <a href="#ex_config">previous example</a>,
  each tablelist widget may have any number of private attributes, which can be
  set and retrieved with the aid of the <code><a href=
  "tablelistWidget.html#attrib">attrib</a></code> subcommand of the Tcl command
  corresponding to the widget.&nbsp; The <code>afterId</code> attribute is set
  by the <code>demo::updateItemsDelayed</code> procedure when sheduling the
  <code>demo::updateItems</code> command for execution 500 ms later, but only
  if its value is an empty string.&nbsp; For this reason, the
  <code>demo::updateItems</code> procedure resets this attribute.&nbsp; It also
  makes use of the <code><a href=
  "tablelistWidget.html#cellcget">cellcget</a></code> tablelist subcommand to
  get the path names contained in the first cell of each row, and updates the
  data of the children with the aid of the <code><a href=
  "tablelistWidget.html#rowconfigure">rowconfigure</a></code> subcommand.&nbsp;
  After updating the items, the procedure repeats the most recent sorting based
  on a column (if there was one), with the aid of the <code><a href=
  "tablelistWidget.html#refreshsorting">refreshsorting</a></code>
  subcommand.</p>

  <p>The procedures <code>demo::putChildrenOfSelWidget</code>,
  <code>demo::dispConfigOfSelWidget</code>, and
  <code>demo::postPopupMenu</code> (see <code>demo::displayChildren</code>) are
  also straight-forward.&nbsp; For example, the
  <code>demo::putChildrenOfSelWidget</code> command shown below makes use of
  the <code><a href="tablelistWidget.html#curselection">curselection</a></code>
  subcommand to get the index of the selected row.&nbsp; More precisely,
  <code>curselection</code> returns a list, but in our case this list will have
  exactly one element, hence it can be used directly as the first component of
  a cell index.</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# demo::putChildrenOfSelWidget
#
# Outputs the data of the children of the selected widget into the tablelist
# widget tbl.
#------------------------------------------------------------------------------</span>
proc demo::putChildrenOfSelWidget tbl {
    set w [$tbl cellcget [$tbl curselection],0 -text]
    if {![winfo exists $w]} {
        bell
        tk_messageBox -title "Error" -icon error -message \
            "Bad window path name \"$w\"" -parent [winfo toplevel $tbl]
        return ""
    }

    if {[llength [winfo children $w]] == 0} {
        bell
    } else {
        putChildren $w $tbl
    }
}
</pre>
  </blockquote>

  <p>The procedure <code>demo::refreshView</code>, associated with the
  <b>Refresh</b> button, is implemented as follows:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# demo::refreshView
#
# Redisplays the data of the children of the widget w in the tablelist widget
# tbl and restores the expanded states of the items as well as the vertical
# view.
#------------------------------------------------------------------------------</span>
proc demo::refreshView {w tbl} {
    <span class="cmt">#
    # Save the vertical view and get the path names of
    # the child widgets displayed in the expanded rows
    #</span>
    set yView [$tbl yview]
    foreach key [$tbl expandedkeys] {
        set pathName [$tbl rowattrib $key pathName]
        set expandedWidgets($pathName) 1
    }

    <span class="cmt">#
    # Redisplay the data of the widget's (possibly changed) children and
    # restore the expanded states of the children, along with the vertical view
    #</span>
    putChildren $w $tbl root
    restoreExpandedStates $tbl root expandedWidgets
    $tbl yview moveto [lindex $yView 0]
}
</pre>
  </blockquote>

  <p>Before redisplaying the tablelist's content via
  <code>demo::putChildren</code>, we get the full keys of the currently
  expanded items with the aid of the <code><a href=
  "tablelistWidget.html#expandedkeys">expandedkeys</a></code> tablelist
  subcommand and insert the correspondig widget paths into the array
  <code>expandedWidgets</code>.&nbsp; After redisplaying the data of the
  (possibly changed) children of the widget given as first argument, we pass
  this array to the <code>demo::restoreExpandedStates</code> procedure shown
  below:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# restoreExpandedStates
#
# Expands those children of the parent identified by nodeIdx that display the
# data of child widgets whose path names are the names of the elements of the
# array specified by the last argument.
#------------------------------------------------------------------------------</span>
proc demo::restoreExpandedStates {tbl nodeIdx expandedWidgetsName} {
    upvar $expandedWidgetsName expandedWidgets

    foreach key [$tbl childkeys $nodeIdx] {
        set pathName [$tbl rowattrib $key pathName]
        if {[info exists expandedWidgets($pathName)]} {
            $tbl expand $key -partly
            restoreExpandedStates $tbl $key expandedWidgets
        }
    }
}
</pre>
  </blockquote>

  <p>The procedure retrieves the list of full keys of the children of the
  parent node indicated by <code>nodeIdx</code>, by means of the <code><a href=
  "tablelistWidget.html#childkeys">childkeys</a></code> tablelist
  subcommand.&nbsp; It then loops over this list, and for each key for which
  the corresponding row was previously expanded, it invokes the <code><a href=
  "tablelistWidget.html#expand">expand</a></code> tablelist subcommand and then
  calls itself recursively to restore the expanded states of that row's
  children.</p>

  <h3 id="ex_dirViewer">A Directory Viewer Based on a tablelist</h3>

  <p>The script <code>dirViewer.tcl</code> in the <code>demos</code> directory
  displays the contents of the volumes mounted on the system (e.g., the root
  <code>/</code> on UNIX and the local drives on Windows) in a tablelist used
  as multi-column tree widget:</p>

  <blockquote>
    <img src="dirViewer.png" alt="Directory Viewer" width="675" height="456">
  </blockquote>

  <p>By double-clicking an item or invoking the single entry of a pop-up menu
  within the body of the tablelist, you can display the content of the folder
  corresponding to the selected item.&nbsp; To go one level up, click on the
  <b>Parent</b> button.</p>

  <p>There are a lot of similarities between this script and the one discussed
  in the <a href="#ex_browse">previous section</a>.&nbsp; In the following we
  will only present a few procedures that invoke tablelist commands not
  encountered in the examples above:</p>

  <blockquote>
    <pre>
package require Tk 8.3
package require tablelist 6.8

<span class="cmt">#
# Add some entries to the Tk option database
#</span>
set dir [file dirname [info script]]
source [file join $dir option.tcl]

<span class="cmt">#
# Create three images
#</span>
image create photo clsdFolderImg -file [file join $dir clsdFolder.gif]
image create photo openFolderImg -file [file join $dir openFolder.gif]
image create photo fileImg       -file [file join $dir file.gif]

<span class="cmt">#------------------------------------------------------------------------------
# displayContents
#
# Displays the content of the directory dir in a tablelist widget.
#------------------------------------------------------------------------------</span>
proc displayContents dir {
    <span class="cmt">#
    # Create a scrolled tablelist widget with 3 dynamic-
    # width columns and interactive sort capability
    #</span>
    set tf .tf
    frame $tf -class ScrollArea
    set tbl $tf.tbl
    set vsb $tf.vsb
    set hsb $tf.hsb
    tablelist::tablelist $tbl \
        -columns {0 "Name"          left
                  0 "Size"          right
                  0 "Date Modified" left} \
        -expandcommand expandCmd -collapsecommand collapseCmd \
        -xscrollcommand [list $hsb set] -yscrollcommand [list $vsb set] \
        -movablecolumns no -setgrid no -showseparators yes -height 20 -width 80
    if {[$tbl cget -selectborderwidth] == 0} {
        $tbl configure -spacing 1
    }
    $tbl columnconfigure 0 -formatcommand formatString -sortmode dictionary
    $tbl columnconfigure 1 -formatcommand formatSize -sortmode integer
    $tbl columnconfigure 2 -formatcommand formatString
    scrollbar $vsb -orient vertical   -command [list $tbl yview]
    scrollbar $hsb -orient horizontal -command [list $tbl xview]

    . . .

    <span class="cmt">#
    # Populate the tablelist with the content of the given directory
    #</span>
    $tbl sortbycolumn 0
    putContents $dir $tbl root
}
</pre>
  </blockquote>

  <p>The procedure <code>displayContents</code> creates the tablelist widget
  and the two scrollbars as children of a frame of class
  <code>ScrollArea</code>.&nbsp; For this class, the file
  <code>option.tcl</code>, <code>source</code>d into the main script, contains
  some look & feel related settings similar to the ones encountered in our
  <a href="#ex_config">first example</a>:</p>

  <blockquote>
    <pre>
option add *ScrollArea.borderWidth                      1
option add *ScrollArea.relief                           sunken
option add *ScrollArea.Tablelist.borderWidth            0
option add *ScrollArea.Tablelist.highlightThickness     0
</pre>
  </blockquote>

  <p>The procedure specifies a value not only for the <code><a href=
  "tablelistWidget.html#expandcommand">-expandcommand</a></code> option of the
  tablelist it creates, but also for its <code><a href=
  "tablelistWidget.html#collapsecommand">-collapsecommand</a></code>
  option.&nbsp; The latter will merely restore the image shown in the first
  column to the one displaying a closed folder (see below).</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# putContents
#
# Outputs the content of the directory dir into the tablelist widget tbl, as
# child items of the one identified by nodeIdx.
#------------------------------------------------------------------------------</span>
proc putContents {dir tbl nodeIdx} {
    . . .

    if {[string compare $nodeIdx "root"] == 0} {
        if {[string compare $dir ""] == 0} {
            if {[llength [file volumes]] == 1} {
                wm title . "Contents of the File System"
            } else {
                wm title . "Contents of the File Systems"
            }
        } else {
            wm title . "Contents of the Directory \"[file nativename $dir]\""
        }

        $tbl delete 0 end
        set row 0
    } else {
        set row [expr {$nodeIdx + 1}]
    }

    <span class="cmt">#
    # Build a list from the data of the subdirectories and
    # files of the directory dir.  Prepend a "D" or "F" to
    # each entry's name and modification date & time, for
    # sorting purposes (it will be removed by formatString).
    #</span>
    set itemList {}
    if {[string compare $dir ""] == 0} {
        foreach volume [file volumes] {
            lappend itemList [list D[file nativename $volume] -1 D $volume]
        }
    } else {
        foreach entry [glob -nocomplain -types {d f} -directory $dir *] {
            if {[catch {file mtime $entry} modTime] != 0} {
                continue
            }

            if {[file isdirectory $entry]} {
                lappend itemList [list D[file tail $entry] -1 \
                    D[clock format $modTime -format "%Y-%m-%d %H:%M"] $entry]
            } else {
                lappend itemList [list F[file tail $entry] [file size $entry] \
                    F[clock format $modTime -format "%Y-%m-%d %H:%M"] ""]
            }
        }
    }

    <span class="cmt">#
    # Sort the above list and insert it into the tablelist widget
    # tbl as list of children of the row identified by nodeIdx
    #</span>
    set itemList [$tbl applysorting $itemList]
    $tbl insertchildlist $nodeIdx end $itemList

    <span class="cmt">#
    # Insert an image into the first cell of each newly inserted row
    #</span>
    foreach item $itemList {
        set name [lindex $item end]
        if {[string compare $name ""] == 0} {                   ;<span class="cmt"># file</span>
            $tbl cellconfigure $row,0 -image fileImg
        } else {                                                ;<span class="cmt"># directory</span>
            $tbl cellconfigure $row,0 -image clsdFolderImg
            $tbl rowattrib $row pathName $name

            <span class="cmt">#
            # Mark the row as collapsed if the directory is non-empty
            #</span>
            if {[file readable $name] && [llength \
                [glob -nocomplain -types {d f} -directory $name *]] != 0} {
                $tbl collapse $row
            }
        }

        incr row
    }

    . . .
}
</pre>
  </blockquote>

  <p>The main difference between the procedure <code>putContents</code> above
  and the procedure <code><a href="#putChildren">demo::putChildren</a></code>
  described in the <a href="#ex_browse">previous section</a> is related to the
  way child items are inserted into the tablelist widget.&nbsp; Instead of
  inserting them individually with the aid of the <code><a href=
  "tablelistWidget.html#insertchildren">insertchild(ren)</a></code> tablelist
  subcommand, here we add the relevant data to a list of items and then invoke
  the much more performant <code><a href=
  "tablelistWidget.html#insertchildlist">insertchildlist</a></code>
  subcommand.&nbsp; Also, instead of first inserting the items and then sorting
  them via <code><a href=
  "tablelistWidget.html#refreshsorting">refreshsorting</a></code>, we first
  perform the necessary sortings on the above-mentioned list of items by
  invoking the <code><a href=
  "tablelistWidget.html#applysorting">applysorting</a></code> subcommand.&nbsp;
  Again, this is much faster than sorting the already inserted child items.</p>

  <p>This procedure also illustrates an effective technique based on the
  <code><a href=
  "tablelistWidget.html#col_formatcommand">-formatcommand</a></code> column
  configuration option:&nbsp; In the tablelist widget's internal list, the
  names and modification times of the directories and files are preceded by a
  <code>D</code> and <code>F</code>, respectively.&nbsp; This makes sure that
  the directories will sort before the files (when sorting in ascending
  order).&nbsp; When displaying the items, the Tablelist code will
  automatically invoke the <code>formatString</code> procedure, which removes
  the first character.&nbsp; Similarly, in the widget's internal list, the size
  of a directory is set to <code>-1</code>, which sorts before the sizes of the
  files.&nbsp; The <code>formatSize</code> procedure, invoked automatically
  when displaying the items, replaces this value with an empty string:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# formatString
#
# Returns the substring obtained from the specified value by removing its first
# character.
#------------------------------------------------------------------------------</span>
proc formatString val {
    return [string range $val 1 end]
}

<span class="cmt">#------------------------------------------------------------------------------
# formatSize
#
# Returns an empty string if the specified value is negative and the value
# itself in user-friendly format otherwise.
#------------------------------------------------------------------------------</span>
proc formatSize val {
    if {$val &lt; 0} {
        return ""
    } elseif {$val &lt; 1024} {
        return "$val bytes"
    } elseif {$val &lt; 1048576} {
        return [format "%.1f KB" [expr {$val / 1024.0}]]
    } elseif {$val &lt; 1073741824} {
        return [format "%.1f MB" [expr {$val / 1048576.0}]]
    } else {
        return [format "%.1f GB" [expr {$val / 1073741824.0}]]
    }
}
</pre>
  </blockquote>

  <p>Besides its common task of inserting the children of the row to be
  expanded, the <code>expandCmd</code> procedure shown below also changes the
  image contained in the first column to the one displaying an open
  folder.&nbsp; The <code>collapseCmd</code> procedure restores the image to
  the one displaying a closed folder:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# expandCmd
#
# Outputs the content of the directory whose leaf name is displayed in the
# first cell of the specified row of the tablelist widget tbl, as child items
# of the one identified by row, and updates the image displayed in that cell.
#------------------------------------------------------------------------------</span>
proc expandCmd {tbl row} {
    if {[$tbl childcount $row] == 0} {
        set dir [$tbl rowattrib $row pathName]
        putContents $dir $tbl $row
    }

    if {[$tbl childcount $row] != 0} {
        $tbl cellconfigure $row,0 -image openFolderImg
    }
}

<span class="cmt">#------------------------------------------------------------------------------
# collapseCmd
#
# Updates the image displayed in the first cell of the specified row of the
# tablelist widget tbl.
#------------------------------------------------------------------------------</span>
proc collapseCmd {tbl row} {
    $tbl cellconfigure $row,0 -image clsdFolderImg
}

. . .

displayContents ""
</pre>
  </blockquote>

  <p>The last line of the script invokes the procedure
  <code>displayContents</code> with an empty string as argument, i.e., displays
  the volumes mounted on the system.</p>

  <h3 id="ex_styles">Improving the Look & Feel of a tablelist Widget</h3>

  <p>The script <code>styles.tcl</code> in the <code>demos</code> directory
  demonstrates some ways of making tablelist widgets smarter and improving the
  readability of their items.&nbsp; It creates 8 tablelist widgets, shown in
  the following figure:</p>

  <blockquote>
    <img src="styles.png" alt="Styles" width="698" height="518">
  </blockquote>

  <p>Here is the relevant code segment:</p>

  <blockquote>
    <pre>
<span class="cmt">#
# Create, configure, and populate 8 tablelist widgets
#</span>
frame .f
for {set n 0} { $n &lt; 8} {incr n} {
    set tbl .f.tbl$n
    tablelist::tablelist $tbl \
        -columntitles {"Label 0" "Label 1" "Label 2" "Label 3"} \
        -background white -height 4 -width 40 -stretch all
    if {[$tbl cget -selectborderwidth] == 0} {
        $tbl configure -spacing 1
    }

    switch $n {
        1 {
            $tbl configure -showseparators yes
        }
        2 {
            $tbl configure -stripebackground #f0f0f0
        }
        3 {
            $tbl configure -stripebackground #f0f0f0 -showseparators yes
        }
        4 {
            $tbl columnconfigure 1 -background LightYellow
            $tbl columnconfigure 3 -background LightCyan
        }
        5 {
            $tbl configure -showseparators yes
            $tbl columnconfigure 1 -background LightYellow
            $tbl columnconfigure 3 -background LightCyan
        }
        6 {
            $tbl configure -stripebackground #f0f0f0
            $tbl columnconfigure 1 -background LightYellow \
                -stripebackground #f0f0d2
            $tbl columnconfigure 3 -background LightCyan \
                -stripebackground #d2f0f0
        }
        7 {
            $tbl configure -stripebackground #f0f0f0 -showseparators yes
            $tbl columnconfigure 1 -background LightYellow \
                -stripebackground #f0f0d2
            $tbl columnconfigure 3 -background LightCyan \
                -stripebackground #d2f0f0
        }
    }

    foreach row {0 1 2 3} {
        $tbl insert end \
             [list "Cell $row,0" "Cell $row,1" "Cell $row,2" "Cell $row,3"]
    }
}
</pre>
  </blockquote>

  <p>The only configuration option used here but not discussed in the first
  three examples (although already encountered in the <a href=
  "#ex_dirViewer">previous one</a>) is <code><a href=
  "tablelistWidget.html#showseparators">-showseparators</a></code>.&nbsp; The
  visual effect it produces looks nice both by itself and combined with
  horizontal or vertical stripes, created by using the <code><a href=
  "tablelistWidget.html#stripebackground">-stripebackground</a></code> option
  and the <code><a href=
  "tablelistWidget.html#columnconfigure">columnconfigure</a></code> subcommand,
  respectively.</p>

  <h3 id="ex_editing">Advanced Interactive tablelist Cell Editing</h3>

  <p>The scripts <code>tileWidgets.tcl</code>, <code>bwidget.tcl</code>,
  <code>iwidgets.tcl</code>, and <code>miscWidgets.tcl</code> in the
  <code>demos</code> directory create a tablelist widget displaying some
  parameters of 16 serial lines, and demonstrate how to use various widgets
  from the Tk core and from the packages tile, BWidget, Iwidgets, combobox (by
  Bryan Oakley), ctext, and Mentry (or Mentry_tile) for interactive cell
  editing.&nbsp; The following figure shows the tablelist widget, together with
  a BWidget ComboBox used to edit the content of one of its cells:</p>

  <blockquote>
    <img src="bwidget.png" alt="Serial Line Configuration" width="841" height=
    "409">
  </blockquote>

  <p>Here is the relevant code segment from the script <code>bwidget.tcl</code>
  (the scripts <code>tileWidgets.tcl</code>, <code>iwidgets.tcl</code>, and
  <code>miscWidgets.tcl</code> are similar).&nbsp; A few parts of the code are
  shown in <span class="red">red</span> color &ndash; we will return to this
  towards the end of the section.</p>

  <blockquote>
    <pre>
package require Tk 8.4                          ;<span class="cmt"># because of "-compound"</span>
package require tablelist 6.8
package require BWidget

wm title . "Serial Line Configuration"

<span class="cmt">#
# Add some entries to the Tk option database
#</span>
set dir [file dirname [info script]]
source [file join $dir option.tcl]
option add *Tablelist*Entry.background white

<span class="cmt">#
# Register some widgets from the BWidget package for interactive cell editing
#</span>
tablelist::addBWidgetEntry
tablelist::addBWidgetSpinBox
tablelist::addBWidgetComboBox

<span class="cmt">#
# Create the images "checkedImg" and "uncheckedImg", as well as 16 images of
# names like "img#FF0000", displaying colors identified by names like "red"
#</span>
source [file join $dir images.tcl]

<span class="cmt">#
# Create a tablelist widget with editable columns (except the first one)
#</span>
set tbl .tbl
tablelist::tablelist $tbl \
    -columns {0 "No."             right
              0 "Available"       center
              0 "Name"            left
              0 "Baud Rate"       right
              0 "Data Bits"       center
              0 "Parity"          left
              0 "Stop Bits"       center
              0 "Handshake"       left
              0 "Activation Date" center
              0 "Activation Time" center
              0 "Cable Color"     center} \
    -editstartcommand editStartCmd -editendcommand editEndCmd \
    -height 0 -width 0
if {[$tbl cget -selectborderwidth] == 0} {
    $tbl configure -spacing 1
}
$tbl columnconfigure 0 -sortmode integer
$tbl columnconfigure 1 <span class="red">-name available -editable yes -editwindow checkbutton</span> \
    -formatcommand emptyStr
$tbl columnconfigure 2 -name lineName  -editable yes -editwindow Entry \
    -sortmode dictionary
$tbl columnconfigure 3 -name baudRate  -editable yes -editwindow ComboBox \
    -sortmode integer
$tbl columnconfigure 4 -name dataBits  -editable yes -editwindow SpinBox
$tbl columnconfigure 5 -name parity    -editable yes -editwindow ComboBox
$tbl columnconfigure 6 -name stopBits  -editable yes -editwindow ComboBox
$tbl columnconfigure 7 -name handshake -editable yes -editwindow ComboBox
$tbl columnconfigure 8 -name actDate   -editable yes -editwindow Entry \
    -formatcommand formatDate -sortmode integer
$tbl columnconfigure 9 -name actTime   -editable yes -editwindow Entry \
    -formatcommand formatTime -sortmode integer
$tbl columnconfigure 10 -name color    -editable yes -editwindow menubutton \
    -formatcommand emptyStr

proc emptyStr   val { return "" }
proc formatDate val { return [clock format $val -format "%Y-%m-%d"] }
proc formatTime val { return [clock format $val -format "%H:%M:%S"] }

<span class="cmt">#
# Populate the tablelist widget; set the activation
# date & time to 10 minutes past the current clock value
#</span>
set clock [expr {[clock seconds] + 600}]
for {set i 0; set n 1} {$i &lt; 16} {set i $n; incr n} {
    $tbl insert end [list $n [expr {$i &lt; 8}] "Line $n" 9600 8 None 1 XON/XOFF \
        $clock $clock [lindex $colorNames $i]]

    <span class="red">set availImg [expr {($i &lt; 8) ? "checkedImg" : "uncheckedImg"}]
    $tbl cellconfigure end,available -image $availImg</span>
    $tbl cellconfigure end,color -image img[lindex $colorValues $i]
}

set btn [button .btn -text "Close" -command exit]

<span class="cmt">#
# Manage the widgets
#</span>
pack $btn -side bottom -pady 10
pack $tbl -side top -expand yes -fill both
</pre>
  </blockquote>

  <p>We invoke the <code><a href=
  "tablelistBWidget.html#Entry">tablelist::addBWidgetEntry</a></code>,
  <code><a href=
  "tablelistBWidget.html#SpinBox">tablelist::addBWidgetSpinBox</a></code>, and
  <code><a href=
  "tablelistBWidget.html#ComboBox">tablelist::addBWidgetComboBox</a></code>
  commands to register the Entry, SpinBox, and ComboBox widgets from the
  BWidget package for interactive cell editing.&nbsp; These commands return the
  values <code>"Entry"</code>, <code>"SpinBox"</code>, and
  <code>"ComboBox"</code>, respectively, which we then use in the
  <code><a href="tablelistWidget.html#col_editwindow">-editwindow</a></code>
  column configuration option to set the edit window for the columns no. 2,
  ..., 10.&nbsp; In columns no. 1 and 10 we use the Tk core checkbutton and
  menubutton widgets, which are automatically registered for interactive cell
  editing.</p>

  <p>Notice the use of the <code><a href=
  "tablelistWidget.html#col_name">-name</a></code> column configuration option,
  which allows us to access the columns by their names instead of by numerical
  column indices.&nbsp; This is important, because the file
  <code>option.tcl</code>, which is <code>source</code>d into the main script,
  contains the line</p>

  <blockquote>
    <pre>
option add *Tablelist.movableColumns    yes
</pre>
  </blockquote>

  <p>The <code>editStartCmd</code> and <code>editEndCmd</code> procedures shown
  below use the <code><a href=
  "tablelistWidget.html#columncget">columncget</a></code> subcommand to
  retrieve the name of the column from the numerical column index.</p>

  <p>By the way, two further option database settings contained in the file
  <code>option.tcl</code> are:</p>

  <blockquote>
    <pre>
option add *Tablelist.labelCommand      tablelist::sortByColumn
option add *Tablelist.labelCommand2     tablelist::addToSortColumns
</pre>
  </blockquote>

  <p>The <code><a href=
  "tablelistColSort.html#sortByColumn">tablelist::sortByColumn</a></code> and
  <code><a href=
  "tablelistColSort.html#addToSortColumns">tablelist::addToSortColumns</a></code>
  commands specified in these settings enable the user to sort the items by one
  or more columns, with the aid of the left mouse button and of the
  <code>Shift</code> key.</p>

  <p>The <code>editStartCmd</code> procedure, specified as the value of the
  <code><a href=
  "tablelistWidget.html#editstartcommand">-editstartcommand</a></code>
  configuration option, needs the path name of the edit window, in order to be
  able to configure the widget in various ways.&nbsp; This is a common
  situation, and Tablelist provides the <code><a href=
  "tablelistWidget.html#editwinpath">editwinpath</a></code> subcommand for this
  purpose:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# editStartCmd
#
# Applies some configuration options to the edit window; if the latter is a
# ComboBox, the procedure populates it.
#------------------------------------------------------------------------------</span>
proc editStartCmd {tbl row col text} {
    set w [$tbl editwinpath]

    switch [$tbl columncget $col -name] {
        lineName {
            <span class="cmt">#
            # Set an upper limit of 20 for the number of characters
            #</span>
            $w configure -invalidcommand bell -validate key \
                         -validatecommand {expr {[string length %P] &lt;= 20}}
        }

        baudRate {
            <span class="cmt">#
            # Populate the ComboBox and allow no more
            # than 6 digits in its Entry component
            #</span>
            $w configure -values {50 75 110 300 1200 2400 4800 9600 19200 38400
                                  57600 115200 230400 460800 921600}
            $w configure -invalidcommand bell -validate key -validatecommand \
                {expr {[string length %P] &lt;= 6 && [regexp {^[0-9]*$} %S]}}
        }

        dataBits {
            <span class="cmt">#
            # Configure the SpinBox
            #</span>
            $w configure -range {5 8 1} -editable no
        }

        parity {
            <span class="cmt">#
            # Populate the ComboBox and make it non-editable
            #</span>
            $w configure -values {None Even Odd Mark Space} -editable no
        }

        . . .

        color {
            <span class="cmt">#
            # Populate the menu and make sure the menubutton will display the
            # color name rather than $text, which is "", due to -formatcommand
            #</span>
            set menu [$w cget -menu]
            foreach name $::colorNames {
                $menu add radiobutton -compound left \
                    -image img$::colors($name) -label $name
            }
            $menu entryconfigure 8 -columnbreak 1
            return [$tbl cellcget $row,$col -text]
        }
    }

    return $text
}
</pre>
  </blockquote>

  <p>The <code>editEndCmd</code> procedure, specified as the value of the
  <code><a href=
  "tablelistWidget.html#editendcommand">-editendcommand</a></code>
  configuration option, is responsible for a final validation of the edit
  window's text.&nbsp; Another purpose of this command is to convert the text
  contained in the edit window to the cell's new <i>internal</i> content, which
  is necessary because the internal value of the activation date and time is a
  clock value in seconds:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# editEndCmd
#
# Performs a final validation of the text contained in the edit window and gets
# the cell's internal content.
#------------------------------------------------------------------------------</span>
proc editEndCmd {tbl row col text} {
    switch [$tbl columncget $col -name] {
        <span class="red">available {
            <span class="cmt">#
            # Update the image contained in the cell
            #</span>
            set img [expr {$text ? "checkedImg" : "uncheckedImg"}]
            $tbl cellconfigure $row,$col -image $img
        }</span>

        baudRate {
            <span class="cmt">#
            # Check whether the baud rate is an integer in the range 50..921600
            #</span>
            if {![regexp {^[0-9]+$} $text] || $text &lt; 50 || $text &gt; 921600} {
                bell
                tk_messageBox -title "Error" -icon error -message \
                    "The baud rate must be an integer in the range 50..921600"
                $tbl rejectinput
            }
        }

        actDate {
            <span class="cmt">#
            # Get the activation date in seconds from the last argument
            #</span>
            if {[catch {clock scan $text} actDate] != 0} {
                bell
                tk_messageBox -title "Error" -icon error -message "Invalid date"
                $tbl rejectinput
                return ""
            }

            <span class="cmt">#
            # Check whether the activation clock value is later than the
            # current one; if this is the case then make sure the cells
            # "actDate" and "actTime" will have the same internal value
            #</span>
            set actTime [$tbl cellcget $row,actTime -text]
            set actClock [clock scan [formatTime $actTime] -base $actDate]
            if {$actClock &lt;= [clock seconds]} {
                bell
                tk_messageBox -title "Error" -icon error -message \
                    "The activation date & time must be in the future"
                $tbl rejectinput
            } else {
                $tbl cellconfigure $row,actTime -text $actClock
                return $actClock
            }
        }

        . . .

        color {
            <span class="cmt">#
            # Update the image contained in the cell
            #</span>
            $tbl cellconfigure $row,$col -image img$::colors($text)
        }
    }

    return $text
}
</pre>
  </blockquote>

  <p>Instead of making the <code>"Available"</code> column editable via a
  <i>temporary</i> checkbutton and displaying the images
  <code>"checkedImg"</code> and <code>"uncheckedImg"</code> in its cells, we
  can use the <code><a href=
  "tablelistWidget.html#embedcheckbuttons">embedcheckbuttons</a></code>
  subcommand to populate the column with <i>persistently</i> embedded
  checkbuttons.&nbsp; The necessary changes are as follows:</p>

  <ul>
    <li class="tm">Remove those parts of the code above that are shown in
    <span class="red">red</span> color.</li>

    <li class="tm">
      Invoke

      <blockquote>
        <pre>
$tbl embedcheckbuttons 1
</pre>
      </blockquote>

      after populating the tablelist widget.
    </li>
  </ul>

  <p>As mentioned above, the scripts <code>tileWidgets.tcl</code>,
  <code>iwidgets.tcl</code>, and <code>miscWidgets.tcl</code> are similar to
  <code>bwidget.tcl</code>.&nbsp; The first one makes use of the tile entry,
  spinbox, combobox, checkbutton, and menubutton widgets.&nbsp; The second one
  uses (besides the Tk core checkbutton and menubutton) the entryfield,
  spinint, combobox, dateentry, and timeentry widgets from the Iwidgets package
  and the validation facilities specific to that library.&nbsp; The third
  script makes use of the entry, spinbox, checkbutton, and menubutton widgets
  from the Tk core, Bryan Oakley's combobox, and of the mentry widgets of type
  <code>"Date"</code> and <code>"Time"</code>, and it performs the entry
  validation with the aid of the Wcb package (which is required anyway for the
  Mentry library).</p>

  <h3 id="ex_windows">A tablelist Widget Containing Embedded Windows</h3>

  <p>The script <code>embeddedWindows.tcl</code> in the <code>demos</code>
  directory creates a tablelist widget whose items correspond to the Tk library
  scripts.&nbsp; The size of each file (in bytes) is not only displayed as a
  number, but is also illustrated with the aid of a frame with red background,
  created as a child of an embedded frame with ivory background.&nbsp; The
  files can be viewed by clicking on the corresponding embedded button
  widgets.</p>

  <p>The following screenshot shows the tablelist widget with the mouse cursor
  over the first header label, causing this label to appear in
  <code>active</code> state:</p>

  <blockquote>
    <img src="embeddedWindows.png" alt="Embedded Windows" width="432" height=
    "310">
  </blockquote>

  <p>First, we create and populate the tablelist widget:</p>

  <blockquote>
    <pre>
package require tablelist 6.8

wm title . "Tk Library Scripts"

<span class="cmt">#
# Add some entries to the Tk option database
#</span>
set dir [file dirname [info script]]
source [file join $dir option.tcl]

<span class="cmt">#
# Create the font TkFixedFont if not yet present
#</span>
catch {font create TkFixedFont -family Courier -size -12}

<span class="cmt">#
# Create an image to be displayed in buttons embedded in a tablelist widget
#</span>
image create photo openImg -file [file join $dir open.gif]

<span class="cmt">#
# Create a vertically scrolled tablelist widget with 5
# dynamic-width columns and interactive sort capability
#</span>
set tf .tf
frame $tf -class ScrollArea
set tbl $tf.tbl
set vsb $tf.vsb
tablelist::tablelist $tbl \
    -columns {0 "File Name" left
              0 "Bar Chart" center
              0 "File Size" right
              0 "View"      center
              0 "Seen"      center} \
    -setgrid no -yscrollcommand [list $vsb set] -width 0
if {[$tbl cget -selectborderwidth] == 0} {
    $tbl configure -spacing 1
}
$tbl columnconfigure 0 -name fileName
$tbl columnconfigure 1 -formatcommand emptyStr -sortmode integer
$tbl columnconfigure 2 -name fileSize -sortmode integer
$tbl columnconfigure 4 -name seen
scrollbar $vsb -orient vertical -command [list $tbl yview]

proc emptyStr val { return "" }

<span class="cmt">#
# Create a bold font
#</span>
set tblFont [$tbl cget -font]
set size [font actual $tblFont -size]
if {$size == 0} {                                       ;<span class="cmt"># e.g., on Ubuntu</span>
    set size -12
}
eval font create BoldFont [font actual $tblFont] -size $size -weight bold

<span class="cmt">#
# Populate the tablelist widget
#</span>
cd $tk_library
set totalSize 0
set maxSize 0
foreach fileName [lsort [glob *.tcl]] {
    set fileSize [file size $fileName]
    $tbl insert end [list $fileName $fileSize $fileSize "" no]

    incr totalSize $fileSize
    if {$fileSize &gt; $maxSize} {
        set maxSize $fileSize
    }
}
if {$tk_version &gt;= 8.5} {
    $tbl header insert 0 [list "[$tbl size] *.tcl files" "" $totalSize "" ""]
    $tbl header rowconfigure 0 -foreground blue
}
</pre>
  </blockquote>

  <p>We insert the size of each file not only into the column with the
  title&nbsp; <code>"File Size"</code>,&nbsp; but also into the column&nbsp;
  <code>"Bar Chart"</code>.&nbsp; Since we configured this column with&nbsp;
  <code>-formatcommand emptyStr</code>,&nbsp; the text will remain hidden in
  it.&nbsp; It will, however, be needed when sorting the items by that
  column.</p>

  <p>After populating the tablelist's body, we create a header item displaying
  the total number and size of the library files, by invoking the&nbsp;
  <code><a href="tablelistWidget.html#hdr_insert">header
  insert</a></code>&nbsp; subcommand, and change its foreground color with the
  aid of the&nbsp; <code><a href="tablelistWidget.html#hdr_rowconfigure">header
  rowconfigure</a></code>&nbsp; subcommand.</p>

  <p>To be able to create the embedded windows, we have first to implement the
  creation scripts for them, as specified in the description of the
  <code><a href="tablelistWidget.html#cell_window">-window</a></code> cell
  configuration option.&nbsp; Here is the script that creates a frame to be
  embedded into the column displaying the bar chart:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# createFrame
#
# Creates a frame widget w to be embedded into the specified cell of the
# tablelist widget tbl, as well as a child frame representing the size of the
# file whose name is diplayed in the first column of the cell's row.
#------------------------------------------------------------------------------</span>
proc createFrame {tbl row col w} {
    <span class="cmt">#
    # Create the frame and replace the binding tag "Frame"
    # with "TablelistBody" in the list of its binding tags
    #</span>
    frame $w -width 102 -height 14 -background ivory -borderwidth 1 \
             -relief solid
    bindtags $w [lreplace [bindtags $w] 1 1 TablelistBody]

    <span class="cmt">#
    # Create the child frame and replace the binding tag "Frame"
    # with "TablelistBody" in the list of its binding tags
    #</span>
    frame $w.f -height 12 -background red -borderwidth 1 -relief raised
    bindtags $w.f [lreplace [bindtags $w] 1 1 TablelistBody]

    <span class="cmt">#
    # Manage the child frame
    #</span>
    set fileSize [$tbl cellcget $row,fileSize -text]
    place $w.f -relwidth [expr {double($fileSize) / $::maxSize}]
}
</pre>
  </blockquote>

  <p>Since the frame will be embedded into the tablelist's body, we want to
  have the same handling of the mouse events in the frame and in its child
  frame as in the rest of the tablelist's body.&nbsp; To this end we replace
  the binding tag <code>Frame</code> (which has no own bindings anyway) with
  <code><a href="tablelistWidget.html#body_bindings">TablelistBody</a></code>,
  thus making sure that the default binding scripts associated with that tag
  will be valid for the parent frame and its child, too.</p>

  <p>We <code>place</code> the red child frame within its parent using the
  <code>-relwidth</code> option, to make sure that its width will remain
  proportional to the size of the corresponding file when resizing the parent
  frame (which will happen when resizing its column, as seen below).</p>

  <p>The creation script for the buttons used for viewing the Tk library files
  is quite simple:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# createButton
#
# Creates a button widget w to be embedded into the specified cell of the
# tablelist widget tbl.
#------------------------------------------------------------------------------</span>
proc createButton {tbl row col w} {
    set key [$tbl getkeys $row]
    button $w -image openImg -highlightthickness 0 -takefocus 0 \
              -command [list viewFile $tbl $key]
}

<span class="cmt">#------------------------------------------------------------------------------
# viewFile
#
# Displays the content of the file whose name is contained in the row with the
# given key of the tablelist widget tbl.
#------------------------------------------------------------------------------</span>
proc viewFile {tbl key} {
    set top .top$key
    if {[winfo exists $top]} {
        raise $top
        focus $top
        return ""
    }

    toplevel $top
    set fileName [$tbl cellcget k$key,fileName -text]
    wm title $top "File \"$fileName\""

    <span class="cmt">#
    # Create a vertically scrolled text widget as a grandchild of the toplevel
    #</span>
    set tf $top.tf
    frame $tf -class ScrollArea
    set txt $tf.txt
    set vsb $tf.vsb
    text $txt -background white -font TkFixedFont -setgrid yes \
              -yscrollcommand [list $vsb set]
    catch {$txt configure -tabstyle wordprocessor}      ;<span class="cmt"># for Tk 8.5 and above</span>
    scrollbar $vsb -orient vertical -command [list $txt yview]

    <span class="cmt">#
    # Insert the file's content into the text widget
    #</span>
    set chan [open $fileName]
    $txt insert end [read -nonewline $chan]
    close $chan

    . . .

    <span class="cmt">#
    # Mark the file as seen
    #</span>
    $tbl rowconfigure k$key -font BoldFont
    $tbl cellconfigure k$key,seen -text yes
}
</pre>
  </blockquote>

  <p>Each file will be displayed in a text widget contained in a toplevel whose
  name is <code>.top$key</code>, where <code>$key</code> is obtained with the
  aid of the <code><a href="tablelistWidget.html#getkeys">getkeys</a></code>
  subcommand.&nbsp; By using the key instead of the row number, we will have a
  unique name for the toplevel, even if the order of the items changes due to
  interactive sorting by a column.&nbsp; (Remember that the embedded windows
  will be destroyed and automatically recreated when sorting the items or
  moving the columns.)</p>

  <p>Having implemented the creation scripts for the frames and buttons, we can
  now use the <code><a href=
  "tablelistWidget.html#cellconfigure">cellconfigure</a></code> subcommand to
  effectively create these widgets as embedded windows.&nbsp; Notice the
  <code><a href=
  "tablelistWidget.html#cell_stretchwindow">-stretchwindow</a></code> option
  used for the embedded frames, to make sure that their width will be adapted
  to that of the containing column when the latter is being resized
  interactively.</p>

  <blockquote>
    <pre>
<span class="cmt">#
# Create embedded windows in the columns no. 1 and 3
#</span>
set rowCount [$tbl size]
for {set row 0} {$row &lt; $rowCount} {incr row} {
    $tbl cellconfigure $row,1 -window createFrame -stretchwindow yes
    $tbl cellconfigure $row,3 -window createButton
}
</pre>
  </blockquote>

  <h3 id="ex_tile">Tile-Based Demo Scripts</h3>

  <p>The Tablelist distribution contains also tile-based counterparts of the
  demo scripts discussed above.&nbsp; As described in the <a href=
  "#ov_tile">More on Tablelist_tile</a> section of this tutorial, it is quite
  easy to port an application using the Tablelist package to one based on
  Tablelist_tile.&nbsp; For example, let's see how to transform the demo script
  <code><a href="#ex_editing">bwidget.tcl</a></code> into a tile-based one,
  called <code>bwidget_tile.tcl</code>.&nbsp; The changes are shown below in
  <span class="red">red</span> color:</p>

  <p>First, we replace the starting lines</p>

  <blockquote>
    <pre>
package require Tk 8.3                          ;<span class="cmt"># because of entry validation</span>
package require tablelist 6.8
</pre>
  </blockquote>

  <p>with</p>

  <blockquote>
    <pre>
package require tablelist<span class="red">_tile</span> 6.8
</pre>
  </blockquote>

  <p>and the command</p>

  <blockquote>
    <pre>
source [file join $dir option.tcl]
</pre>
  </blockquote>

  <p>with</p>

  <blockquote>
    <pre>
source [file join $dir option<span class="red">_tile</span>.tcl]
</pre>
  </blockquote>

  <p>To ensure that the overall appearance of the GUI will conform to the
  currently used theme, we create a theme-specific container for our
  widgets:</p>

  <blockquote>
    <pre>
<span class="red">#
# Improve the window's appearance by using a tile
# frame as a container for the other widgets
#
set f [ttk::frame .f]</span>
</pre>
  </blockquote>

  <p>This implies that we have to replace the statement</p>

  <blockquote>
    <pre>
set tbl .tbl
</pre>
  </blockquote>

  <p>defining the path name of our tablelist widget with</p>

  <blockquote>
    <pre>
set tbl <span class="red">$f</span>.tbl
</pre>
  </blockquote>

  <p>Similarly, instead of a Tk button created by the command</p>

  <blockquote>
    <pre>
set btn [button .btn -text "Close" -command exit]
</pre>
  </blockquote>

  <p>we use a tile button that is a child of the above tile frame:</p>

  <blockquote>
    <pre>
set btn [<span class="red">ttk::</span>button <span class="red">$f</span>.btn -text "Close" -command exit]
</pre>
  </blockquote>

  <p>We manage this frame in the usual manner:</p>

  <blockquote>
    <pre>
<span class="red">pack $f -expand yes -fill both</span>
</pre>
  </blockquote>

  <p>The script <code>option_tile.tcl</code> is nearly identical to
  <code>option.tcl</code>.&nbsp; Its tile-specific part uses the values written
  by the command <code><a href=
  "tablelistThemes.html#setThemeDefaults">tablelist::setThemeDefaults</a></code>
  into the array <code>tablelist::themeDefaults</code>, to make sure that the
  selection will have the same theme-specific look in all the widgets created
  by the application:</p>

  <blockquote>
    <pre>
<span class="red">tablelist::setThemeDefaults
if {[tablelist::getCurrentTheme] eq "aqua"} {
    option add *Listbox.selectBackground \
               $tablelist::themeDefaults(-selectbackground)
    option add *Listbox.selectForeground \
               $tablelist::themeDefaults(-selectforeground)
} else {
    option add *selectBackground  $tablelist::themeDefaults(-selectbackground)
    option add *selectForeground  $tablelist::themeDefaults(-selectforeground)
}
option add *selectBorderWidth     $tablelist::themeDefaults(-selectborderwidth)</span>
</pre>
  </blockquote>

  <p>The demo script <code>tileWidgets.tcl</code> uses not only the
  Tablelist_tile package for creating a tablelist widget with a modern
  theme-specific look & feel, but also the tile entry, spinbox, combobox,
  checkbutton, and menubutoon widgets for interactive cell editing.&nbsp; The
  resulting window has a nice theme-specific appearance:</p>

  <blockquote>
    <img src="tileWidgets.png" alt="Serial Line Configuration" width="839"
    height="404">
  </blockquote>

  <p>The tile-based version of the demo script <code><a href=
  "#ex_windows">embeddedWindows.tcl</a></code> contains a bit more changes, but
  most of them are not Tablelist-specific.&nbsp; Please take a look at the file
  <code>embeddedWindows_tile.tcl</code> in the <code>demos</code> directory for
  the details.&nbsp; Here is a screenshot of the resulting window:</p>

  <blockquote>
    <img src="embeddedWindows_tile.png" alt="Embedded Windows" width="432"
    height="316">
  </blockquote>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>
</body>
</html>