Tk Library Source Code: Check-in [deffd2c563]

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview

Comment:	* doc/*.html: Updated to reflect the changes; improved and extended the description of the "-height" option in the reference manual; added references to the new Scrollutil package and an example showing how the scrollutil::scrollarea widget can be used to make the creation of a scrolled tablelist quite simple.
Downloads:	Tarball \| ZIP archive \| SQL archive
Timelines:	family \| ancestors \| descendants \| both \| trunk
Files:	files \| file ages \| folders
SHA3-256:	deffd2c56399fff24d7fd3ab683b337b3e15d378230c197bd0801e739c381929
User & Date:	csaba 2019-07-06 17:47:30

Context

2019-07-06
17:50		* doc/adwaita.png: Updated screenshots. * doc/arrowStyles_vista.png: check-in: 4713178d5f user: csaba tags: trunk
17:47		* doc/*.html: Updated to reflect the changes; improved and extended the description of the "-height" option in the reference manual; added references to the new Scrollutil package and an example showing how the scrollutil::scrollarea widget can be used to make the creation of a scrolled tablelist quite simple. check-in: deffd2c563 user: csaba tags: trunk
17:46		* scripts/tclIndex: Newly generated. check-in: ed5bcd155e user: csaba tags: trunk

Changes

Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to modules/tablelist/doc/index.html.

<html>
<head>
  <title>The Multi-Column Listbox and Tree Widget Package Tablelist 6.5</title>

  <meta name="Author" content="Csaba Nemethi">
  <meta name="Keywords" content=
  "tablelist, multi-column, listbox, tree, widget, tile">
</head>

<body bgcolor="#FFFFFF">
  <div align="center">
    <h1>The Multi-Column Listbox and Tree Widget Package Tablelist 6.5</h1>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>

<html>
<head>
  <title>The Multi-Column Listbox and Tree Widget Package Tablelist 6.6</title>

  <meta name="Author" content="Csaba Nemethi">
  <meta name="Keywords" content=
  "tablelist, multi-column, listbox, tree, widget, tile">
</head>

<body bgcolor="#FFFFFF">
  <div align="center">
    <h1>The Multi-Column Listbox and Tree Widget Package Tablelist 6.6</h1>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>

Changes to modules/tablelist/doc/tablelist.html.

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

<body bgcolor="#FFFFFF">
  <div align="center">
    <h1>Tablelist Programmer's Guide</h1>

    <h2>For Tablelist Version 6.5</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>
................................................................................
    Configuration Options</a></li>

    <li><a href="#ex_browse">Two Widget Browsers Based on a tablelist</a></li>

    <li><a href="#ex_dirViewer">A Directory Viewer Based on a
    tablelist</a></li>

    <li><a href="#ex_styles">Improving the Look &amp; Feel of a tablelist
    Widget</a></li>

    <li><a href="#ex_editing">Advanced Interactive tablelist Cell
    Editing</a></li>

    <li><a href="#ex_windows">A tablelist Widget Containing Embedded
    Windows</a></li>
................................................................................
  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 &amp; 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>
................................................................................
      <a href="http://www.nemethi.de">http://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.5.tar.gz</code> for UNIX and
  <code>tablelist6_5.zip</code> for Windows.&nbsp; These files contain the same
  information, except for the additional carriage return character preceding
  the linefeed at the end of each line in the text files for Windows.</p>

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

  <blockquote>
    <address>
................................................................................
  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.5.tar.gz</code>:</p>

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

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

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

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

  <p><i>On Windows</i>, use WinZip or some other program capable of unpacking
  the distribution file <code>tablelist6_5.zip</code> into the directory
  <code>tablelist6.5</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
................................................................................
  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.5, then it is highly
  recommended to specify the version number <code>6.5</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.5</code>,&nbsp; and their
  tile-based counterparts invoke the command&nbsp; <code>package require
  tablelist_tile 6.5</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>?
................................................................................
      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.5
source [file join $tablelist::library demos config.tcl]
</pre>
      </blockquote>
    </li>
  </ul>

  <p>In both cases, the script will print the following message to
................................................................................
  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.5

namespace eval demo {
    #
    # 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:
    #
................................................................................

  <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 &amp; feel with respect to the vertical scrollbar on
  the windowing systems other than <code>win32</code> (i.e., <code>aqua</code>
  and <code>x11</code>).</p>

  <p>We populate the tablelist by invoking the <code>demo::putConfig</code>
  procedure discussed below.&nbsp; The same script is associated with the
  <b>Refresh</b> button, as the value of its <code>-command</code>
  configuration option.&nbsp; This procedure is implemented as follows:</p>

  <blockquote>
................................................................................
  <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.5

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

    #
    # Create two images, needed in the procedure putChildren
    #
................................................................................
  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.5

#
# Add some entries to the Tk option database
#
set dir [file dirname [info script]]
source [file join $dir option.tcl]

................................................................................
</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 &amp; 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
................................................................................
    } else {
        set row [expr {$nodeIdx + 1}]
    }

    #
    # 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 &amp; time, for
    # sorting purposes (it will be removed by formatString).
    #
    set itemList {}
    if {[string compare $dir ""] == 0} {
        foreach volume [file volumes] {
            lappend itemList [list D[file nativename $volume] -1 D $volume]
        }
................................................................................
        } else {                                                ;# directory
            $tbl cellconfigure $row,0 -image clsdFolderImg
            $tbl rowattrib $row pathName $name

            #
            # Mark the row as collapsed if the directory is non-empty
            #
            if {[file readable $name] &amp;&amp; [llength \
                [glob -nocomplain -types {d f} -directory $name *]] != 0} {
                $tbl collapse $row
            }
        }

        incr row
    }
................................................................................
</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 &amp; 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>
................................................................................
  <code>miscWidgets.tcl</code> are similar).&nbsp; A few parts of the code are
  shown in <span>red</span> color &ndash; we will return to this towards the
  end of the section.</p>

  <blockquote>
    <pre>
package require Tk 8.4                          ;# because of "-compound"
package require tablelist 6.5
package require BWidget

wm title . "Serial Line Configuration"

#
# Add some entries to the Tk option database
#
................................................................................

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

#
# Populate the tablelist widget; set the activation
# date &amp; time to 10 minutes past the current clock value
#
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>set availImg [expr {($i &lt; 8) ? "checkedImg" : "uncheckedImg"}]
................................................................................
            #
            # Populate the ComboBox and allow no more
            # than 6 digits in its Entry component
            #
            $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 &amp;&amp; [regexp {^[0-9]*$} %S]}}
        }

        dataBits {
            #
            # Configure the SpinBox
            #
            $w configure -range {5 8 1} -editable no
................................................................................
            # "actDate" and "actTime" will have the same internal value
            #
            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 &amp; time must be in the future"
                $tbl rejectinput
            } else {
                $tbl cellconfigure $row,actTime -text $actClock
                return $actClock
            }
        }

................................................................................
    "310">
  </blockquote>

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

  <blockquote>
    <pre>
package require tablelist 6.5

wm title . "Tk Library Scripts"

#
# Add some entries to the Tk option database
#
set dir [file dirname [info script]]
................................................................................
  <span>red</span> color:</p>

  <p>First, we replace the starting lines</p>

  <blockquote>
    <pre>
package require Tk 8.3                          ;# because of entry validation
package require tablelist 6.5
</pre>
  </blockquote>

  <p>with</p>

  <blockquote>
    <pre>
package require tablelist<span>_tile</span> 6.5
</pre>
  </blockquote>

  <p>and the command</p>

  <blockquote>
    <pre>
................................................................................
}
option add *selectBorderWidth     $tablelist::themeDefaults(-selectborderwidth)</span>
</pre>
  </blockquote>

  <p>The demo script <code>tileWidgets.tcl</code> uses not only the
  Tablelist_tile package for creating a tablelist widget with a modern
  theme-specific look &amp; feel, but also the tile entry, spinbox, combobox,
  checkbutton, and menubutoon widgets for interactive cell editing.&nbsp; The
  resulting window has a nice theme-specific appearance:</p>

  <blockquote>
    <img src="tileWidgets.png" alt="Serial Line Configuration" width="839"
    height="404">
  </blockquote>

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

<body bgcolor="#FFFFFF">
  <div align="center">
    <h1>Tablelist Programmer's Guide</h1>

    <h2>For Tablelist Version 6.6</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>
................................................................................
    Configuration Options</a></li>

    <li><a href="#ex_browse">Two Widget Browsers Based on a tablelist</a></li>

    <li><a href="#ex_dirViewer">A Directory Viewer Based on a
    tablelist</a></li>

    <li><a href="#ex_styles">Improving the Look & Feel of a tablelist
    Widget</a></li>

    <li><a href="#ex_editing">Advanced Interactive tablelist Cell
    Editing</a></li>

    <li><a href="#ex_windows">A tablelist Widget Containing Embedded
    Windows</a></li>
................................................................................
  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>
................................................................................
      <a href="http://www.nemethi.de">http://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.6.tar.gz</code> for UNIX and
  <code>tablelist6_6.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 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.6.tar.gz</code>:</p>

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

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

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

  <p>Both commands will create a directory named <code>tablelist6.6</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_6.zip</code> into the directory
  <code>tablelist6.6</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
................................................................................
  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.6, then it is highly
  recommended to specify the version number <code>6.6</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.6</code>,&nbsp; and their
  tile-based counterparts invoke the command&nbsp; <code>package require
  tablelist_tile 6.6</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>?
................................................................................
      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.6
source [file join $tablelist::library demos config.tcl]
</pre>
      </blockquote>
    </li>
  </ul>

  <p>In both cases, the script will print the following message to
................................................................................
  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.6

namespace eval demo {
    #
    # 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:
    #
................................................................................

  <p>The option database entries for <code>*DemoTop.tf.borderWidth</code>,
  <code>*DemoTop.tf.relief</code>, <code>*DemoTop.tf.tbl.borderWidth</code>,
  and <code>*DemoTop.tf.tbl.highlightThickness</code> are implicitly used when
  managing the tablelist widget and the two scrollbars with the aid of
  <code>grid</code>.&nbsp; Notice how the <code><a href=
  "tablelistWidget.html#cornerpath">cornerpath</a></code> subcommand enables us
  to achieve a native look & feel with respect to the vertical scrollbar on the
  windowing systems other than <code>win32</code> (i.e., <code>aqua</code> and
  <code>x11</code>).</p>

  <p>We populate the tablelist by invoking the <code>demo::putConfig</code>
  procedure discussed below.&nbsp; The same script is associated with the
  <b>Refresh</b> button, as the value of its <code>-command</code>
  configuration option.&nbsp; This procedure is implemented as follows:</p>

  <blockquote>
................................................................................
  <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.6

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

    #
    # Create two images, needed in the procedure putChildren
    #
................................................................................
  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.6

#
# Add some entries to the Tk option database
#
set dir [file dirname [info script]]
source [file join $dir option.tcl]

................................................................................
</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
................................................................................
    } else {
        set row [expr {$nodeIdx + 1}]
    }

    #
    # 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).
    #
    set itemList {}
    if {[string compare $dir ""] == 0} {
        foreach volume [file volumes] {
            lappend itemList [list D[file nativename $volume] -1 D $volume]
        }
................................................................................
        } else {                                                ;# directory
            $tbl cellconfigure $row,0 -image clsdFolderImg
            $tbl rowattrib $row pathName $name

            #
            # Mark the row as collapsed if the directory is non-empty
            #
            if {[file readable $name] && [llength \
                [glob -nocomplain -types {d f} -directory $name *]] != 0} {
                $tbl collapse $row
            }
        }

        incr row
    }
................................................................................
</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>
................................................................................
  <code>miscWidgets.tcl</code> are similar).&nbsp; A few parts of the code are
  shown in <span>red</span> color &ndash; we will return to this towards the
  end of the section.</p>

  <blockquote>
    <pre>
package require Tk 8.4                          ;# because of "-compound"
package require tablelist 6.6
package require BWidget

wm title . "Serial Line Configuration"

#
# Add some entries to the Tk option database
#
................................................................................

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

#
# Populate the tablelist widget; set the activation
# date & time to 10 minutes past the current clock value
#
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>set availImg [expr {($i &lt; 8) ? "checkedImg" : "uncheckedImg"}]
................................................................................
            #
            # Populate the ComboBox and allow no more
            # than 6 digits in its Entry component
            #
            $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 {
            #
            # Configure the SpinBox
            #
            $w configure -range {5 8 1} -editable no
................................................................................
            # "actDate" and "actTime" will have the same internal value
            #
            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
            }
        }

................................................................................
    "310">
  </blockquote>

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

  <blockquote>
    <pre>
package require tablelist 6.6

wm title . "Tk Library Scripts"

#
# Add some entries to the Tk option database
#
set dir [file dirname [info script]]
................................................................................
  <span>red</span> color:</p>

  <p>First, we replace the starting lines</p>

  <blockquote>
    <pre>
package require Tk 8.3                          ;# because of entry validation
package require tablelist 6.6
</pre>
  </blockquote>

  <p>with</p>

  <blockquote>
    <pre>
package require tablelist<span>_tile</span> 6.6
</pre>
  </blockquote>

  <p>and the command</p>

  <blockquote>
    <pre>
................................................................................
}
option add *selectBorderWidth     $tablelist::themeDefaults(-selectborderwidth)</span>
</pre>
  </blockquote>

  <p>The demo script <code>tileWidgets.tcl</code> uses not only the
  Tablelist_tile package for creating a tablelist widget with a modern
  theme-specific look & feel, but also the tile entry, spinbox, combobox,
  checkbutton, and menubutoon widgets for interactive cell editing.&nbsp; The
  resulting window has a nice theme-specific appearance:</p>

  <blockquote>
    <img src="tileWidgets.png" alt="Serial Line Configuration" width="839"
    height="404">
  </blockquote>

Changes to modules/tablelist/doc/tablelistBWidget.html.

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

<body bgcolor="#FFFFFF">
  <div align="center">
    <h1>Interactive Tablelist Cell Editing Using the BWidget Package</h1>

    <h2>For Tablelist Version 6.5</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>

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

<body bgcolor="#FFFFFF">
  <div align="center">
    <h1>Interactive Tablelist Cell Editing Using the BWidget Package</h1>

    <h2>For Tablelist Version 6.6</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>

Changes to modules/tablelist/doc/tablelistBinding.html.

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

<body bgcolor="#FFFFFF">
  <div align="center">
    <h1>Commands Related to Binding Scripts</h1>

    <h2>For Tablelist Version 6.5</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>

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

<body bgcolor="#FFFFFF">
  <div align="center">
    <h1>Commands Related to Binding Scripts</h1>

    <h2>For Tablelist Version 6.6</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>

Changes to modules/tablelist/doc/tablelistColSort.html.

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

<body bgcolor="#FFFFFF">
  <div align="center">
    <h1>Commands for Interactive Sorting by One or More Columns</h1>

    <h2>For Tablelist Version 6.5</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>

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

<body bgcolor="#FFFFFF">
  <div align="center">
    <h1>Commands for Interactive Sorting by One or More Columns</h1>

    <h2>For Tablelist Version 6.6</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>

Changes to modules/tablelist/doc/tablelistCombobox.html.

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

<body bgcolor="#FFFFFF">
  <div align="center">
    <h1>Interactive Tablelist Cell Editing Using the combobox Package</h1>

    <h2>For Tablelist Version 6.5</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>

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

<body bgcolor="#FFFFFF">
  <div align="center">
    <h1>Interactive Tablelist Cell Editing Using the combobox Package</h1>

    <h2>For Tablelist Version 6.6</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>

Changes to modules/tablelist/doc/tablelistCtext.html.

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

<body bgcolor="#FFFFFF">
  <div align="center">
    <h1>Interactive Tablelist Cell Editing Using the ctext Package</h1>

    <h2>For Tablelist Version 6.5</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>

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

<body bgcolor="#FFFFFF">
  <div align="center">
    <h1>Interactive Tablelist Cell Editing Using the ctext Package</h1>

    <h2>For Tablelist Version 6.6</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>

Changes to modules/tablelist/doc/tablelistIwidgets.html.

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

<body bgcolor="#FFFFFF">
  <div align="center">
    <h1>Interactive Tablelist Cell Editing Using the Iwidgets Package</h1>

    <h2>For Tablelist Version 6.5</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>

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

<body bgcolor="#FFFFFF">
  <div align="center">
    <h1>Interactive Tablelist Cell Editing Using the Iwidgets Package</h1>

    <h2>For Tablelist Version 6.6</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>

Changes to modules/tablelist/doc/tablelistMentry.html.

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

<body bgcolor="#FFFFFF">
  <div align="center">
    <h1>Interactive Tablelist Cell Editing Using the Mentry Package</h1>

    <h2>For Tablelist Version 6.5</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>
................................................................................
    <code><b>mentry::dateTimeMentry</b></code> command from the Mentry (or
    Mentry_tile) package for interactive cell editing in tablelist
    widgets.&nbsp; The <code><i>format</i></code>,
    <code><i>dateSeparator</i></code>, and <code><i>timeSeparator</i></code>
    arguments have the same meanings as in the
    <code><b>mentry::dateTimeMentry</b></code> command.&nbsp; If the
    <code><b>-gmt</b></code> argument is present then both the internal clock
    value and its external date &amp; time representation in the mentry widget
    will be viewed as Greenwich Mean Time, otherwise as local time.&nbsp; The
    second optional argument specifies the name to be used for the mentry
    widget as the value of the <code><b><a href=
    "tablelistWidget.html#col_editwindow">-editwindow</a></b></code> column or
    cell configuration option.&nbsp; It may be any string that is different
    from the <a href="tablelistTkCore.html">Tk core</a> and <a href=
    "tablelistTile.html">tile</a> edit window names.&nbsp; The default is
    <code><b>dateTimeMentry</b></code>.&nbsp; The command returns its
    <code><i>name</i></code> argument.</dd>

    <dd class="tm">A tablelist column having the above <code><i>name</i></code>
    as the value of its <code><b>-editwindow</b></code> option must contain as
    internal cell values date &amp; time information in seconds (displayed with
    the aid of a command given by the <code><b><a href=
    "tablelistWidget.html#col_formatcommand">-formatcommand</a></b></code>
    column configuration option).&nbsp; The <code><b><a href=
    "tablelistWidget.html#finishediting">finishediting</a></b></code>
    subcommand of the Tcl command associated with the tablelist widget will
    retrieve the content of the embedded window used for interactive cell
    editing by invoking the <code><b>mentry::getClockVal</b></code>
    command.&nbsp; The value returned by this command (a clock value in seconds

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

<body bgcolor="#FFFFFF">
  <div align="center">
    <h1>Interactive Tablelist Cell Editing Using the Mentry Package</h1>

    <h2>For Tablelist Version 6.6</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>
................................................................................
    <code><b>mentry::dateTimeMentry</b></code> command from the Mentry (or
    Mentry_tile) package for interactive cell editing in tablelist
    widgets.&nbsp; The <code><i>format</i></code>,
    <code><i>dateSeparator</i></code>, and <code><i>timeSeparator</i></code>
    arguments have the same meanings as in the
    <code><b>mentry::dateTimeMentry</b></code> command.&nbsp; If the
    <code><b>-gmt</b></code> argument is present then both the internal clock
    value and its external date & time representation in the mentry widget will
    be viewed as Greenwich Mean Time, otherwise as local time.&nbsp; The second
    optional argument specifies the name to be used for the mentry widget as
    the value of the <code><b><a href=
    "tablelistWidget.html#col_editwindow">-editwindow</a></b></code> column or
    cell configuration option.&nbsp; It may be any string that is different
    from the <a href="tablelistTkCore.html">Tk core</a> and <a href=
    "tablelistTile.html">tile</a> edit window names.&nbsp; The default is
    <code><b>dateTimeMentry</b></code>.&nbsp; The command returns its
    <code><i>name</i></code> argument.</dd>

    <dd class="tm">A tablelist column having the above <code><i>name</i></code>
    as the value of its <code><b>-editwindow</b></code> option must contain as
    internal cell values date & time information in seconds (displayed with the
    aid of a command given by the <code><b><a href=
    "tablelistWidget.html#col_formatcommand">-formatcommand</a></b></code>
    column configuration option).&nbsp; The <code><b><a href=
    "tablelistWidget.html#finishediting">finishediting</a></b></code>
    subcommand of the Tcl command associated with the tablelist widget will
    retrieve the content of the embedded window used for interactive cell
    editing by invoking the <code><b>mentry::getClockVal</b></code>
    command.&nbsp; The value returned by this command (a clock value in seconds

Changes to modules/tablelist/doc/tablelistThemes.html.

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

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

    <h2>For Tablelist Version 6.5</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>

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

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

    <h2>For Tablelist Version 6.6</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>

Changes to modules/tablelist/doc/tablelistTile.html.

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

<body bgcolor="#FFFFFF">
  <div align="center">
    <h1>Interactive Tablelist Cell Editing Using Tile Widgets</h1>

    <h2>For Tablelist Version 6.5</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>

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

<body bgcolor="#FFFFFF">
  <div align="center">
    <h1>Interactive Tablelist Cell Editing Using Tile Widgets</h1>

    <h2>For Tablelist Version 6.6</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>

Changes to modules/tablelist/doc/tablelistTkCore.html.

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

<body bgcolor="#FFFFFF">
  <div align="center">
    <h1>Interactive Tablelist Cell Editing Using Tk Core Widgets</h1>

    <h2>For Tablelist Version 6.5</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>

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

<body bgcolor="#FFFFFF">
  <div align="center">
    <h1>Interactive Tablelist Cell Editing Using Tk Core Widgets</h1>

    <h2>For Tablelist Version 6.6</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>

Changes to modules/tablelist/doc/tablelistWidget.html.

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

<body bgcolor="#FFFFFF">
  <div align="center">
    <h1>The <code><b>tablelist::tablelist</b></code> Command</h1>

    <h2>For Tablelist Version 6.5</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>
................................................................................

    <dd><code><b><a href="#forceeditendcommand">-forceeditendcommand</a></b>
    <i>boolean</i></code></dd>

    <dd><code><b><a href="#fullseparators">-fullseparators</a></b>
    <i>boolean</i></code></dd>

    <dd><code><b><a href="#height">-height</a></b> <i>lines</i></code></dd>

    <dd><code><b><a href="#incrarrowtype">-incrarrowtype</a></b>
    <b>up</b>|<b>down</b></code></dd>

    <dd><code><b><a href="#instanttoggle">-instanttoggle</a></b>
    <i>boolean</i></code></dd>

................................................................................
    <i>boolean</i></code></dd>

    <dd><code><b><a href="#resizablecolumns">-resizablecolumns</a></b>
    <i>boolean</i></code></dd>

    <dd><code><b><a href="#resizecursor">-resizecursor</a></b>
    <i>cursor</i></code></dd>




    <dd><code><b><a href="#selectmode">-selectmode</a></b>
    <b>single</b>|<b>browse</b>|<b>multiple</b>|<b>extended</b></code></dd>

    <dd><code><b><a href="#selecttype">-selecttype</a></b>
    <b>row</b>|<b>cell</b></code></dd>

................................................................................
    <dd><code><b><a href="#col_name">-name</a></b> <i>name</i></code></dd>

    <dd><code><b><a href="#col_resizable">-resizable</a></b>
    <i>boolean</i></code></dd>

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




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

    <dd><code><b><a href="#col_showarrow">-showarrow</a></b>
    <i>boolean</i></code></dd>

................................................................................
    <dt class="tm"><a href="#colors_and_fonts">COLORS AND FONTS</a></dt>

    <dt class="tm"><a href="#tree_widget">USING A TABLELIST AS MULTI-COLUMN
    TREE WIDGET</a></dt>

    <dt class="tm"><a href="#cell_editing">INTERACTIVE CELL EDITING</a></dt>

    <dt class="tm"><a href="#drag_and_drop_support">DRAG &amp; DROP
    SUPPORT</a></dt>

    <dt class="tm"><a href="#virtual_events">VIRTUAL EVENTS</a></dt>

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

    <dd>
................................................................................
    Instead of an image, a tablelist cell (in both the body and the header) can
    also contain an embedded window, placed to the left or right of the text,
    just like an embedded image.</dd>

    <dd class="tm">When a tablelist is used as a tree widget, one of its
    columns will display the tree hierarchy with the aid of indentations and
    expand/collapse controls.&nbsp; The Tablelist package provides a great
    variety of tree styles controlling the look &amp; feel of that column, and
    chooses the correct default style depending on the windowing system,
    operating system version, and tile theme.&nbsp; In a tablelist used as a
    multi-column tree widget, every row of its body (but not of its header) is
    at the same time a tree <b>node</b>, having exactly one <b>parent</b> node
    and any number of <b>child</b> nodes.&nbsp; The tree's origin is the
    invisible <b>root</b> node, which has no parent itself and whose children
    are the <b>top-level</b> nodes.</dd>
................................................................................
    <code><b>-highlightthickness</b></code> options are only supported by the
    Tablelist package, but not by Tablelist_tile.&nbsp; When using the package
    Tablelist_tile, the options <code><b>-selectbackground</b></code>,
    <code><b>-selectborderwidth</b></code>, and
    <code><b>-selectforeground</b></code> have theme-specific default
    values.</dd>

    <dd class="tm"><b>REMARK:</b>&nbsp; If the value of the <code><b><a href=
    "#width">-width</a></b></code> configuration option is zero or less and the
    tablelist has <a href="#stretch">stretchable</a> columns, then the
    <code><b>-setgrid</b></code> option will be ignored.&nbsp; This minor
    restriction has technical reasons and is only relevant on X11.</dd>











    <dt class="tm" id="body_options"><b>OPTIONS FOR THE BODY AND HEADER
    COMPONENTS OF THE WIDGET</b></dt>

    <dd>
      <pre>
<b>-background  -disabledforeground  -font  -foreground</b>
................................................................................
        operation, the command specified by this option might look like in the
        code below:</p>

        <blockquote>
          <pre>
proc acceptDropCmd {tbl targetRow sourceRow} {
    set rowCount [[$tbl <a href="#size">size</a>]
    return [expr {$sourceRow != $rowCount - 1 &amp;&amp; $targetRow &lt; $rowCount}]
}
</pre>
        </blockquote>
      </blockquote>
    </dd>

    <dd id="activestyle">
................................................................................
        no effect.</p>

        <p>On Windows Vista, 7, 8, and 10, the sort arrows are shown
        horizontally centered in the header labels, just below their top
        edges:</p>

        <p><img src="arrowStyles_vista.png" alt="Arrow Styles Vista" width=
        "638" height="124"></p>

        <p>The arrow style <code><b>photo7x7</b></code> uses PNG images that
        look and behave very close to the native sort arrows on Mac OS X Aqua
        versions earlier than 10.10 (Yosemite).&nbsp; This arrow style is only
        supported if the Tk version is either 8.6 (with built-in PNG support),
        or 8.5 and the <code><b>img::png</b></code> package can be loaded into
        the interpreter.&nbsp; When supported, <code><b>photo7x7</b></code>
................................................................................

      <blockquote>
        <p>Specifies a boolean value that controls whether to trigger the
        automatic scrolling when the mouse leaves the tablelist window with
        button 1 down.&nbsp; The default is <code>1</code>, meaning that
        automatic scrolling will be in effect, just like in the case of the Tk
        listbox widget.&nbsp; However, when using the TkDND package or some
        other drag &amp; drop implementation, you might want to set this option
        to <code>0</code>, in order to avoid any conflicts between the drag
        operation and the automatic scrolling.</p>

        <p><b>REMARK:</b>&nbsp; Starting with Tablelist version 5.12, this
        option has become obsolete, because the default bindings now suppress
        the above-mentioned automatic scrolling if the tablelist's body
        component was registered as a drag source for mouse button 1 via
        the&nbsp; <code><b>tkdnd::drag_source register</b></code>&nbsp; or the
................................................................................

          <td><code><b>&nbsp;CustomDragSource</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>Specifies a boolean value that indicates whether the tablelist
        widget is a drag source for some drag &amp; drop implementation other
        than TkDND and the drag &amp; drop framework included in BWidget.&nbsp;
        If true then the default bindings will perform an automatic <a href=
        "#global_drag_and_drop">drag-friendly handling of the selection</a> and
        will suppress the automatic scrolling when the mouse leaves the
        tablelist window with button 1 down.&nbsp; The default is
        <code>0</code>.</p>
      </blockquote>
    </dd>

................................................................................
          <td>Database Class:</td>

          <td><code><b>&nbsp;Height</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>Specifies the desired height for the window, in units of characters
        in the font given by the <code><b>-font</b></code> option.&nbsp; This
        is at the same time the desired height in lines, provided that no
        column-, row-, or cell-specific fonts, multi-line elements, or embedded
        images or windows will make the height of any of the rows different
        from the one corresponding to the above-mentioned font.&nbsp; With this
        restriction, if the option's value is zero or less, then the window's




        height is made just large enough to hold all the items in the tablelist
        widget.</p>









      </blockquote>
    </dd>

    <dd id="incrarrowtype">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
................................................................................
          <td>Database Class:</td>

          <td><code><b>&nbsp;LabelCommand</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>Specifies the Tcl command to be invoked when mouse button 1 is
        pressed over one of the header labels and later released over the same

        label.&nbsp; When the <code><b>&lt;ButtonRelease-1&gt;</b></code> event
        occurs, the command is automatically concatenated with the path name of
        the tablelist widget and the column index of the respective label, and
        the resulting script is evaluated in the global scope.&nbsp; If the


        tablelist's <code><b><a href="#state">state</a></b></code> is
        <code><b>disabled</b></code> then this action will not take
        place.&nbsp; The most common value of this option is <code><b><a href=

        "tablelistColSort.html#sortByColumn">tablelist::sortByColumn</a></b></code>;
        this command sorts the items based on the column whose index was passed
        to it as second argument.</p>
      </blockquote>
    </dd>

    <dd id="labelcommand2">
................................................................................
          <td>Database Class:</td>

          <td><code><b>&nbsp;LabelCommand2</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>Specifies the Tcl command to be invoked when mouse button 1 is
        pressed together with the <code>Shift</code> key over one of the header
        labels and later released over the same label.&nbsp; When the

        <code><b>&lt;ButtonRelease-1&gt;</b></code> event occurs, the command
        is automatically concatenated with the path name of the tablelist
        widget and the column index of the respective label, and the resulting
        script is evaluated in the global scope.&nbsp; If the tablelist's
        <code><b><a href="#state">state</a></b></code> is


        <code><b>disabled</b></code> then this action will not take
        place.&nbsp; The most common value of this option is <code><b><a href=

        "tablelistColSort.html#addToSortColumns">tablelist::addToSortColumns</a></b></code>;
        this command adds the column index passed to it as second argument to
        the list of sort columns and sorts the items based on the columns
        indicated by the modified list.</p>
      </blockquote>
    </dd>

................................................................................
          <td><code><b>&nbsp;MovableRows</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>Specifies a boolean value that determines whether the rows displayed
        in the tablelist's body can be moved interactively.&nbsp; See the

        <a href="#body_bindings">DEFAULT AND INDIVIDUAL BINDINGS FOR THE
        TABLELIST BODY</a> section below for information on moving a row
        interactively.&nbsp; The default value is <code>0</code>.</p>

        <p><b>REMARK:</b>&nbsp; The support for moving a row is restricted to
        the widget's body component.&nbsp; Moving of header rows is not
        supported.</p>
................................................................................
        resizing.&nbsp; The default value is
        <code><b>sb_h_double_arrow</b></code> on the windowing systems
        <code><b>x11</b></code> and <code><b>win32</b></code>, and the native
        cursor <code><b>resizeleftright</b></code> on the Macintosh windowing
        systems <code><b>classic</b></code> and <code><b>aqua</b></code>.</p>
      </blockquote>
    </dd>







































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

          <td><code><b>-selectmode</b></code></td>
................................................................................
        command from the BWidget package to display the full cell and label
        texts as tooltips for the cells and header labels with snipped
        contents.</p>

        <blockquote>
          <pre>
proc tooltipAddCmd {tbl row col} {
    if {($row &gt;= 0 &amp;&amp; [$tbl <a href=
"#iselemsnipped">iselemsnipped</a> $row,$col fullText]) ||
        ($row &lt;  0 &amp;&amp; [$tbl <a href=
"#istitlesnipped">istitlesnipped</a> $col fullText])} {
        DynamicHelp::add $tbl -text $fullText
    }
}
</pre>
        </blockquote>

................................................................................
        <p>If the widget can also contain header items then a slightly more
        complicated procedure is needed:</p>

        <blockquote>
          <pre>
proc tooltipAddCmd {tbl row col} {
    if {[string is integer $row]} {
        if {($row &gt;= 0 &amp;&amp; [$tbl <a href=
"#iselemsnipped">iselemsnipped</a> $row,$col fullText]) ||
            ($row &lt;  0 &amp;&amp; [$tbl <a href=
"#istitlesnipped">istitlesnipped</a> $col fullText])} {
            DynamicHelp::add $tbl -text $fullText
        }
    } else {
        set row [string range $row 1 end]
        if {[$tbl <a href=
"#hdr_iselemsnipped">header iselemsnipped</a> $row,$col fullText]} {
................................................................................
        <p>If you prefer to use the <code><b>tooltip::tooltip</b></code>
        command from the tooltip package contained in tklib then the procedure
        becomes</p>

        <blockquote>
          <pre>
proc tooltipAddCmd {tbl row col} {
    if {($row &gt;= 0 &amp;&amp; [$tbl <a href=
"#iselemsnipped">iselemsnipped</a> $row,$col fullText]) ||
        ($row &lt;  0 &amp;&amp; [$tbl <a href=
"#istitlesnipped">istitlesnipped</a> $col fullText])} {
        tooltip::tooltip $tbl $fullText
    }
}
</pre>
        </blockquote>

        <p>or, to cover also the case of header items:</p>

        <blockquote>
          <pre>
proc tooltipAddCmd {tbl row col} {
    if {[string is integer $row]} {
        if {($row &gt;= 0 &amp;&amp; [$tbl <a href=
"#iselemsnipped">iselemsnipped</a> $row,$col fullText]) ||
            ($row &lt;  0 &amp;&amp; [$tbl <a href=
"#istitlesnipped">istitlesnipped</a> $col fullText])} {
            tooltip::tooltip $tbl $fullText
        }
    } else {
        set row [string range $row 1 end]
        if {[$tbl <a href=
"#hdr_iselemsnipped">header iselemsnipped</a> $row,$col fullText]} {
................................................................................
          <td>Database Class:</td>

          <td><code><b>&nbsp;TreeStyle</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>Specifies the look &amp; feel of the column containing the
        indentations and expand/collapse controls in the body of a a tablelist
        used as a tree widget.&nbsp; This includes, among others, the images
        used for displaying the expand/collapse controls, the indentation
        width, and whether expand/collapse controls and indentations are to be
        protected when selecting a row or cell.&nbsp; The currently supported
        values are shown at a glance in the two tables below:</p>

        <p>Tree styles for native look &amp; feel:</p>

        <table border="2" cellspacing="0" cellpadding="3" rules="groups">
          <colgroup></colgroup>

          <colgroup></colgroup>

          <colgroup></colgroup>
................................................................................

              <th><code>winxpSilver</code></th>
            </tr>
          </tbody>

          <tbody align="center">
            <tr>


              <td><img src="vistaAero.png" alt="vistaAero" width="120" height=
              "54"></td>

              <td><img src="vistaClassic.png" alt="vistaClassic" width="120"
              height="51"></td>

              <td><img src="win7Aero.png" alt="win7Aero" width="120" height=
................................................................................
              "54"></td>

              <td><img src="win7Classic.png" alt="win7Classic" width="120"
              height="51"></td>

              <td><img src="win10.png" alt="win110" width="120" height=
              "54"></td>

              <td><img src="aqua.png" alt="aqua" width="120" height="54"></td>
            </tr>

            <tr>


              <th><code>vistaAero</code></th>

              <th><code>vistaClassic</code></th>

              <th><code>win7Aero</code></th>

              <th><code>win7Classic</code></th>

              <th><code>win10</code></th>

              <th><code>aqua</code></th>
            </tr>
          </tbody>

          <tbody align="center">
            <tr>
              <td><img src="ambiance.png" alt="ambiance" width="120" height=
              "63"></td>
................................................................................
        <p>If the tree style is <code><b>gtk</b></code>,
        <code><b>adwaita</b></code>, <code><b>blueMenta</b></code>,
        <code><b>ubuntu</b></code>, <code><b>ubuntu2</b></code>,
        <code><b>ubuntu3</b></code>, <code><b>mint</b></code>,
        <code><b>mint2</b></code>, <code><b>mate</b></code>,
        <code><b>menta</b></code>, <code><b>ubuntuMate</b></code>,
        <code><b>arc</b></code>, <code><b>oxygen2</b></code>,
        <code><b>vistaAero</b></code>, <code><b>win7Aero</b></code>,
        <code><b>win10</b></code>, <code><b>aqua</b></code>,
        <code><b>newWave</b></code>, <code><b>plain*</b></code>, or
        <code><b>bicolor*</b></code>, and the Tk version is either 8.6 (with
        built-in PNG support) or 8.5 and the <code><b>img::png</b></code>
        package can be loaded into the interpreter, then the images used for
        displaying the expand/collapse controls are PNG images with alpha
        channel.&nbsp; Otherwise (i.e., for the other tree styles or in the
        absence of PNG support) GIF images are used for the expand/collapse
................................................................................
          Instead, the event will be redirected to the widget container or the
          toplevel widget with the aid of the&nbsp; <code><b>event
          generate</b></code>&nbsp; command.&nbsp; This in turn will give rise
          to horizontal scrolling of the widget container, provided that the
          containing toplevel widget or the binding tag <code><b>all</b></code>
          has the necessary mouse wheel event bindings.</li>
        </ul>






      </blockquote>
    </dd>

    <dd id="ymousewheelwindow">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
................................................................................
          Instead, the event will be redirected to the widget container or the
          toplevel widget with the aid of the&nbsp; <code><b>event
          generate</b></code>&nbsp; command.&nbsp; This in turn will give rise
          to vertical scrolling of the widget container, provided that the
          containing toplevel widget or the binding tag <code><b>all</b></code>
          has the necessary mouse wheel event bindings.</li>
        </ul>






      </blockquote>
    </dd>

    <dt id="col_options"><b>COLUMN CONFIGURATION OPTIONS</b></dt>

    <dd>The following options are currently supported by the <code><b><a href=
    "#columncget">columncget</a></b></code>, <code><b><a href=
................................................................................
        <code><b>-labelcommand2</b> <i>command</i></code><br>
        <code><b>-labelfont</b> <i>fontName</i></code><br>
        <code><b>-labelforeground</b> <i>color</i></code> or
        <code><b>-labelfg</b> <i>color</i></code><br>
        <code><b>-labelheight</b> <i>lines</i></code><br>
        <code><b>-labelpady</b> <i>screenDistance</i></code><br>
        <code><b>-labelrelief</b> <i>relief</i></code></dt>


        <dd>The value of each of these options may also be an empty
        string.&nbsp; These options are the column-specific equivalents of the
        global ones having the same names, described in the <a href=
        "#widget_options">WIDGET-SPECIFIC OPTIONS</a> section.&nbsp; They
        override the options of the same names set at widget level if the
        specified value is not empty.&nbsp; If one of these options hasn't been
................................................................................
    text to the cell's new <i>internal</i> content, which is necessary if, due
    to the <code><b><a href="#col_formatcommand">-formatcommand</a></b></code>
    column configuration option, the cell's internal value is different from
    its external representation.&nbsp; See the description of the
    <code><b><a href="#forceeditendcommand">-forceeditendcommand</a></b></code>
    option for more about the invocation of the command mentioned above.</dd>

    <dt class="tm" id="drag_and_drop_support"><b>DRAG &amp; DROP
    SUPPORT</b></dt>

    <dd>As <a href="#global_drag_and_drop">described in detail</a> in the
    "DEFAULT AND INDIVIDUAL BINDINGS FOR THE TABLELIST BODY" section, the
    default binding scripts perform an automatic drag-friendly handling of the
    selection and of pointer movements with mouse button 1 down if the
    tablelist widget's <code><b><a href=
    "#customdragsource">-customdragsource</a></b></code> opton was set to true
    or its body component was registered as a drag source for mouse button 1
    via the&nbsp; <code><b>tkdnd::drag_source register</b></code>&nbsp; or the
    BWidget <code><b>DragSite::register</b></code> command.</dd>

    <dd class="tm">On the other hand, you can also register a tablelist widget
    as a TkDND drop target, by invoking the&nbsp; <code><b>tkdnd::drop_target
    register</b></code>&nbsp; command.&nbsp; Similarly, you can register the
    body component of a tablelist widget as a drop target for the drag &amp;
    drop framework included in BWidget, with the aid of the
    <code><b>DropSite::register</b></code> command.&nbsp; (Notice that for
    BWidget it is necessary to register the tablelist's <i>body</i> rather than
    the widget itself.)</dd>

    <dd class="tm">The action to be triggered by a drop event over a tablelist
    widget might depend on the row under the mouse and the vertical position of
    the mouse pointer within the containing row (if any).&nbsp; For example,
................................................................................
    return $action
}
</pre>
      </blockquote>
    </dd>

    <dd>
      <b>BWidget EXAMPLE:</b>&nbsp; For an introduction to drag &amp; drop with
      BWidget see the online tutorial <a href=
      "http://wiki.tcl.tk/16126">BWidget example: Drag and Drop Demo</a> by
      Kevin Walzer.&nbsp; The <code><b>DropSite::*</b></code> commands used in
      the following example are described in the "DropSite" reference page
      included in the BWidget distribution.&nbsp; When using this drag &amp;
      drop framework, you will have to register not only the tablelist's body,
      but also its target indicator as drop sites, to make sure that the target
      mark won't get hidden by moving the mouse cursor over it with mouse
      button 1 down:

      <blockquote>
        <pre>
package require BWidget

................................................................................
proc tblDropOverCmd {dropTarget dragSrc event rootX rootY op dataType data} {
    <i># $event may be "enter", "motion", or "leave"</i>
    set tbl [<a href=
"tablelistBinding.html#getTablelistPath">tablelist::getTablelistPath</a> $dropTarget]
    if {[string equal $event "leave"]} {
        set newWidget [winfo containing -displayof $dropTarget $rootX $rootY]
        if {![string equal $newWidget [$tbl <a href=
"#targetmarkpath">targetmarkpath</a>]] &amp;&amp;
            ![string equal $newWidget [$tbl <a href=
"#bodypath">bodypath</a>]]} {
            $tbl <a href="#hidetargetmark">hidetargetmark</a>
            return 2 ;<i># refuse the drop and re-invoke the callback on motion events</i>
        }
    }

................................................................................
        </tr>

        <tr valign="top">
          <td>
          <code><b>&lt;&lt;TablelistHeaderHeightChanged&gt;&gt;</b></code></td>

          <td>Generated whenever the (requested) height of the tablelist's
          header changes.</td>




          <td>The (requested) height of the tablelist's header.</td>
        </tr>

        <tr valign="top">
          <td>
          <code><b>&lt;&lt;TablelistRowHiddenStateChanged&gt;&gt;</b></code></td>
................................................................................
          <td>Not used.</td>
        </tr>

        <tr valign="top">
          <td><code><b>&lt;&lt;TablelistTitleColsWidthChanged&gt;&gt;</b></code></td>

          <td>Generated whenever the total width of the non-hidden title
          columns changes.</td>




          <td>The total width of the non-hidden title columns.</td>
        </tr>

        <tr valign="top">
          <td><code><b>&lt;&lt;TablelistViewUpdated&gt;&gt;</b></code></td>

................................................................................
        virtual event is generated, with its <code><b>-data</b></code> option
        set to the total width of the non-hidden title columns for Tk versions
        8.5 and higher.</dd>

        <dd class="tm">
          <b>REMARK 1:</b>&nbsp; This subcommand enables you to manage the
          vertical scrollbar (if any) to appear below the tablelist widget's
          header, thus respecting the native look &amp; feel on Mac OS X Aqua
          and on many modern Linux systems.&nbsp; As shown in the following
          example, it is recommended to always create a scrolled tablelist
          along with the scrollbar(s) as children of a (ttk::)frame widget:

          <blockquote>
            <pre>
<i># Add some entries to the Tk option database</i>
option add *ScrollArea.borderWidth                      1
................................................................................
            <p>For a tablelist widget having two header rows and one title
            column, the scrollbars of the modified example will appear like in
            the screenshot below (on Windows this is only valid for the
            horizontal scrollbar):</p>

            <p><img src="scrollbars.png" alt="Scrollbars" width="461" height=
            "274"></p>































          </blockquote>
        </dd>

        <dt id="curcellselection"><code><i>pathName</i> <b>curcellselection</b>
        ?<b>-all</b>|<b>-nonhidden</b>|<b>-viewable</b>?</code></dt>

        <dd>Returns a list containing the canonical indices (of the form
................................................................................
        <b>hidetargetmark</b></code></dt>

        <dd>Hides the horizontal gap or vertical bar displayed by the
        <code><b><a href="#showtargetmark">showtargetmark</a></b></code>
        command.&nbsp; No error is generated if the target indicator is not
        visible at the time the command is invoked.</dd>

        <dd class="tm">This command is designed to be used during a drag &amp;
        drop operation for which the tablelist widget (or its body component)
        was registered as a drop target.&nbsp; See the <a href=
        "#drag_and_drop_support">DRAG &amp; DROP SUPPORT</a> section for
        details and examples.</dd>

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

        <dd>Returns the path name of the label widget containing the image
        embedded into the cell given by <code><i>cellIndex</i></code>, as
        specified with the <code><b><a href="#cell_image">-image</a></b></code>
................................................................................
bind [.tbl <a href=
"#bodytag">bodytag</a>] &lt;Button-1&gt; {printClickedImage %W %x %y}<br>
proc printClickedImage {w x y} {
    foreach {tbl x y} [<a href=
"tablelistBinding.html#convEventFields">tablelist::convEventFields</a> $w $x $y] {}
    set cellIdx [$tbl <a href="#containingcell">containingcell</a> $x $y]
    scan $cellIdx "%d,%d" row col
    if {$row &gt;= 0 &amp;&amp; $col &gt;= 0 &amp;&amp;
        [string compare $w [$tbl <span>imagelabelpath</span> $cellIdx]] == 0} {
        puts "clicked the image of cell $cellIdx"
    }
}
</pre>
          </blockquote>
        </dd>
................................................................................
        number of items or is specified as <code><b>end</b></code> then the
        horizontal gap will be shown just <i>after</i> the tablelist's last
        row.&nbsp; If the subcommand is used with the
        <code><b>inside</b></code> option then the index
        <code><b>end</b></code> is interpreted as indicating the widget's last
        item.</dd>

        <dd class="tm">This command is designed to be used during a drag &amp;
        drop operation for which the tablelist widget (or its body component)
        was registered as a drop target.&nbsp; See the <a href=
        "#drag_and_drop_support">DRAG &amp; DROP SUPPORT</a> section for
        details and examples.</dd>

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

        <dd>Returns the total number of items in the tablelist body.</dd>

        <dt class="tm" id="sort"><code><i>pathName</i> <b>sort</b>
        ?<b>-increasing</b>|<b>-decreasing</b>?</code></dt>
................................................................................
        respectively.&nbsp; If the option <code><b>-vertical</b></code> was
        specified and no item of the tablelist's body contains the given
        y-position, then the return value is the list&nbsp;
        <code>{<b>inside</b> -1}</code>.&nbsp; The coordinate
        <code><i>y</i></code> is expected to be relative to the tablelist
        window itself (not its body component).</dd>

        <dd class="tm">This command is designed to be used during a drag &amp;
        drop operation for which the tablelist widget (or its body component)
        was registered as a drop target.&nbsp; See the <a href=
        "#drag_and_drop_support">DRAG &amp; DROP SUPPORT</a> section for
        details and examples.</dd>

        <dt class="tm" id="togglecolumnhide"><code><i>pathName</i>
        <b>togglecolumnhide</b> <i>firstColumn</i> <i>lastColumn</i></code><br>
        <code><i>pathName</i> <b>togglecolumnhide</b>
        <i>columnIndexList</i></code></dt>

        <dd>Toggles the value of the <code><b><a href=
................................................................................
    <code><b>&lt;&lt;ListboxSelect&gt;&gt;</b></code>.&nbsp; Instead of this
    event (which is supported for compatibility reasons), the virtual event
    <code><b>&lt;&lt;TablelistSelect&gt;&gt;</b></code> can be used to be made
    aware of any changes to tablelist selection.&nbsp; Both events will be
    generated independently of the selection type.</dd>

    <dd class="tm" id="local_drag_and_drop">
      <b>LOCAL DRAG &amp; DROP:</b>&nbsp; The following binding associated with
      the binding tag <code><b>TablelistBody</b></code> is only valid if the
      selection mode is <code><b>single</b></code> or
      <code><b>multiple</b></code>:

      <blockquote>
        <p>If mouse button 1 is clicked on an item and then dragged outside
        that item, and the value of the <code><b><a href=
        "#movablerows">-movablerows</a></b></code> configuration option is
................................................................................
        true, then the mouse cursor takes on the shape specified by the
        <code><b><a href="#movecursor">-movecursor</a></b></code> option,
        indicating that the item in question is being moved to another
        position.&nbsp; The new item position (if any) is visualized with the
        aid of a gap placed before the target row or a bar placed inside the
        latter (depending on the current mouse position), indicating whether
        the source item would be moved before this row or become a child of
        it.&nbsp; This <b>local drag &amp; drop</b> operation ends when mouse
        button 1 is released, and can be canceled by pressing the
        <code>Escape</code> key.&nbsp; In both cases, the mouse cursor is reset
        to its original value, specified by the <code><b>-cursor</b></code>
        configuration option.&nbsp; After releasing mouse button 1 in the
        presence of a valid target, the source item is moved before the target
        row or just before the latter's first child, and the virtual event
        <code><b>&lt;&lt;TablelistRowMoved&gt;&gt;</b></code> is
................................................................................
        The first list element will be the full key corresponding to the first
        argument, the second one will be <code><b>root</b></code> or the full
        key corresponding to the second argument, and the third list element
        will be identical to the third argument passed to the
        <code><b>move</b></code> subcommand.</p>

        <p>Notice that, depending on the current mouse position during the
        local drag &amp; drop, there can be a corresponding potential target
        row or not.&nbsp; For instance, a tree item cannot become a sibling of
        one of its descendants, and not all items might be allowed to have
        children or to become top-level ones (example: in a file manager,
        regular file items cannot be parents of other items and should not be
        allowed to become top-level ones).&nbsp; To decide whether the row
        corresponding to the y-coordinate of the current mouse position
        represents a valid potential target, the Tablelist code first checks
        whether moving the source item before that row or making it a child of
        the latter is allowed from the point of view of the general tree
        structure.&nbsp; If this is the case and the move operation would
        change the source item's parent (and the Tk version is at least 8.3),
        and the command specified as the value of the <code><b><a href=
        "#acceptchildcommand">-acceptchildcommand</a></b></code> configuration
        option is a nonempty string, then this command is concatenated with the
        path name of the tablelist widget, the node index of the would-be new
        parent node, and the row index of the dragged item, the resulting
        script is evaluated in the global scope, and if the return value (which
        must be a boolean) is false, then the source item will not be allowed
        to be moved to the current mouse position.&nbsp; Likewise, if the
................................................................................
        moved to the current mouse position.</p>

        <p>Recall that if the selection mode is <code><b>multiple</b></code>
        then <i>pressing</i> mouse button 1 on a selected item or element
        normally deselects that item or element (depending on the selection
        type).&nbsp; However, if in addition the value of the <code><b><a href=
        "#movablerows">-movablerows</a></b></code> configuration option is true
        then the clicked row is a potential drag source for the local drag
        &amp; drop operation described above, and for this reason the clicked
        item or element will only be deselected when <i>releasing</i> mouse
        button 1 over the same item or element.</p>
      </blockquote>
    </dd>

    <dd class="tm" id="global_drag_and_drop"><b>DRAG SOURCE SUPPORT FOR GLOBAL
    DRAG &amp; DROP:</b>&nbsp; Besides the local drag &amp; drop, the default
    bindings also support the TkDND compiled extension and the drag &amp; drop
    framework included in BWidget, as well as custom drag &amp; drop
    implementations.&nbsp; A tablelist widget is viewed as a <b>drag source for
    mouse button 1</b> if its body component was registered as such via
    the&nbsp; <code><b>tkdnd::drag_source register</b></code>&nbsp; or the
    BWidget <code><b>DragSite::register</b></code> command, or the tablelist's
    <code><b><a href="#customdragsource">-customdragsource</a></b></code>
    option was set to true.&nbsp; The default bindings provide drag source
    support as described below:</dd>

    <dd>
      <ol>
        <li class="tm">If the selection mode is <code><b>extended</b></code>
................................................................................
        <code><b>&lt;&lt;TablelistColumnResized&gt;&gt;</b></code> is
        generated, with its <code><b>-data</b></code> option set to the
        numerical column index for Tk versions 8.5 and higher.&nbsp; The same
        action is triggered by double-clicking the resize area of a header
        label with the <code>Shift</code> key held down.</li>
      </ol>
    </dd>



















































    <dd class="tm">If the tablelist's <code><b><a href=
    "#state">state</a></b></code> is <code><b>disabled</b></code> then none of
    the above actions occur: the labels are completely insensitive.</dd>

    <dd class="tm">
      If you want to define non-default bindings for the header labels, it is







|







 







|







 







>
>
>







 







>
>
>







 







|







 







|







 







|




>
>
>
>
>
>
>
>
>
>







 







|







 







|







 







|
|







 







|
|
|







 







|
|
|
|
|
|
|
>
>
>
>
|
|
>
>
>
>
>
>
>
>
>







 







|
|
>
|
|
|
|
>
>
|
|
|
>







 







|
|
|
>



|
|
>
>
|
|
>







 







>







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







 







|

|







 







|

|







 







|

|













|

|







 







|
|
|
|
|
|
|

|







 







>
>







 







<
<



>
>









<
<







 







|
|







 







>
>
>
>
>
>







 







>
>
>
>
>
>







 







>







 







|
<


|
|
|
|








|
|







 







|




|
|
|







 







|







 







|
>
>
>







 







|
>
>
>







 







|
|







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







 







|
|
|
|
|







 







|







 







|
|
|
|
|







 







|
|
|
|
|







 







|
|







 







|







 







|
|
|
|
|
|
|
|
|
|
|
|
|







 







|
|
|
|




|
|
|
|
|
|
|







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

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

<body bgcolor="#FFFFFF">
  <div align="center">
    <h1>The <code><b>tablelist::tablelist</b></code> Command</h1>

    <h2>For Tablelist Version 6.6</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>
................................................................................

    <dd><code><b><a href="#forceeditendcommand">-forceeditendcommand</a></b>
    <i>boolean</i></code></dd>

    <dd><code><b><a href="#fullseparators">-fullseparators</a></b>
    <i>boolean</i></code></dd>

    <dd><code><b><a href="#height">-height</a></b> <i>units</i></code></dd>

    <dd><code><b><a href="#incrarrowtype">-incrarrowtype</a></b>
    <b>up</b>|<b>down</b></code></dd>

    <dd><code><b><a href="#instanttoggle">-instanttoggle</a></b>
    <i>boolean</i></code></dd>

................................................................................
    <i>boolean</i></code></dd>

    <dd><code><b><a href="#resizablecolumns">-resizablecolumns</a></b>
    <i>boolean</i></code></dd>

    <dd><code><b><a href="#resizecursor">-resizecursor</a></b>
    <i>cursor</i></code></dd>

    <dd><code><b><a href="#selectfiltercommand">-selectfiltercommand</a></b>
    <i>command</i></code></dd>

    <dd><code><b><a href="#selectmode">-selectmode</a></b>
    <b>single</b>|<b>browse</b>|<b>multiple</b>|<b>extended</b></code></dd>

    <dd><code><b><a href="#selecttype">-selecttype</a></b>
    <b>row</b>|<b>cell</b></code></dd>

................................................................................
    <dd><code><b><a href="#col_name">-name</a></b> <i>name</i></code></dd>

    <dd><code><b><a href="#col_resizable">-resizable</a></b>
    <i>boolean</i></code></dd>

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

    <dd><code><b><a href="#col_labelopts">-selectfiltercommand</a></b>
    <i>command</i></code></dd>

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

    <dd><code><b><a href="#col_showarrow">-showarrow</a></b>
    <i>boolean</i></code></dd>

................................................................................
    <dt class="tm"><a href="#colors_and_fonts">COLORS AND FONTS</a></dt>

    <dt class="tm"><a href="#tree_widget">USING A TABLELIST AS MULTI-COLUMN
    TREE WIDGET</a></dt>

    <dt class="tm"><a href="#cell_editing">INTERACTIVE CELL EDITING</a></dt>

    <dt class="tm"><a href="#drag_and_drop_support">DRAG & DROP
    SUPPORT</a></dt>

    <dt class="tm"><a href="#virtual_events">VIRTUAL EVENTS</a></dt>

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

    <dd>
................................................................................
    Instead of an image, a tablelist cell (in both the body and the header) can
    also contain an embedded window, placed to the left or right of the text,
    just like an embedded image.</dd>

    <dd class="tm">When a tablelist is used as a tree widget, one of its
    columns will display the tree hierarchy with the aid of indentations and
    expand/collapse controls.&nbsp; The Tablelist package provides a great
    variety of tree styles controlling the look & feel of that column, and
    chooses the correct default style depending on the windowing system,
    operating system version, and tile theme.&nbsp; In a tablelist used as a
    multi-column tree widget, every row of its body (but not of its header) is
    at the same time a tree <b>node</b>, having exactly one <b>parent</b> node
    and any number of <b>child</b> nodes.&nbsp; The tree's origin is the
    invisible <b>root</b> node, which has no parent itself and whose children
    are the <b>top-level</b> nodes.</dd>
................................................................................
    <code><b>-highlightthickness</b></code> options are only supported by the
    Tablelist package, but not by Tablelist_tile.&nbsp; When using the package
    Tablelist_tile, the options <code><b>-selectbackground</b></code>,
    <code><b>-selectborderwidth</b></code>, and
    <code><b>-selectforeground</b></code> have theme-specific default
    values.</dd>

    <dd class="tm"><b>REMARK 1:</b>&nbsp; If the value of the <code><b><a href=
    "#width">-width</a></b></code> configuration option is zero or less and the
    tablelist has <a href="#stretch">stretchable</a> columns, then the
    <code><b>-setgrid</b></code> option will be ignored.&nbsp; This minor
    restriction has technical reasons and is only relevant on X11.</dd>

    <dd class="tm"><b>REMARK 2:</b>&nbsp; Instead of creating the scrollbar(s)
    manually and settings the <code><b>-xscrollcommand</b></code> and/or
    <code><b>-yscrollcommand</b></code> options accordingly, you might consider
    to use the <a href=
    "http://www.nemethi.de/scrollutil/scrollarea.html">scrollarea</a> widget of
    the <a href="http://www.nemethi.de/scrollutil/">Scrollutil</a> package,
    which greatly simplifies the creation of arbitrary scrolled widgets,
    supports both static and dynamic scrollbars, and respects the header
    component and title columns of tablelist widgets.</dd>

    <dt class="tm" id="body_options"><b>OPTIONS FOR THE BODY AND HEADER
    COMPONENTS OF THE WIDGET</b></dt>

    <dd>
      <pre>
<b>-background  -disabledforeground  -font  -foreground</b>
................................................................................
        operation, the command specified by this option might look like in the
        code below:</p>

        <blockquote>
          <pre>
proc acceptDropCmd {tbl targetRow sourceRow} {
    set rowCount [[$tbl <a href="#size">size</a>]
    return [expr {$sourceRow != $rowCount - 1 && $targetRow &lt; $rowCount}]
}
</pre>
        </blockquote>
      </blockquote>
    </dd>

    <dd id="activestyle">
................................................................................
        no effect.</p>

        <p>On Windows Vista, 7, 8, and 10, the sort arrows are shown
        horizontally centered in the header labels, just below their top
        edges:</p>

        <p><img src="arrowStyles_vista.png" alt="Arrow Styles Vista" width=
        "638" height="123"></p>

        <p>The arrow style <code><b>photo7x7</b></code> uses PNG images that
        look and behave very close to the native sort arrows on Mac OS X Aqua
        versions earlier than 10.10 (Yosemite).&nbsp; This arrow style is only
        supported if the Tk version is either 8.6 (with built-in PNG support),
        or 8.5 and the <code><b>img::png</b></code> package can be loaded into
        the interpreter.&nbsp; When supported, <code><b>photo7x7</b></code>
................................................................................

      <blockquote>
        <p>Specifies a boolean value that controls whether to trigger the
        automatic scrolling when the mouse leaves the tablelist window with
        button 1 down.&nbsp; The default is <code>1</code>, meaning that
        automatic scrolling will be in effect, just like in the case of the Tk
        listbox widget.&nbsp; However, when using the TkDND package or some
        other drag & drop implementation, you might want to set this option to
        <code>0</code>, in order to avoid any conflicts between the drag
        operation and the automatic scrolling.</p>

        <p><b>REMARK:</b>&nbsp; Starting with Tablelist version 5.12, this
        option has become obsolete, because the default bindings now suppress
        the above-mentioned automatic scrolling if the tablelist's body
        component was registered as a drag source for mouse button 1 via
        the&nbsp; <code><b>tkdnd::drag_source register</b></code>&nbsp; or the
................................................................................

          <td><code><b>&nbsp;CustomDragSource</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>Specifies a boolean value that indicates whether the tablelist
        widget is a drag source for some drag & drop implementation other than
        TkDND and the drag & drop framework included in BWidget.&nbsp; If true
        then the default bindings will perform an automatic <a href=
        "#global_drag_and_drop">drag-friendly handling of the selection</a> and
        will suppress the automatic scrolling when the mouse leaves the
        tablelist window with button 1 down.&nbsp; The default is
        <code>0</code>.</p>
      </blockquote>
    </dd>

................................................................................
          <td>Database Class:</td>

          <td><code><b>&nbsp;Height</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>Specifies the desired height for the tablelist's body, in units of
        characters in the font given by the <code><b>-font</b></code>
        option.&nbsp; This is at the same time the desired height in rows,
        provided that no column-, row-, or cell-specific fonts, multi-line
        elements, or embedded images or windows make the height of any of the
        body items different from the one corresponding to the above-mentioned
        font.&nbsp; If the option's value is zero or less, then the body's
        desired height in units of characters in the widget's font is kept in
        sync with the number of <a href="#isviewable">viewable</a> body items;
        again, if all the items in the tablelist's body have the height
        corresponding to the widget's font then this means that the body's
        desired height is made just large enough to hold all the viewable body
        items.</p>

        <p><b>REMARK:</b>&nbsp; Embedded images and windows often make the rows
        of the tablelist higher, resulting in a discrepancy between the value
        of this option and the number of rows visible in the body window.&nbsp;
        In many cases you can work around this problem by saving the value of
        the widget's <code><b>-font</b></code> option, setting the latter to a
        sufficiently large font, and then setting the <code><b>-font</b></code>
        row configuration option of each body item to the saved widget font
        value.</p>
      </blockquote>
    </dd>

    <dd id="incrarrowtype">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
................................................................................
          <td>Database Class:</td>

          <td><code><b>&nbsp;LabelCommand</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>Specifies a Tcl command to be invoked when mouse button 1 is pressed
        over one of the header labels and later released over the same
        label.&nbsp; Provided that the option's value is a nonempty string,
        when the <code><b>&lt;ButtonRelease-1&gt;</b></code> event occurs, the
        command is automatically concatenated with the path name of the
        tablelist widget and the column index of the respective label, and the
        resulting script is evaluated in the global scope.&nbsp; If another
        nonempty command was specified as the value of the option of the same
        name at column level then that column-specific command will be used
        instead of the global one.&nbsp; If the tablelist's <code><b><a href=
        "#state">state</a></b></code> is <code><b>disabled</b></code> then this
        action will not take place.&nbsp; The most common value of this option
        is <code><b><a href=
        "tablelistColSort.html#sortByColumn">tablelist::sortByColumn</a></b></code>;
        this command sorts the items based on the column whose index was passed
        to it as second argument.</p>
      </blockquote>
    </dd>

    <dd id="labelcommand2">
................................................................................
          <td>Database Class:</td>

          <td><code><b>&nbsp;LabelCommand2</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>Specifies a Tcl command to be invoked when mouse button 1 is pressed
        together with the <code>Shift</code> key over one of the header labels
        and later released over the same label.&nbsp; Provided that the
        option's value is a nonempty string, when the
        <code><b>&lt;ButtonRelease-1&gt;</b></code> event occurs, the command
        is automatically concatenated with the path name of the tablelist
        widget and the column index of the respective label, and the resulting
        script is evaluated in the global scope.&nbsp; If another nonempty
        command was specified as the value of the option of the same name at
        column level then that column-specific command will be used instead of
        the global one.&nbsp; If the tablelist's <code><b><a href=
        "#state">state</a></b></code> is <code><b>disabled</b></code> then this
        action will not take place.&nbsp; The most common value of this option
        is <code><b><a href=
        "tablelistColSort.html#addToSortColumns">tablelist::addToSortColumns</a></b></code>;
        this command adds the column index passed to it as second argument to
        the list of sort columns and sorts the items based on the columns
        indicated by the modified list.</p>
      </blockquote>
    </dd>

................................................................................
          <td><code><b>&nbsp;MovableRows</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>Specifies a boolean value that determines whether the rows displayed
        in the tablelist's body can be moved interactively.&nbsp; See the
        <a href="#local_drag_and_drop">LOCAL DRAG & DROP</a> subsection of the
        <a href="#body_bindings">DEFAULT AND INDIVIDUAL BINDINGS FOR THE
        TABLELIST BODY</a> section below for information on moving a row
        interactively.&nbsp; The default value is <code>0</code>.</p>

        <p><b>REMARK:</b>&nbsp; The support for moving a row is restricted to
        the widget's body component.&nbsp; Moving of header rows is not
        supported.</p>
................................................................................
        resizing.&nbsp; The default value is
        <code><b>sb_h_double_arrow</b></code> on the windowing systems
        <code><b>x11</b></code> and <code><b>win32</b></code>, and the native
        cursor <code><b>resizeleftright</b></code> on the Macintosh windowing
        systems <code><b>classic</b></code> and <code><b>aqua</b></code>.</p>
      </blockquote>
    </dd>

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

          <td><code><b>-selectfiltercommand</b></code></td>
        </tr>

        <tr>
          <td>Database Name:</td>

          <td><code><b>&nbsp;selectFilterCommand</b></code></td>
        </tr>

        <tr>
          <td>Database Class:</td>

          <td><code><b>&nbsp;SelectFilterCommand</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>Specifies a Tcl command which can be used for filtering the cells
        that will be selected when the default bindings for the header labels
        perform a <a href="#columnwise_selection">column-wise cell
        selection</a>.&nbsp; If the option's value is a nonempty string then
        this command is concatenated with the path name of the tablelist widget
        and the numerical index of the respective column, and the resulting
        script is evaluated in the global scope.&nbsp; If another nonempty
        command was specified as the value of the option of the same name at
        column level then that column-specific command will be used instead of
        the global one.&nbsp; In both cases, the resulting script is expected
        to return a list consisting of the row numbers of those cells contained
        in the column in question that are to be selected by the column-wise
        cell selection operation.</p>
      </blockquote>
    </dd>

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

          <td><code><b>-selectmode</b></code></td>
................................................................................
        command from the BWidget package to display the full cell and label
        texts as tooltips for the cells and header labels with snipped
        contents.</p>

        <blockquote>
          <pre>
proc tooltipAddCmd {tbl row col} {
    if {($row &gt;= 0 && [$tbl <a href=
"#iselemsnipped">iselemsnipped</a> $row,$col fullText]) ||
        ($row &lt;  0 && [$tbl <a href=
"#istitlesnipped">istitlesnipped</a> $col fullText])} {
        DynamicHelp::add $tbl -text $fullText
    }
}
</pre>
        </blockquote>

................................................................................
        <p>If the widget can also contain header items then a slightly more
        complicated procedure is needed:</p>

        <blockquote>
          <pre>
proc tooltipAddCmd {tbl row col} {
    if {[string is integer $row]} {
        if {($row &gt;= 0 && [$tbl <a href=
"#iselemsnipped">iselemsnipped</a> $row,$col fullText]) ||
            ($row &lt;  0 && [$tbl <a href=
"#istitlesnipped">istitlesnipped</a> $col fullText])} {
            DynamicHelp::add $tbl -text $fullText
        }
    } else {
        set row [string range $row 1 end]
        if {[$tbl <a href=
"#hdr_iselemsnipped">header iselemsnipped</a> $row,$col fullText]} {
................................................................................
        <p>If you prefer to use the <code><b>tooltip::tooltip</b></code>
        command from the tooltip package contained in tklib then the procedure
        becomes</p>

        <blockquote>
          <pre>
proc tooltipAddCmd {tbl row col} {
    if {($row &gt;= 0 && [$tbl <a href=
"#iselemsnipped">iselemsnipped</a> $row,$col fullText]) ||
        ($row &lt;  0 && [$tbl <a href=
"#istitlesnipped">istitlesnipped</a> $col fullText])} {
        tooltip::tooltip $tbl $fullText
    }
}
</pre>
        </blockquote>

        <p>or, to cover also the case of header items:</p>

        <blockquote>
          <pre>
proc tooltipAddCmd {tbl row col} {
    if {[string is integer $row]} {
        if {($row &gt;= 0 && [$tbl <a href=
"#iselemsnipped">iselemsnipped</a> $row,$col fullText]) ||
            ($row &lt;  0 && [$tbl <a href=
"#istitlesnipped">istitlesnipped</a> $col fullText])} {
            tooltip::tooltip $tbl $fullText
        }
    } else {
        set row [string range $row 1 end]
        if {[$tbl <a href=
"#hdr_iselemsnipped">header iselemsnipped</a> $row,$col fullText]} {
................................................................................
          <td>Database Class:</td>

          <td><code><b>&nbsp;TreeStyle</b></code></td>
        </tr>
      </table>

      <blockquote>
        <p>Specifies the look & feel of the column containing the indentations
        and expand/collapse controls in the body of a a tablelist used as a
        tree widget.&nbsp; This includes, among others, the images used for
        displaying the expand/collapse controls, the indentation width, and
        whether expand/collapse controls and indentations are to be protected
        when selecting a row or cell.&nbsp; The currently supported values are
        shown at a glance in the two tables below:</p>

        <p>Tree styles for native look & feel:</p>

        <table border="2" cellspacing="0" cellpadding="3" rules="groups">
          <colgroup></colgroup>

          <colgroup></colgroup>

          <colgroup></colgroup>
................................................................................

              <th><code>winxpSilver</code></th>
            </tr>
          </tbody>

          <tbody align="center">
            <tr>
              <td><img src="aqua.png" alt="aqua" width="120" height="54"></td>

              <td><img src="vistaAero.png" alt="vistaAero" width="120" height=
              "54"></td>

              <td><img src="vistaClassic.png" alt="vistaClassic" width="120"
              height="51"></td>

              <td><img src="win7Aero.png" alt="win7Aero" width="120" height=
................................................................................
              "54"></td>

              <td><img src="win7Classic.png" alt="win7Classic" width="120"
              height="51"></td>

              <td><img src="win10.png" alt="win110" width="120" height=
              "54"></td>


            </tr>

            <tr>
              <th><code>aqua</code></th>

              <th><code>vistaAero</code></th>

              <th><code>vistaClassic</code></th>

              <th><code>win7Aero</code></th>

              <th><code>win7Classic</code></th>

              <th><code>win10</code></th>


            </tr>
          </tbody>

          <tbody align="center">
            <tr>
              <td><img src="ambiance.png" alt="ambiance" width="120" height=
              "63"></td>
................................................................................
        <p>If the tree style is <code><b>gtk</b></code>,
        <code><b>adwaita</b></code>, <code><b>blueMenta</b></code>,
        <code><b>ubuntu</b></code>, <code><b>ubuntu2</b></code>,
        <code><b>ubuntu3</b></code>, <code><b>mint</b></code>,
        <code><b>mint2</b></code>, <code><b>mate</b></code>,
        <code><b>menta</b></code>, <code><b>ubuntuMate</b></code>,
        <code><b>arc</b></code>, <code><b>oxygen2</b></code>,
        <code><b>aqua</b></code>, <code><b>vistaAero</b></code>,
        <code><b>win7Aero</b></code>, <code><b>win10</b></code>,
        <code><b>newWave</b></code>, <code><b>plain*</b></code>, or
        <code><b>bicolor*</b></code>, and the Tk version is either 8.6 (with
        built-in PNG support) or 8.5 and the <code><b>img::png</b></code>
        package can be loaded into the interpreter, then the images used for
        displaying the expand/collapse controls are PNG images with alpha
        channel.&nbsp; Otherwise (i.e., for the other tree styles or in the
        absence of PNG support) GIF images are used for the expand/collapse
................................................................................
          Instead, the event will be redirected to the widget container or the
          toplevel widget with the aid of the&nbsp; <code><b>event
          generate</b></code>&nbsp; command.&nbsp; This in turn will give rise
          to horizontal scrolling of the widget container, provided that the
          containing toplevel widget or the binding tag <code><b>all</b></code>
          has the necessary mouse wheel event bindings.</li>
        </ul>

        <p><b>REMARK 3:</b>&nbsp; If you pass the tablelist widget to the
        <code><b><a href=
        "http://www.nemethi.de/scrollutil/wheelEvent.html#adapt">scrollutil::adaptWheelEventHandling</a></b></code>
        command then the latter sets this option to the path name of the
        containing toplevel window.</p>
      </blockquote>
    </dd>

    <dd id="ymousewheelwindow">
      <table border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>Command-Line Name:&nbsp;</td>
................................................................................
          Instead, the event will be redirected to the widget container or the
          toplevel widget with the aid of the&nbsp; <code><b>event
          generate</b></code>&nbsp; command.&nbsp; This in turn will give rise
          to vertical scrolling of the widget container, provided that the
          containing toplevel widget or the binding tag <code><b>all</b></code>
          has the necessary mouse wheel event bindings.</li>
        </ul>

        <p><b>REMARK 3:</b>&nbsp; If you pass the tablelist widget to the
        <code><b><a href=
        "http://www.nemethi.de/scrollutil/wheelEvent.html#adapt">scrollutil::adaptWheelEventHandling</a></b></code>
        command then the latter sets this option to the path name of the
        containing toplevel window.</p>
      </blockquote>
    </dd>

    <dt id="col_options"><b>COLUMN CONFIGURATION OPTIONS</b></dt>

    <dd>The following options are currently supported by the <code><b><a href=
    "#columncget">columncget</a></b></code>, <code><b><a href=
................................................................................
        <code><b>-labelcommand2</b> <i>command</i></code><br>
        <code><b>-labelfont</b> <i>fontName</i></code><br>
        <code><b>-labelforeground</b> <i>color</i></code> or
        <code><b>-labelfg</b> <i>color</i></code><br>
        <code><b>-labelheight</b> <i>lines</i></code><br>
        <code><b>-labelpady</b> <i>screenDistance</i></code><br>
        <code><b>-labelrelief</b> <i>relief</i></code></dt>
        <code><b>-selectfiltercommand</b> <i>command</i></code><br>

        <dd>The value of each of these options may also be an empty
        string.&nbsp; These options are the column-specific equivalents of the
        global ones having the same names, described in the <a href=
        "#widget_options">WIDGET-SPECIFIC OPTIONS</a> section.&nbsp; They
        override the options of the same names set at widget level if the
        specified value is not empty.&nbsp; If one of these options hasn't been
................................................................................
    text to the cell's new <i>internal</i> content, which is necessary if, due
    to the <code><b><a href="#col_formatcommand">-formatcommand</a></b></code>
    column configuration option, the cell's internal value is different from
    its external representation.&nbsp; See the description of the
    <code><b><a href="#forceeditendcommand">-forceeditendcommand</a></b></code>
    option for more about the invocation of the command mentioned above.</dd>

    <dt class="tm" id="drag_and_drop_support"><b>DRAG & DROP SUPPORT</b></dt>


    <dd>As <a href="#global_drag_and_drop">described in detail</a> in the
    <a href="#body_bindings">DEFAULT AND INDIVIDUAL BINDINGS FOR THE TABLELIST
    BODY</a> section, the default binding scripts perform an automatic
    drag-friendly handling of the selection and of pointer movements with mouse
    button 1 down if the tablelist widget's <code><b><a href=
    "#customdragsource">-customdragsource</a></b></code> opton was set to true
    or its body component was registered as a drag source for mouse button 1
    via the&nbsp; <code><b>tkdnd::drag_source register</b></code>&nbsp; or the
    BWidget <code><b>DragSite::register</b></code> command.</dd>

    <dd class="tm">On the other hand, you can also register a tablelist widget
    as a TkDND drop target, by invoking the&nbsp; <code><b>tkdnd::drop_target
    register</b></code>&nbsp; command.&nbsp; Similarly, you can register the
    body component of a tablelist widget as a drop target for the drag & drop
    framework included in BWidget, with the aid of the
    <code><b>DropSite::register</b></code> command.&nbsp; (Notice that for
    BWidget it is necessary to register the tablelist's <i>body</i> rather than
    the widget itself.)</dd>

    <dd class="tm">The action to be triggered by a drop event over a tablelist
    widget might depend on the row under the mouse and the vertical position of
    the mouse pointer within the containing row (if any).&nbsp; For example,
................................................................................
    return $action
}
</pre>
      </blockquote>
    </dd>

    <dd>
      <b>BWidget EXAMPLE:</b>&nbsp; For an introduction to drag & drop with
      BWidget see the online tutorial <a href=
      "http://wiki.tcl.tk/16126">BWidget example: Drag and Drop Demo</a> by
      Kevin Walzer.&nbsp; The <code><b>DropSite::*</b></code> commands used in
      the following example are described in the "DropSite" reference page
      included in the BWidget distribution.&nbsp; When using this drag & drop
      framework, you will have to register not only the tablelist's body, but
      also its target indicator as drop sites, to make sure that the target
      mark won't get hidden by moving the mouse cursor over it with mouse
      button 1 down:

      <blockquote>
        <pre>
package require BWidget

................................................................................
proc tblDropOverCmd {dropTarget dragSrc event rootX rootY op dataType data} {
    <i># $event may be "enter", "motion", or "leave"</i>
    set tbl [<a href=
"tablelistBinding.html#getTablelistPath">tablelist::getTablelistPath</a> $dropTarget]
    if {[string equal $event "leave"]} {
        set newWidget [winfo containing -displayof $dropTarget $rootX $rootY]
        if {![string equal $newWidget [$tbl <a href=
"#targetmarkpath">targetmarkpath</a>]] &&
            ![string equal $newWidget [$tbl <a href=
"#bodypath">bodypath</a>]]} {
            $tbl <a href="#hidetargetmark">hidetargetmark</a>
            return 2 ;<i># refuse the drop and re-invoke the callback on motion events</i>
        }
    }

................................................................................
        </tr>

        <tr valign="top">
          <td>
          <code><b>&lt;&lt;TablelistHeaderHeightChanged&gt;&gt;</b></code></td>

          <td>Generated whenever the (requested) height of the tablelist's
          header changes.&nbsp; Used by the <a href=
          "http://www.nemethi.de/scrollutil/scrollarea.html">scrollarea</a>
          widget of the <a href=
          "http://www.nemethi.de/scrollutil/">Scrollutil</a> package.</td>

          <td>The (requested) height of the tablelist's header.</td>
        </tr>

        <tr valign="top">
          <td>
          <code><b>&lt;&lt;TablelistRowHiddenStateChanged&gt;&gt;</b></code></td>
................................................................................
          <td>Not used.</td>
        </tr>

        <tr valign="top">
          <td><code><b>&lt;&lt;TablelistTitleColsWidthChanged&gt;&gt;</b></code></td>

          <td>Generated whenever the total width of the non-hidden title
          columns changes.&nbsp; Used by the <a href=
          "http://www.nemethi.de/scrollutil/scrollarea.html">scrollarea</a>
          widget of the <a href=
          "http://www.nemethi.de/scrollutil/">Scrollutil</a> package.</td>

          <td>The total width of the non-hidden title columns.</td>
        </tr>

        <tr valign="top">
          <td><code><b>&lt;&lt;TablelistViewUpdated&gt;&gt;</b></code></td>

................................................................................
        virtual event is generated, with its <code><b>-data</b></code> option
        set to the total width of the non-hidden title columns for Tk versions
        8.5 and higher.</dd>

        <dd class="tm">
          <b>REMARK 1:</b>&nbsp; This subcommand enables you to manage the
          vertical scrollbar (if any) to appear below the tablelist widget's
          header, thus respecting the native look & feel on Mac OS X Aqua and
          on many modern Linux systems.&nbsp; As shown in the following
          example, it is recommended to always create a scrolled tablelist
          along with the scrollbar(s) as children of a (ttk::)frame widget:

          <blockquote>
            <pre>
<i># Add some entries to the Tk option database</i>
option add *ScrollArea.borderWidth                      1
................................................................................
            <p>For a tablelist widget having two header rows and one title
            column, the scrollbars of the modified example will appear like in
            the screenshot below (on Windows this is only valid for the
            horizontal scrollbar):</p>

            <p><img src="scrollbars.png" alt="Scrollbars" width="461" height=
            "274"></p>
          </blockquote>
        </dd>

        <dd>
          <b>REMARK 3:</b>&nbsp; You can greatly simplify the creation of
          scrolled tablelists (and other scrolled widgets) by using a <a href=
          "http://www.nemethi.de/scrollutil/scrollarea.html">scrollarea</a>
          widget, which is part of the <a href=
          "http://www.nemethi.de/scrollutil/">Scrollutil</a> package.&nbsp; It
          supports both static and dynamic scrollbars and respects the header
          component and title columns of tablelist widgets.&nbsp; With the aid
          of the scrollarea widget, the rather technical code in the above
          example can be replaced with just a few lines:

          <blockquote>
            <pre>
package require scrollutil(_tile)

. . .

<i># Create the tablelist within a scrollarea</i>
set sa [scrollutil::scrollarea ...]
set tbl $sa.tbl
tablelist::tablelist $tbl ...
$sa setwidget $tbl

. . .

<i># Manage the scrollarea</i>
pack $sa -expand yes -fill both -padx 10 -pady 10
</pre>
          </blockquote>
        </dd>

        <dt id="curcellselection"><code><i>pathName</i> <b>curcellselection</b>
        ?<b>-all</b>|<b>-nonhidden</b>|<b>-viewable</b>?</code></dt>

        <dd>Returns a list containing the canonical indices (of the form
................................................................................
        <b>hidetargetmark</b></code></dt>

        <dd>Hides the horizontal gap or vertical bar displayed by the
        <code><b><a href="#showtargetmark">showtargetmark</a></b></code>
        command.&nbsp; No error is generated if the target indicator is not
        visible at the time the command is invoked.</dd>

        <dd class="tm">This command is designed to be used during a drag & drop
        operation for which the tablelist widget (or its body component) was
        registered as a drop target.&nbsp; See the <a href=
        "#drag_and_drop_support">DRAG & DROP SUPPORT</a> section for details
        and examples.</dd>

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

        <dd>Returns the path name of the label widget containing the image
        embedded into the cell given by <code><i>cellIndex</i></code>, as
        specified with the <code><b><a href="#cell_image">-image</a></b></code>
................................................................................
bind [.tbl <a href=
"#bodytag">bodytag</a>] &lt;Button-1&gt; {printClickedImage %W %x %y}<br>
proc printClickedImage {w x y} {
    foreach {tbl x y} [<a href=
"tablelistBinding.html#convEventFields">tablelist::convEventFields</a> $w $x $y] {}
    set cellIdx [$tbl <a href="#containingcell">containingcell</a> $x $y]
    scan $cellIdx "%d,%d" row col
    if {$row &gt;= 0 && $col &gt;= 0 &&
        [string compare $w [$tbl <span>imagelabelpath</span> $cellIdx]] == 0} {
        puts "clicked the image of cell $cellIdx"
    }
}
</pre>
          </blockquote>
        </dd>
................................................................................
        number of items or is specified as <code><b>end</b></code> then the
        horizontal gap will be shown just <i>after</i> the tablelist's last
        row.&nbsp; If the subcommand is used with the
        <code><b>inside</b></code> option then the index
        <code><b>end</b></code> is interpreted as indicating the widget's last
        item.</dd>

        <dd class="tm">This command is designed to be used during a drag & drop
        operation for which the tablelist widget (or its body component) was
        registered as a drop target.&nbsp; See the <a href=
        "#drag_and_drop_support">DRAG & DROP SUPPORT</a> section for details
        and examples.</dd>

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

        <dd>Returns the total number of items in the tablelist body.</dd>

        <dt class="tm" id="sort"><code><i>pathName</i> <b>sort</b>
        ?<b>-increasing</b>|<b>-decreasing</b>?</code></dt>
................................................................................
        respectively.&nbsp; If the option <code><b>-vertical</b></code> was
        specified and no item of the tablelist's body contains the given
        y-position, then the return value is the list&nbsp;
        <code>{<b>inside</b> -1}</code>.&nbsp; The coordinate
        <code><i>y</i></code> is expected to be relative to the tablelist
        window itself (not its body component).</dd>

        <dd class="tm">This command is designed to be used during a drag & drop
        operation for which the tablelist widget (or its body component) was
        registered as a drop target.&nbsp; See the <a href=
        "#drag_and_drop_support">DRAG & DROP SUPPORT</a> section for details
        and examples.</dd>

        <dt class="tm" id="togglecolumnhide"><code><i>pathName</i>
        <b>togglecolumnhide</b> <i>firstColumn</i> <i>lastColumn</i></code><br>
        <code><i>pathName</i> <b>togglecolumnhide</b>
        <i>columnIndexList</i></code></dt>

        <dd>Toggles the value of the <code><b><a href=
................................................................................
    <code><b>&lt;&lt;ListboxSelect&gt;&gt;</b></code>.&nbsp; Instead of this
    event (which is supported for compatibility reasons), the virtual event
    <code><b>&lt;&lt;TablelistSelect&gt;&gt;</b></code> can be used to be made
    aware of any changes to tablelist selection.&nbsp; Both events will be
    generated independently of the selection type.</dd>

    <dd class="tm" id="local_drag_and_drop">
      <b>LOCAL DRAG & DROP:</b>&nbsp; The following binding associated with the
      binding tag <code><b>TablelistBody</b></code> is only valid if the
      selection mode is <code><b>single</b></code> or
      <code><b>multiple</b></code>:

      <blockquote>
        <p>If mouse button 1 is clicked on an item and then dragged outside
        that item, and the value of the <code><b><a href=
        "#movablerows">-movablerows</a></b></code> configuration option is
................................................................................
        true, then the mouse cursor takes on the shape specified by the
        <code><b><a href="#movecursor">-movecursor</a></b></code> option,
        indicating that the item in question is being moved to another
        position.&nbsp; The new item position (if any) is visualized with the
        aid of a gap placed before the target row or a bar placed inside the
        latter (depending on the current mouse position), indicating whether
        the source item would be moved before this row or become a child of
        it.&nbsp; This <b>local drag & drop</b> operation ends when mouse
        button 1 is released, and can be canceled by pressing the
        <code>Escape</code> key.&nbsp; In both cases, the mouse cursor is reset
        to its original value, specified by the <code><b>-cursor</b></code>
        configuration option.&nbsp; After releasing mouse button 1 in the
        presence of a valid target, the source item is moved before the target
        row or just before the latter's first child, and the virtual event
        <code><b>&lt;&lt;TablelistRowMoved&gt;&gt;</b></code> is
................................................................................
        The first list element will be the full key corresponding to the first
        argument, the second one will be <code><b>root</b></code> or the full
        key corresponding to the second argument, and the third list element
        will be identical to the third argument passed to the
        <code><b>move</b></code> subcommand.</p>

        <p>Notice that, depending on the current mouse position during the
        local drag & drop, there can be a corresponding potential target row or
        not.&nbsp; For instance, a tree item cannot become a sibling of one of
        its descendants, and not all items might be allowed to have children or
        to become top-level ones (example: in a file manager, regular file
        items cannot be parents of other items and should not be allowed to
        become top-level ones).&nbsp; To decide whether the row corresponding
        to the y-coordinate of the current mouse position represents a valid
        potential target, the Tablelist code first checks whether moving the
        source item before that row or making it a child of the latter is
        allowed from the point of view of the general tree structure.&nbsp; If
        this is the case and the move operation would change the source item's
        parent (and the Tk version is at least 8.3), and the command specified
        as the value of the <code><b><a href=
        "#acceptchildcommand">-acceptchildcommand</a></b></code> configuration
        option is a nonempty string, then this command is concatenated with the
        path name of the tablelist widget, the node index of the would-be new
        parent node, and the row index of the dragged item, the resulting
        script is evaluated in the global scope, and if the return value (which
        must be a boolean) is false, then the source item will not be allowed
        to be moved to the current mouse position.&nbsp; Likewise, if the
................................................................................
        moved to the current mouse position.</p>

        <p>Recall that if the selection mode is <code><b>multiple</b></code>
        then <i>pressing</i> mouse button 1 on a selected item or element
        normally deselects that item or element (depending on the selection
        type).&nbsp; However, if in addition the value of the <code><b><a href=
        "#movablerows">-movablerows</a></b></code> configuration option is true
        then the clicked row is a potential drag source for the local drag &
        drop operation described above, and for this reason the clicked item or
        element will only be deselected when <i>releasing</i> mouse button 1
        over the same item or element.</p>
      </blockquote>
    </dd>

    <dd class="tm" id="global_drag_and_drop"><b>DRAG SOURCE SUPPORT FOR GLOBAL
    DRAG & DROP:</b>&nbsp; Besides the local drag & drop, the default bindings
    also support the TkDND compiled extension and the drag & drop framework
    included in BWidget, as well as custom drag & drop implementations.&nbsp; A
    tablelist widget is viewed as a <b>drag source for mouse button 1</b> if
    its body component was registered as such via the&nbsp;
    <code><b>tkdnd::drag_source register</b></code>&nbsp; or the BWidget
    <code><b>DragSite::register</b></code> command, or the tablelist's
    <code><b><a href="#customdragsource">-customdragsource</a></b></code>
    option was set to true.&nbsp; The default bindings provide drag source
    support as described below:</dd>

    <dd>
      <ol>
        <li class="tm">If the selection mode is <code><b>extended</b></code>
................................................................................
        <code><b>&lt;&lt;TablelistColumnResized&gt;&gt;</b></code> is
        generated, with its <code><b>-data</b></code> option set to the
        numerical column index for Tk versions 8.5 and higher.&nbsp; The same
        action is triggered by double-clicking the resize area of a header
        label with the <code>Shift</code> key held down.</li>
      </ol>
    </dd>

    <dd class="tm" id="columnwise_selection"><b>BINDINGS FOR COLUMN-WISE CELL
    SELECTION:</b>&nbsp; If the selection type is <code><b>cell</b></code> then
    a few further bindings apply to the header labels.&nbsp; In the description
    below the <code>Alt</code> key can be replaced with <code>Meta</code>; on
    Mac OS Classic and Mac OS X Aqua the <code>Command</code> key is used
    instead of <code>Alt</code> and <code>Meta</code>.&nbsp; Notice also that
    you can restrict the set of cells that will be selected when these bindings
    perform a column-wise cell selection:&nbsp; If the command specified by the
    <code><b><a href="#selectfiltercommand">-selectfiltercommand</a></b></code>
    option is a nonempty string then this command is concatenated with the path
    name of the tablelist widget and the numerical index of the respective
    column, and the resulting script is evaluated in the global scope.&nbsp; If
    another nonempty command was specified as the value of the option of the
    same name at column level then that column-specific command will be used
    instead of the global one.&nbsp; In both cases, only those cells contained
    in that column will be selected whose row numbers are contained in the list
    returned by the script.</dd>

    <dd>
      <ol>
        <li class="tm">Pressing mouse button 1 on a header label with the
        <code>Alt</code> key down selects the cells of the corresponding
        column, deselects everything else, and sets the anchor to the first
        viewable selected cell of that column; dragging the mouse with button 1
        down extends the selection to include all the columns between the
        anchor and the column under the mouse, inclusive.</li>

        <li class="tm">If the anchor column contains at least one selected cell
        then the range of selected columns can be adjusted by pressing button 1
        on a header label with the <code>Alt</code> and <code>Shift</code> keys
        down: this modifies the selection to consist of the cells of the
        columns between the anchor and the one under the mouse,
        inclusive.&nbsp; The un-anchored end of this new column-wise cell
        selection can also be dragged with the button down.</li>

        <li class="tm">Pressing button 1 on a header label with the
        <code>Alt</code> and <code>Control</code> keys down starts a toggle
        operation: the cells of the column corresponding to the clicked label
        will be deselected if at least one of them was selected before, and
        selected otherwise; in the first case the anchor is set to the first
        viewable cell of that column, while in the second case to the column's
        first viewable selected cell.&nbsp; The selection state of other cells
        is not changed.&nbsp; If subsequently the mouse is dragged with button
        1 down, then the selection state of the cells between the anchor column
        and the one under the mouse is set to match the toggled state of the
        anchor column; the selection state of all other cells remains what it
        was before the toggle operation began.</li>
      </ol>
    </dd>

    <dd class="tm">If the tablelist's <code><b><a href=
    "#state">state</a></b></code> is <code><b>disabled</b></code> then none of
    the above actions occur: the labels are completely insensitive.</dd>

    <dd class="tm">
      If you want to define non-default bindings for the header labels, it is