File: tablelist.html

package info (click to toggle)
tklib 0.7%2B20210111-1
links: PTS, VCS
area: main
in suites: bullseye
size: 17,676 kB
sloc: tcl: 82,240; sh: 5,801; ansic: 792; pascal: 359; makefile: 70; sed: 53; exp: 21
file content (3014 lines) | stat: -rw-r--r-- 124,918 bytes
<!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.11</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_scaling">More on
    <code>tablelist::scalingpct</code></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 Scalable Widget Browsers Based on a
    tablelist</a></li>

    <li><a href="#ex_dirViewer">A Scalable 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 Scalable Interactive tablelist Cell
    Editing</a></li>

    <li><a href="#ex_windows">A tablelist Widget Containing Scalable 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.11.tar.gz</code> for UNIX and
  <code>tablelist6_11.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.11.tar.gz</code>:</p>

  <blockquote>
    <pre>
gunzip -c tablelist6.11.tar.gz | tar -xf -
</pre>
  </blockquote>

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

  <blockquote>
    <pre>
tar -zxf tablelist6.11.tar.gz
</pre>
  </blockquote>

  <p>Both commands will create a directory named <code>tablelist6.11</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_11.zip</code> into the directory
  <code>tablelist6.11</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.11, then it is highly
  recommended to specify the version number <code>6.11</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.11</code>,&nbsp; and their
  tile-based counterparts invoke the command&nbsp; <code>package require
  tablelist_tile 6.11</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 read-only variable <code>tablelist::scalingpct</code> is set at
    application start time to the scaling percentage corresponding to the
    display's DPI scaling level.&nbsp; Tablelist adapts, among others, the
    default sort arrow style on X11 and Windows Vista, 7, 8, and 10, as well as
    the sizes of the tree styles <code>vistaAero</code>,
    <code>vistaClassic</code>, <code>win7Aero</code>, <code>win7Classic</code>,
    and <code>win10</code> to the value of this variable.&nbsp; The currently
    supported values are <code>100</code>, <code>125</code>, <code>150</code>,
    <code>175</code>, and <code>200</code>.&nbsp; You can use this variable,
    e.g., if you want to create images of different sizes, depending on the DPI
    scaling level.&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_scaling">More on <code>tablelist::scalingpct</code></h3>

  <p>The way Tablelist initializes the variable
  <code>tablelist::scalingpct</code> depends on the windowing system:</p>

  <p><i>On Windows and Mac OS X Aqua</i> the scaling percentage is computed
  from&nbsp; <code>[tk scaling]</code>.&nbsp; Note that on Mac OS X the result
  is always <code>100</code>, regardless of the display's scaling level.&nbsp;
  On this system the desktop engine automatically scales everything as
  needed.</p>

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

  <ul>
    <li class="tm">On <i>Xfce and MATE</i> the display scaling mode can be
    either unscaled (1x, normal) or scaled (2x, HiDPI), and the variable
    <code>tablelist::scalingpct</code> will be set accordingly to
    <code>100</code> or <code>200</code>.</li>

    <li class="tm">In case of <i>GNOME on Xorg, Budgie, and Cinnamon versions
    earlier than 4.6</i>, the display scaling can be either 100 % or 200 %, and
    Tablelist sets the variable <code>tablelist::scalingpct</code> accordingly
    to <code>100</code> or <code>200</code>.&nbsp; In newer GNOME and Budgie
    versions on Ubuntu one can enable the
    <code>x11-randr-fractional-scaling</code> as experimental feature, which
    adds 125 %, 150 %, and 175 % to the list of supported scaling
    percentages.&nbsp; Note that, due to the way this fractional scaling is
    implemented, if the display scaling was set to one of these intermediate
    levels, the value of <code>tablelist::scalingpct</code> will be
    <code>200</code>.&nbsp; The same is valid for the fractional scaling
    support on Cinnamon, introduced in version 4.6.</li>

    <li class="tm"><i>GNOME on Wayland</i> traditionally supports the display
    scaling values 100 % and 200 %, and the variable
    <code>tablelist::scalingpct</code> will be set accordingly to
    <code>100</code> or <code>200</code>.&nbsp; In newer GNOME versions one can
    enable the experimental feature <code>scale-monitor-framebuffer</code>,
    which adds 125 %, 150 %, and 175 % to the list of supported scaling
    percentages.&nbsp; With this feature enabled, the value of
    <code>tablelist::scalingpct</code> will be <code>100</code> for all scaling
    levels 100 %, 125 %, ..., 200 %.&nbsp; This is due to the fact that in this
    case, instead of window contents, monitor framebuffers will be scaled in a
    logical pixel coordinate space.</li>

    <li class="tm"><i>KDE Plasma on Xorg</i> provides fractional scaling
    support.&nbsp; On this desktop, Tablelist will set the variable
    <code>tablelist::scalingpct</code> to <code>100</code>, <code>125</code>,
    <code>150</code>, <code>175</code>, or <code>200</code>, depending on the
    display's scaling level.</li>

    <li class="tm"><i>KDE Plasma on Wayland</i> supports fractional scaling,
    too.&nbsp; In this case, the value of the variable
    <code>tablelist::scalingpct</code> will always be <code>100</code>,
    regardless of the display's scaling level.</li>
  </ul>

  <p>After getting the scaling percentage on X11, Tablelist sets the scaling
  factor to be used by Tk to convert between physical units and pixels, by
  passing the scaling factor corresponding to the scaling percentage to
  the&nbsp; <code>tk scaling</code>&nbsp; command.</p>

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

  <p>Independently of the windowing system, the code responsible for the
  initialization of the variable <code>tablelist::scalingpct</code> also
  scales:</p>

  <ul>
    <li>the default width of the Tk core scrollbars on X11;</li>

    <li>for the built-in themes <code>alt</code>, <code>clam</code>,
    <code>classic</code>, and <code>default</code>, the default width of the
    ttk::scrollbar widget, as well as the arrows of the ttk::combobox and
    ttk::spinbox widgets;</li>

    <li>for the <code>alt</code> and <code>clam</code> themes, the arrow of
    the ttk::menubutton widget;</li>

    <li>for the <code>clam</code>, <code>classic</code>, and
    <code>default</code> themes, the indicators of the ttk::checkbutton and
    ttk::radiobutton widgets.</li>
  </ul>

  <p>In addition, the above-mentioned variable initialization code makes sure
  that in the <code>vista</code> and <code>xpnative</code> themes the
  indicators of the ttk::checkbutton and ttk::radiobutton widgets will appear
  properly scaled, regardless of the Tk release being used.&nbsp; (A
  long-standing bug in the implementation of these widgets was fixed in May
  2020, but Tablelist provides a workaround for the Tk versions that are still
  affected by this bug.)</p>

  <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, if the package Tablelist_tile cannot get the
  current theme with the aid of&nbsp; <code>ttk::style theme use</code>&nbsp;
  then it 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>
  command.&nbsp; From this it follows that <b>if the tile version being used
  doesn't support the&nbsp; <code>ttk::style theme use</code>&nbsp; command
  without an argument then 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 library procedure
  <code>ttk::setTheme</code> or <code>tile::setTheme</code>, depending on the
  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.11
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="400">
  </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.11

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 9}

        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 7p
    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
  "Refresh" 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 Scalable 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="607" height="297">
  </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="615" height="297">
  </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 "Parent" 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.11

namespace eval demo {
    variable dir [file dirname [info script]]

    <span class="cmt">#
    # Create two images corresponding to the display's DPI scaling level
    #</span>
    set pct $::tablelist::scalingpct
    variable compImg [image create bitmap -file [file join $dir comp$pct.xbm] \
                      -background yellow -foreground gray50]
    variable leafImg [image create bitmap -file [file join $dir leaf$pct.xbm] \
                      -background coral -foreground gray50]
}

source [file join $demo::dir config.tcl]
</pre>
  </blockquote>

  <p>The two images representing a "compound" widget (with children) and a
  "leaf" widget (without children), respectively, are created from files whose
  names contain the display's DPI scaling level, given by the public variable
  <code>tablelist::scalingpct</code>.&nbsp; The X bitmap files
  <code>comp100.xbm</code> and <code>leaf100.xbm</code> contain images of size
  16 x 13, the files <code>*125.xbm</code> contain images of size 20 x 16, the
  files <code>*150.xbm</code> contain images of size 24 x 19, and so on.</p>

  <blockquote>
    <pre>
<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">#
    # On X11 configure the tablelist according
    # to the display's DPI scaling level
    #</span>
    variable winSys                                     ;<span class="cmt"># see config.tcl</span>
    if {[string compare $winSys "x11"] == 0} {
        $tbl configure -treestyle bicolor$::tablelist::scalingpct
    }

    <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>In a scaling-aware application the value of the <code><a href=
  "tablelistWidget.html#treestyle">-treestyle</a></code> tablelist option
  should reflect the display's DPI scaling level.&nbsp; On Windows Vista, 7, 8,
  and 10 the default value of this option already fulfills this requirement,
  and on Mac OS X Aqua the desktop engine automatically scales everything as
  needed.&nbsp; On X11 we set the <code>-treestyle</code> option to one of
  <code>bicolor100</code>, ..., <code>bicolor200</code>, depending on the value
  of the public variable <code>::tablelist::scalingpct</code>.</p>

  <p>After configuring the <code>-treestyle</code> option on X11, 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
  "Refresh" 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 Scalable 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="454">
  </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
  "Parent" 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.11

<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 corresponding to the display's DPI scaling level
#</span>
set pct $tablelist::scalingpct
image create photo clsdFolderImg -file [file join $dir clsdFolder$pct.gif]
image create photo openFolderImg -file [file join $dir openFolder$pct.gif]
image create photo fileImg       -file [file join $dir       file$pct.gif]
</pre>
  </blockquote>

  <p>The three images representing a closed folder, an open folder, and a file,
  respectively, are created from files whose names contain the display's DPI
  scaling level, given by the public variable
  <code>tablelist::scalingpct</code>.&nbsp; The files
  <code>clsdFolder100.gif</code>, <code>openFolder100.gif</code>, and
  <code>file100.gif</code> contain images of size 16 x 16, the files
  <code>*125.gif</code> contain images of size 20 x 20, the files
  <code>*150.gif</code> contain images of size 24 x 24, and so on.</p>

  <blockquote>
    <pre>
<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">#
    # On X11 configure the tablelist according
    # to the display's DPI scaling level
    #</span>
    global winSys                                       ;<span class="cmt"># see option.tcl</span>
    if {[string compare $winSys "x11"] == 0} {
        $tbl configure -treestyle bicolor$tablelist::scalingpct
    }

    . . .

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

  <p>In a scaling-aware application the value of the <code><a href=
  "tablelistWidget.html#treestyle">-treestyle</a></code> tablelist option
  should reflect the display's DPI scaling level.&nbsp; On Windows Vista, 7, 8,
  and 10 the default value of this option already fulfills this requirement,
  and on Mac OS X Aqua the desktop engine automatically scales everything as
  needed.&nbsp; On X11 we set the <code>-treestyle</code> option to one of
  <code>bicolor100</code>, ..., <code>bicolor200</code>, depending on the value
  of the public variable <code>tablelist::scalingpct</code>.</p>

  <p>Let's see how the script populates the tablelist with the content of the
  given directory:</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="695" height="512">
  </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 Scalable 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=
    "407">
  </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.11
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">#
# 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">#
# Register some widgets from the BWidget package for interactive cell editing
#</span>
tablelist::addBWidgetEntry
tablelist::addBWidgetSpinBox
tablelist::addBWidgetComboBox

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

. . .
</pre>
  </blockquote>

  <p>The sizes of the images created in the file <code>images.tcl</code>, which
  is <code>source</code>d into the main script, depend on the display's scaling
  level, given by the public variable <code>tablelist::scalingpct</code>.&nbsp;
  For example:</p>

  <blockquote>
    <pre>
set pct $tablelist::scalingpct
image create photo checkedImg   -file [file join $dir checked$pct.gif]
image create photo uncheckedImg -file [file join $dir unchecked$pct.gif]
</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 Scalable 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="426" height=
    "308">
  </blockquote>

  <p>First, we create and populate the tablelist widget:</p>

  <blockquote>
    <pre>
package require tablelist 6.11

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 9}

<span class="cmt">#
# Create an image corresponding to the display's DPI scaling
# level, to be displayed in buttons embedded in a tablelist widget
#</span>
image create photo openImg -file [file join $dir openAction$pct.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 9
}
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>The image representing an "open" action is created from a file whose name
  contains the display's DPI scaling level, given by the public variable
  <code>tablelist::scalingpct</code>.</p>

  <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>
    set height [expr {[font metrics $::tblFont -linespace] * 4 / 5}]
    frame $w -width 72p -height $height -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 -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 -relheight 1.0 -relwidth [expr {double($fileSize) / $::maxSize}]
}
</pre>
  </blockquote>

  <p>Notice that we specify the values of the <code>-width</code> and
  <code>-height</code> options for the frame in a scaling-aware manner.</p>

  <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>-relheight</code> and <code>-relwidth</code> options, to make sure that
  it will vertically fill the area inside its parent's border and 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]
    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.11
</pre>
  </blockquote>

  <p>with</p>

  <blockquote>
    <pre>
package require tablelist<span class="red">_tile</span> 6.11
</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 on
  <code>x11</code> the selection will have the same theme-specific look in all
  the widgets created by the application:</p>

  <blockquote>
    <pre>
tablelist::setThemeDefaults
if {[tk windowingsystem] eq "x11"} {
    option add *Font              TkDefaultFont
    option add *selectBackground  $tablelist::themeDefaults(-selectbackground)
    option add *selectForeground  $tablelist::themeDefaults(-selectforeground)
}
option add *selectBorderWidth     $tablelist::themeDefaults(-selectborderwidth)
</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="402">
  </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="426"
    height="314">
  </blockquote>

  <p>Finally, notice that the following tile-based demo-scripts provide
  <i>full</i> support for the Dark Mode appearance on Mac OS 10.14 (Mojave) and
  later with Tk 8.6.10 or above, as well as for the <code>awdark</code>,
  <code>awlight</code>, and the five other themes provided by the
  multi-platform package <a href=
  "https://sourceforge.net/projects/tcl-awthemes/">awthemes</a> 9.4 or later by
  Brad Lanam: <code>browse_tile.tcl</code>, <code>browseTree_tile.tcl</code>,
  <code>config_tile.tcl</code>, <code>dirViewer_tile.tcl</code>,
  <code>embeddedWindows_tile.tcl</code>, and
  <code>tileWidgets.tcl</code>.&nbsp; While the Aqua Dark Mode support has been
  present in Tk since its version 8.6.10, for an optimal user experience on the
  Mac it is recommended to run these scripts with Tk 8.6.11 or later, due to a
  few appearance-related improvements made in Tk 8.6.11.</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>