diff options
| author | treectrl <treectrl> | 2005-07-23 00:35:20 (GMT) |
|---|---|---|
| committer | treectrl <treectrl> | 2005-07-23 00:35:20 (GMT) |
| commit | 3119a6b4195b4f8ae8c338788103160833936983 (patch) | |
| tree | b377b3bb6880d1f193d289df6e5a7f5df7114ec9 /doc | |
| parent | 10f73bee8fa08d7e14c85086c94d4851c3a28316 (diff) | |
| download | tktreectrl-3119a6b4195b4f8ae8c338788103160833936983.zip tktreectrl-3119a6b4195b4f8ae8c338788103160833936983.tar.gz tktreectrl-3119a6b4195b4f8ae8c338788103160833936983.tar.bz2 | |
Changes for 2.1.
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/What's New in TkTreeCtrl.html | 611 | ||||
| -rw-r--r-- | doc/treectrl.html | 305 | ||||
| -rw-r--r-- | doc/treectrl.man | 301 | ||||
| -rw-r--r-- | doc/treectrl.n | 297 |
4 files changed, 1041 insertions, 473 deletions
diff --git a/doc/What's New in TkTreeCtrl.html b/doc/What's New in TkTreeCtrl.html index 25dfdba..ed598ef 100644 --- a/doc/What's New in TkTreeCtrl.html +++ b/doc/What's New in TkTreeCtrl.html @@ -1,10 +1,12 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
-<!-- $Id: What's\040New\040in\040TkTreeCtrl.html,v 1.9 2005/07/15 01:39:34 treectrl Exp $ -->
+<!-- $Id: What's\040New\040in\040TkTreeCtrl.html,v 1.10 2005/07/23 00:35:21 treectrl Exp $ -->
+
+
@@ -12,6 +14,9 @@ +
+
+
@@ -27,151 +32,194 @@ +
<h1>What's New in TkTreeCtrl 2.1</h1>
+
This version should be backwards compatible with 2.0, except for a few obscure changes.<br>
+
<h2>TreeCtrl Configuration Options</h2>
+
<table style="text-align: left; width: 100%;" border="1" cellpadding="2" cellspacing="2">
+
<tbody>
+
<tr>
+
<th style="background-color: rgb(255, 255, 204); width: 50%;">New</th>
+
<th style="background-color: rgb(204, 255, 255);">Comment</th>
+
</tr>
+
<tr>
+
<td>-itemwidth</td>
+
<td><br>
+
</td>
+
</tr>
+
<tr>
+
<td>-itemwidthequal</td>
+
<td>Deprecates the column -widthhack option.</td>
+
</tr>
+
<tr>
+
<td>-itemwidthmultiple</td>
+
<td>Deprecates the column -stepwidth option.</td>
+
</tr>
+
+
</tbody>
</table>
+
<h2>Column Configuration Options</h2>
+
<table style="text-align: left; width: 100%;" border="1" cellpadding="2" cellspacing="2">
+
<tbody>
+
<tr>
+
<th style="background-color: rgb(255, 255, 204); width: 50%;">Deprecated</th>
+
<th style="background-color: rgb(204, 255, 255);">What to use
instead</th>
+
</tr>
+
<tr>
+
<td>-stepwidth</td>
+
<td>treectrl's -itemwidthmultiple option</td>
+
</tr>
+
<tr>
+
<td>-widthhack</td>
+
<td>treectrl's -itemwidthequal option</td>
+
</tr>
+
+
</tbody>
</table>
+
<h2>Element Command</h2>
+
@@ -184,25 +232,38 @@ instead</th> <table style="text-align: left; width: 100%;" border="1" cellpadding="2" cellspacing="2">
+
<tbody>
+
<tr>
+
<th style="background-color: rgb(255, 255, 204); width: 50%;">New</th>
+
<th style="background-color: rgb(204, 255, 255);">Comment</th>
+
</tr>
+
<tr>
+
<td>element perstate</td>
+
<td>Like [item element perstate].</td>
+
</tr>
+
+
</tbody>
</table>
+
<h2>Item Configuration Options</h2>
+
@@ -211,396 +272,520 @@ instead</th> <table style="text-align: left; width: 100%;" border="1" cellpadding="2" cellspacing="2">
+
<tbody>
+
<tr>
+
<th style="background-color: rgb(255, 255, 204); width: 50%;">New</th>
+
<th style="background-color: rgb(204, 255, 255);">Comment</th>
+
</tr>
+
<tr>
+
<td>-height</td>
+
<td>Overrides the treectrl's -itemheight option</td>
+
</tr>
+
+
</tbody>
</table>
+
<h2>Item Command</h2>
+
<table style="text-align: left; width: 100%;" border="1" cellpadding="2" cellspacing="2">
+
<tbody>
+
<tr>
+
<th style="background-color: rgb(255, 255, 204);">Deprecated</th>
+
<th style="background-color: rgb(204, 255, 255);">What to use
instead</th>
+
</tr>
+
<tr>
+
<td>item element actual</td>
+
<td>item element perstate</td>
+
</tr>
+
<tr>
+
<td>item complex</td>
+
<td>item element configure</td>
+
</tr>
+
<tr>
+
<th style="background-color: rgb(255, 255, 204);">Behaviour Changed</th>
+
<th style="background-color: rgb(204, 255, 255);">What changed</th>
+
</tr>
+
<tr>
+
<td>item bbox</td>
+
<td>No longer returns an error if no style had been assigned to the column.</td>
+
</tr>
+
<tr>
+
<td>item state forcolumn</td>
+
<td>No longer returns an error if no style had been assigned to the column.</td>
+
</tr>
+
<tr>
+
<td>item style set</td>
+
<td>Does nothing when replacing a style with the same style.
Previously the old style was freed before assigning the new style,
losing the element config info if the old and new styles were the same.<br>
+
<span style="color: rgb(255, 0, 0);">Potential incompatibility</span></td>
+
</tr>
+
<tr>
+
<th style="background-color: rgb(255, 255, 204); width: 50%;">Arguments/Result
Changed</th>
+
<th style="background-color: rgb(204, 255, 255);">What changed</th>
+
</tr>
+
<tr>
+
<td>item create</td>
+
<td>Added options: -count -height, -nextsibling, -open, -parent,
-prevsibling, and -returnid. Multiple items may be created with one
call using the -count option.</td>
+
</tr>
+
<tr>
+
<td>item element configure</td>
+
<td>Multiple elements in multiple columns may be configured with
a single call. Use '+' to separate elements, and ',' to separate
columns. See the docs.</td>
+
</tr>
+
<tr>
+
<td>item style set</td>
+
<td>When no column is specified, returns a list of one style name
per column. Previously, the list would have less values than the number
of columns if no styles had ever been assigned to the rightmost
column(s).<br>
+
<span style="color: rgb(255, 0, 0);">Potential incompatibility</span></td>
+
</tr>
+
<tr>
+
<td>item text</td>
+
<td>When no column is specified, returns a list of one string per column.</td>
+
</tr>
+
<tr>
+
<th style="background-color: rgb(255, 255, 204); width: 50%;">New</th>
+
<th style="background-color: rgb(204, 255, 255);">Comment</th>
+
</tr>
+
<tr>
+
<td>item image</td>
+
<td>Partner to the [item text] command.</td>
+
</tr>
+
<tr>
+
<td>item element perstate</td>
+
<td>Not really new, just renamed from [item element actual] to
better describe what it does. Accepts a new optional argument which
specifies the state to use when determining the value of the per-state
option.<br>
+
<br>
+
The following options no longer return a default value if the per-state option itself does not have a value specified:<br>
+
+
<ul>
+
<li>bitmap -foreground, -background</li>
+
<li>border -relief</li>
+
<li>text -fill, -font</li>
+
+
</ul>
+
<span style="color: rgb(255, 0, 0);">Potential incompatibility</span></td>
+
</tr>
+
<tr>
+
<td>item span</td>
+
<td>A style may now be displayed over multiple adjacent columns.<br>
+
</td>
+
</tr>
+
+
</tbody>
</table>
+
<h2><span style="font-weight: bold;"></span>Notify Command</h2>
+
<table style="text-align: left; width: 100%;" border="1" cellpadding="2" cellspacing="2">
+
<tbody>
+
<tr>
+
<th style="background-color: rgb(255, 255, 204); width: 50%;">New</th>
+
<th style="background-color: rgb(204, 255, 255);">Comment</th>
+
</tr>
+
<tr>
+
<td>notify unbind<br>
+
</td>
+
<td>Let's you unbind all scripts from an object with one call.</td>
+
</tr>
+
+
</tbody>
</table>
+
<h2>Style Layout Changes</h2>
+
<ul>
+
<li>Column justification will now affect the position of elements in 2 situations which previously had no effect (<span style="color: rgb(255, 0, 0);">Potential incompatibility</span>):</li>
+
</ul>
+
<ol style="margin-left: 40px;">
+
<li>If a -detach element had a fixed width larger than the other elements.</li>
+
<li>If an element had -iexpand x specified as well as -maxwidth, leaving some space available.</li>
+
</ol>
+
<h2>Element Changes</h2>
+
<ul>
+
<li>Bitmap, image and text elements are drawn clipped if given less space than they need.</li>
+
<li>Fixed line wrapping of text elements. It did not work for single lines of text at all (<span style="color: rgb(255, 0, 0);">Potential incompatibility</span>).</li>
+ <li>The text -wrap option can now be <span style="font-weight: bold;">none</span> to disable line wrapping.</li>
+
</ul>
+
<h2>Event Changes</h2>
+
<ul>
+
<li>The new static event <span style="font-weight: bold;"><ItemVisibility></span> is generated when items become visible on screen and when items are no longer visible on screen.
This event allows you to create really big lists by only assigning
styles when items are about to be displayed. See the EVENTS AND SCRIPT
@@ -608,168 +793,210 @@ SUBSTITUTIONS section in the help file, and the new demo "Big List".</li>
+
</ul>
+
<h2>Other Changes</h2>
+
<ul>
+
<li>On WinXP, the column header sort arrow is drawn like Explorer draws it if <span style="font-weight: bold;">-usetheme</span>
is true.</li>
+
</ul>
+
<h2>Demo Changes</h2>
+
<ul>
+
<li>New demo "Big List". Demonstrates the new <span style="font-weight: bold;"><ItemVisibility></span> event, using <Expand-before> to add items on demand, and column spanning.</li>
+
<li>The context menu has a <span style="font-weight: bold;">Span</span> submenu that lets you maninpulate column spanning in items. See the <span style="font-weight: bold;">item span</span> command in the help file.</li>
+
<li>Under WinXP, the "Explorer" demos will use the new <span style="font-weight: bold;">shellicon</span>
extension if available. This extension allows a treectrl to display
file/folder icons using the Win32 Shell API. It may work on other
versions of Windows but it hasn't been tested.</li>
+
</ul>
+
<hr style="width: 100%; height: 2px;">
<h1>What's New in TkTreeCtrl 2.0</h1>
+
<h2>TreeCtrl Configuration Options</h2>
+
<table style="text-align: left; width: 100%;" border="1" cellpadding="2" cellspacing="2">
+
<tbody>
+
<tr>
+
<th style="background-color: rgb(255, 255, 204); width: 50%;">Replaced</th>
+
<th style="background-color: rgb(204, 255, 255);">What to use
instead</th>
+
</tr>
+
<tr>
+
<td>-openbuttonimage</td>
+
<td>-buttonimage</td>
+
</tr>
+
<tr>
+
<td>-closedbuttonimage</td>
+
<td>-buttonimage</td>
+
</tr>
+
<tr>
+
<td>-openbuttonbitmap</td>
+
<td>-buttonbitmap</td>
+
</tr>
+
<tr>
+
<td>-closedbuttonbitmap</td>
+
<td>-buttonbitmap</td>
+
</tr>
+
<tr>
+
<th style="background-color: rgb(255, 255, 204); width: 50%;">Usage
Changed</th>
+
<th style="background-color: rgb(204, 255, 255);">How it changed</th>
+
</tr>
+
<tr>
+
<td>-backgroundmode</td>
+
<td>The values "index" and "visindex" are deprecated. The value
"order" should be used instead of "index", and
"ordervisible" should be used instead of "visindex". This brings
@@ -778,18 +1005,22 @@ index" command.</td> +
</tr>
+
<tr>
+
<td>-treecolumn</td>
+
<td>This used to be any integer value which may or may not have
corresponded to an actual column. Now the value must be a valid column
description, or an empty string to indicate no column should display
@@ -797,122 +1028,153 @@ buttons/lines.</td> +
</tr>
+
<tr>
+
<th style="background-color: rgb(255, 255, 204);">New</th>
+
<td></td>
+
</tr>
+
<tr>
+
<td>-backgroundimage</td>
+
<td></td>
+
</tr>
+
<tr>
+
<td>-columnprefix</td>
+
<td></td>
+
</tr>
+
<tr>
+
<td>-columnresizemode</td>
+
<td></td>
+
</tr>
+
<tr>
+
<td>-itemprefix</td>
+
<td></td>
+
</tr>
+
<tr>
+
<td>-minitemheight</td>
+
<td></td>
+
</tr>
+
<tr>
+
<td>-usetheme</td>
+
<td></td>
+
</tr>
+
+
@@ -921,115 +1183,144 @@ buttons/lines.</td> +
<h2>TreeCtrl Commands</h2>
+
<table style="text-align: left; width: 100%;" border="1" cellpadding="2" cellspacing="2">
+
<tbody>
+
<tr>
+
<th style="width: 50%; background-color: rgb(255, 255, 204);">Deprecated</th>
+
<th style="background-color: rgb(204, 255, 255);">What to use
instead</th>
+
</tr>
+
<tr>
+
<td>compare</td>
+
<td>item compare</td>
+
</tr>
+
<tr>
+
<td>index</td>
+
<td>item id</td>
+
</tr>
+
<tr>
+
<td>numcolumns</td>
+
<td>column count</td>
+
</tr>
+
<tr>
+
<td>numitems</td>
+
<td>item count</td>
+
</tr>
+
<tr>
+
<td>range</td>
+
<td>item range</td>
+
</tr>
+
+
@@ -1038,276 +1329,345 @@ instead</th> +
<h2>Column Configuration Options</h2>
+
<table style="text-align: left; width: 100%;" border="1" cellpadding="2" cellspacing="2">
+
<tbody>
+
<tr>
+
<th style="background-color: rgb(255, 255, 204); width: 50%;">Removed</th>
+
<th style="background-color: rgb(204, 255, 255);">What to use
instead</th>
+
</tr>
+
<tr>
+
<td>-relief<br>
+
</td>
+
<td>-state</td>
+
</tr>
+
<tr>
+
<td>-sunken</td>
+
<td>-state</td>
+
</tr>
+
<tr>
+
<th style="background-color: rgb(255, 255, 204);">Renamed<br>
+
</th>
+
<th style="background-color: rgb(204, 255, 255);">New name</th>
+
</tr>
+
<tr>
+
<td>-arrowpad</td>
+
<td>-arrowpadx</td>
+
</tr>
+
<tr>
+
<th style="background-color: rgb(255, 255, 204);">Usage Changed</th>
+
<th style="background-color: rgb(204, 255, 255);">How it changed</th>
+
</tr>
+
<tr>
+
<td>-background</td>
+
<td>This is now a per-state option. See COLUMNS in the help file
for valid state names.</td>
+
</tr>
+
<tr>
+
<th style="background-color: rgb(255, 255, 204);">New<br>
+
</th>
+
<td></td>
+
</tr>
+
<tr>
+
<td>-arrowbitmap<br>
+
</td>
+
<td></td>
+
</tr>
+
<tr>
+
<td>-arrowimage</td>
+
<td></td>
+
</tr>
+
<tr>
+
<td>-arrowpady</td>
+
<td></td>
+
</tr>
+
<tr>
+
<td>-maxwidth</td>
+
<td></td>
+
</tr>
+
<tr>
+
<td>-resize</td>
+
<td></td>
+
</tr>
+
<tr>
+
<td>-state</td>
+
<td></td>
+
</tr>
+
<tr>
+
<td>-textlines</td>
+
<td></td>
+
</tr>
+
+
@@ -1316,255 +1676,318 @@ for valid state names.</td> +
<h2>Column Command</h2>
+
<table style="text-align: left; width: 100%;" border="1" cellpadding="2" cellspacing="2">
+
<tbody>
+
<tr>
+
<th style="background-color: rgb(255, 255, 204);">Deprecated</th>
+
<th style="background-color: rgb(204, 255, 255);">What to use
instead</th>
+
</tr>
+
<tr>
+
<td>column index</td>
+
<td>column id</td>
+
</tr>
+
<tr>
+
<th style="background-color: rgb(255, 255, 204); width: 50%;">Arguments/Result
Changed</th>
+
<th style="background-color: rgb(204, 255, 255);">What changed</th>
+
</tr>
+
<tr>
+
<td>column configure<br>
+
</td>
+
<td>A column description of "all" is allowed if at least one
option-value pair is given.<br>
+
</td>
+
</tr>
+
<tr>
+
<td>column create</td>
+
<td>The result is a unique identifier. Previously the result was
an
index in the list of columns.</td>
+
</tr>
+
<tr>
+
<td>column delete</td>
+
<td>A column description of "all" is allowed.</td>
+
</tr>
+
<tr>
+
<th style="background-color: rgb(255, 255, 204);">New</th>
+
<th style="background-color: rgb(204, 255, 255);">Comment</th>
+
</tr>
+
<tr>
+
<td>column compare</td>
+
<td></td>
+
</tr>
+
<tr>
+
<td>column count</td>
+
<td>replaces "numcolumns"</td>
+
</tr>
+
<tr>
+
<td>column dragconfigure</td>
+
<td></td>
+
</tr>
+
<tr>
+
<td>column dragcget</td>
+
<td></td>
+
</tr>
+
<tr>
+
<td>column id</td>
+
<td>replaces "column index"</td>
+
</tr>
+
<tr>
+
<td>column list</td>
+
<td></td>
+
</tr>
+
<tr>
+
<td>column order</td>
+
<td></td>
+
</tr>
+
+
@@ -1573,147 +1996,184 @@ index in the list of columns.</td> +
<h2>Item Command</h2>
+
<table style="text-align: left; width: 100%;" border="1" cellpadding="2" cellspacing="2">
+
<tbody>
+
<tr>
+
<th style="background-color: rgb(255, 255, 204);">Removed</th>
+
<th style="background-color: rgb(204, 255, 255);">What to use
instead</th>
+
</tr>
+
<tr>
+
<td>item index</td>
+
<td>item order</td>
+
</tr>
+
<tr>
+
<th style="background-color: rgb(255, 255, 204); width: 50%;">New</th>
+
<th style="background-color: rgb(204, 255, 255);">Comment</th>
+
</tr>
+
<tr>
+
<td>item compare</td>
+
<td>replaces "compare"</td>
+
</tr>
+
<tr>
+
<td>item count</td>
+
<td>replaces "numitems"</td>
+
</tr>
+
<tr>
+
<td>item id</td>
+
<td>replaces "index"</td>
+
</tr>
+
<tr>
+
<td>item order</td>
+
<td>replaces "item index"</td>
+
</tr>
+
<tr>
+
<td>item range</td>
+
<td>replaces "range"</td>
+
</tr>
+
+
@@ -1722,68 +2182,85 @@ instead</th> +
<h2>Notify Command</h2>
+
<table style="text-align: left; width: 100%;" border="1" cellpadding="2" cellspacing="2">
+
<tbody>
+
<tr>
+
<th style="background-color: rgb(255, 255, 204); width: 50%;">Arguments/Result
Changed</th>
+
<th style="background-color: rgb(204, 255, 255);">What changed</th>
+
</tr>
+
<tr>
+
<td>notify generate<br>
+
</td>
+
<td>Added optional <span style="font-style: italic;">percentsCommand</span>
argument</td>
+
</tr>
+
<tr>
+
<td>notify install</td>
+
<td>Old syntax (supported but deprecated):<br>
+
+
@@ -1791,6 +2268,8 @@ argument</td> +
+
@@ -1798,10 +2277,13 @@ argument</td> +
New syntax:<br>
+
+
@@ -1809,6 +2291,8 @@ New syntax:<br> +
+
@@ -1816,26 +2300,33 @@ New syntax:<br> +
</td>
+
</tr>
+
<tr>
+
<td>notify linkage</td>
+
<td>Old syntax (supported but deprecated):<br>
+
+
@@ -1843,10 +2334,13 @@ New syntax:<br> +
<pre><span style="font-weight: bold;">notify linkage</span> <span style="font-style: italic;">eventName</span></pre>
+
+
@@ -1854,14 +2348,18 @@ New syntax:<br> +
</div>
+
New syntax:<br>
+
+
@@ -1869,10 +2367,13 @@ New syntax:<br> +
<pre><span style="font-weight: bold;">notify linkage</span> <<span style="font-style: italic;">eventName</span>></pre>
+
+
@@ -1880,35 +2381,44 @@ New syntax:<br> +
</div>
+
</td>
+
</tr>
+
<tr>
+
<td>notify uninstall</td>
+
<td>see <span style="font-weight: bold;">notify install</span>
above</td>
+
</tr>
+
+
@@ -1917,42 +2427,52 @@ above</td> +
<h2>Style Layout Options</h2>
+
<table style="text-align: left; width: 100%;" border="1" cellpadding="2" cellspacing="2">
+
<tbody>
+
<tr>
+
<th style="background-color: rgb(255, 255, 204);">Usage Changed</th>
+
<th style="background-color: rgb(204, 255, 255);">How it changed</th>
+
</tr>
+
<tr>
+
<td>-iexpand</td>
+
<td>Two new flags "x' and "y" are allowed. Previously, only the
-ipadx and -ipady padding could be expanded by this option. The new xy
flags expand the display area of the element, not the padding. To
@@ -1960,6 +2480,8 @@ update your code, you will probably want to change this:<br> +
+
@@ -1967,18 +2489,23 @@ update your code, you will probably want to change this:<br> +
<pre>$T style layout $S $E -iexpand we</pre>
+
</div>
+
to this:<br>
+
+
@@ -1986,156 +2513,195 @@ to this:<br> +
<pre>$T style layout $S $E -iexpand x<br></pre>
+
</div>
+
Keep in mind that -union elements are not affected by -iexpand xy,
since the size of a -union element is determined by the elements it
surrounds.</td>
+
</tr>
+
<tr>
+
<th style="width: 50%; background-color: rgb(255, 255, 204);">New<br>
+
</th>
+
<td></td>
+
</tr>
+
<tr>
+
<td>-height</td>
+
<td></td>
+
</tr>
+
<tr>
+
<td>-maxheight</td>
+
<td></td>
+
</tr>
+
<tr>
+
<td>-maxwidth</td>
+
<td></td>
+
</tr>
+
<tr>
+
<td>-minheight</td>
+
<td></td>
+
</tr>
+
<tr>
+
<td>-minwidth</td>
+
<td></td>
+
</tr>
+
<tr>
+
<td>-sticky</td>
+
<td></td>
+
</tr>
+
<tr>
+
<td>-width</td>
+
<td></td>
+
</tr>
+
+
@@ -2144,14 +2710,17 @@ surrounds.</td> +
<h2>Element Changes</h2>
+
<ul>
+
<li>A new element type <span style="font-weight: bold;">window</span>
was added.
See the new demo "Firefox Privacy" and the ELEMENTS section in the help
@@ -2159,11 +2728,13 @@ file.</li> +
<li>All element types have a new
per-state boolean option called <span style="font-weight: bold;">-draw</span>.</li>
+
<li>The <span style="font-weight: bold;">text</span> element type
has a new option called <span style="font-weight: bold;">-textvariable</span>.
See the new demo
@@ -2171,18 +2742,22 @@ See the new demo +
</ul>
+
<h2>Event Changes</h2>
+
<ul>
+
<li>2 new %-substitution characters <span style="font-weight: bold;">%P</span>
and <span style="font-weight: bold;">%?</span> are allowed in binding
scripts. See the EVENTS AND SCRIPT SUBSTITUTIONS section in the help
@@ -2190,82 +2765,99 @@ file.</li> +
<li>The new static event <span style="font-weight: bold;"><ItemDelete></span>
is generated when items are deleted. See the EVENTS AND SCRIPT
SUBSTITUTIONS section in the help file.</li>
+
</ul>
+
<h2>Library Script Changes</h2>
+
<h3 style="margin-left: 40px;">filelist-bindings.tcl:</h3>
+
<ul>
+
<li>The Priv(edit) variable, which is used to specify which text
elements may be edited, now has the same format as Priv(sensitive).
Previously only elements in the first column could be edited.</li>
+
<li>3 new commands in the TreeCtrl namespace should be used to access
the Priv(dragimage), Priv(edit) and Priv(sensitive) variables. The
commands are SetDragImage, SetEditable and SetSensitive.</li>
+
<li>Two new dynamic events <span style="font-weight: bold;"><Edit-begin></span>
and <span style="font-weight: bold;"><Edit-end></span> are
generated when editing a file name.</li>
+
</ul>
+
<h3 style="margin-left: 40px;">treectrl.tcl:</h3>
+
<ul>
+
<li>On OSX/Aqua, the Command key is used to perform discontinuous
selection. Previously the Control key was used but Command is specified
by Apple's user-interface guidelines.</li>
+
</ul>
+
<h2>Other Changes</h2>
+
<ul>
+
<li>On WinXP, the column headers and open/close buttons are drawn
using the system theme if <span style="font-weight: bold;">-usetheme</span>
is true. The sort arrow is drawn the old-fashioned way.</li>
+
<li>On OSX/Aqua, the column headers and open/close buttons are
drawn
using the system theme if <span style="font-weight: bold;">-usetheme</span>
@@ -2275,35 +2867,42 @@ and <span style="font-weight: bold;">-arrowgravity</span> options.</li> +
<li>Columns can be moved by drag-and-drop. See <span style="font-weight: bold;">column dragconfigure</span> in the help
file.</li>
+
<li>Columns can be specified in new ways. See the COLUMN DESCRIPTION
section in the help file.</li>
+
<li>Added new section DYNAMIC EVENTS to the help file.</li>
+
<li>Added new section PER-STATE OPTIONS to the help file.</li>
+
<li>The new style layout option <span style="font-weight: bold;">-indent</span>
allows elements to be displayed in the button/line area. See the <span style="font-weight: bold;">style layout</span> command in the help
file and the new demo "Firefox Privacy".</li>
+
<li>The new item description <span style="font-weight: bold;">end</span>
is equivalent to <span style="font-weight: bold;">last</span>.</li>
+
<li><span style="color: rgb(255, 0, 0);">If you have version 1.1
installed, replace the old pkgIndex.tcl file with the one from this
version (but replace the version number 2.0 with 1.1).<span style="color: rgb(0, 0, 0);"> Otherwise the old pkgIndex.tcl file will
@@ -2312,44 +2911,54 @@ scripts are found.</span></span></li> +
</ul>
+
<h2>Demo Changes</h2>
+
<ul>
+
<li>New demo "Firefox Privacy". Demonstrates the new <span style="font-weight: bold;">window</span> element type and <span style="font-weight: bold;">-indent</span> style layout option.</li>
+
<li>New demo "Textvariable". Demonstrates the new <span style="font-weight: bold;">-textvariable</span> option of the <span style="font-weight: bold;">text</span> element.</li>
+
<li>Added a new Event Browser window to display events generated by
the main treectrl widget.</li>
+
<li>The context menu can be popped up in all the demo lists. A
<Control-ButtonPress-1> binding for this was added under OSX/Aqua.</li>
+
<li>In the "Explorer" demos, the file name is hidden while editing
the file name.</li>
+
</ul>
+
</body>
</html>
diff --git a/doc/treectrl.html b/doc/treectrl.html index c89a604..bfaf0cb 100644 --- a/doc/treectrl.html +++ b/doc/treectrl.html @@ -1,14 +1,14 @@ -<! -- Copyright (c) 2002-2003 Christian Krone. -- -- See the file "license.terms" for information on usage and redistribution -- of this file, and for a DISCLAIMER OF ALL WARRANTIES. -- -- $Id: treectrl.html,v 1.29 2005/07/15 01:39:19 treectrl Exp $ +<! -- Copyright (c) 2002-2003 Christian Krone. -- -- See the file "license.terms" for information on usage and redistribution -- of this file, and for a DISCLAIMER OF ALL WARRANTIES. -- -- $Id: treectrl.html,v 1.30 2005/07/23 00:35:20 treectrl Exp $ --><html><head> <title>treectrl - Tk Commands </title> </head> <! -- Generated from file 'doc/treectrl.man' by tcllib/doctools with format 'html' --> -<! -- CVS: $Id: treectrl.html,v 1.29 2005/07/15 01:39:19 treectrl Exp $ treectrl.n +<! -- CVS: $Id: treectrl.html,v 1.30 2005/07/23 00:35:20 treectrl Exp $ treectrl.n --> <body> -<h1> treectrl(n) 2.0 treectrl "Tk Commands"</h1> +<h1> treectrl(n) 2.1 treectrl "Tk Commands"</h1> <h2><a name="name">NAME</a></h2> <p> <p> treectrl - Create and manipulate hierarchical multicolumn widgets @@ -43,7 +43,7 @@ <a href="#keywords">KEYWORDS</a><br> <h2><a name="synopsis">SYNOPSIS</a></h2> <p> -package require <b>treectrl 2.0</b><br> +package require <b>treectrl 2.1</b><br> <br><table border=1 width=100% cellspacing=0 cellpadding=0><tr bgcolor=lightyellow><td bgcolor=lightyellow><table 0 width=100% cellspacing=0 cellpadding=0><tr valign=top ><td ><a href="#1"><b class='cmd'>treectrl</b> <i class='arg'>pathName</i> ?<i class='arg'>options</i>?</a></td></tr> <tr valign=top ><td ><a href="#2"><i class='arg'>pathName</i> <b class='cmd'>activate</b> <i class='arg'>itemDesc</i></a></td></tr> <tr valign=top ><td ><a href="#3"><i class='arg'>pathName</i> <b class='cmd'>canvasx</b> <i class='arg'>screenx</i></a></td></tr> @@ -131,7 +131,7 @@ package require <b>treectrl 2.0</b><br> <tr valign=top ><td ><a href="#85"><i class='arg'>pathName</i> <b class='cmd'>item state</b> <i class='arg'>command</i> <i class='arg'>itemDesc</i> ?<i class='arg'>arg ...</i>?</a></td></tr> <tr valign=top ><td ><a href="#86"><i class='arg'>pathName</i> <b class='cmd'>item state forcolumn</b> <i class='arg'>itemDesc</i> <i class='arg'>column</i> ?<i class='arg'>stateDescList</i>?</a></td></tr> <tr valign=top ><td ><a href="#87"><i class='arg'>pathName</i> <b class='cmd'>item state get</b> <i class='arg'>itemDesc</i> ?<i class='arg'>stateName</i>?</a></td></tr> -<tr valign=top ><td ><a href="#88"><i class='arg'>pathName</i> <b class='cmd'>item state set</b> <i class='arg'>itemDesc</i> ?<i class='arg'>lastItem</i>? ?<i class='arg'>stateDescList</i>?</a></td></tr> +<tr valign=top ><td ><a href="#88"><i class='arg'>pathName</i> <b class='cmd'>item state set</b> <i class='arg'>itemDesc</i> ?<i class='arg'>lastItem</i>? <i class='arg'>stateDescList</i></a></td></tr> <tr valign=top ><td ><a href="#89"><i class='arg'>pathName</i> <b class='cmd'>item style</b> <i class='arg'>command</i> <i class='arg'>itemDesc</i> ?<i class='arg'>arg ...</i>?</a></td></tr> <tr valign=top ><td ><a href="#90"><i class='arg'>pathName</i> <b class='cmd'>item style elements</b> <i class='arg'>itemDesc</i> <i class='arg'>column</i></a></td></tr> <tr valign=top ><td ><a href="#91"><i class='arg'>pathName</i> <b class='cmd'>item style map</b> <i class='arg'>itemDesc</i> <i class='arg'>column</i> <i class='arg'>style</i> <i class='arg'>map</i></a></td></tr> @@ -407,7 +407,7 @@ Database Class: <strong>Height</strong><br> <dd> Specifies the desired height for the window in any of the forms acceptable to <strong>Tk_GetPixels</strong>. -The default is 200 pixel. +The default is 200 pixels. If this option is less than or equal to zero then the window will not request any size at all. @@ -451,14 +451,9 @@ Database Name: <strong>itemWidth</strong><br> Database Class: <strong>ItemWidth</strong><br> <dd> Specifies a fixed width for every item in any of the forms acceptable to <strong>Tk_GetPixels</strong>. -This option only has an effect when either of these sets of conditions are met: -a) the treectrl's -orient option is vertical, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -wrap option causes a 2-dimension arrangement of items, or -b) the treectrl's -orient option is horizontal, and -only a single column is visible, and -the visible column's -width option is "". +If more than one column is visible, then this option has no effect. +If the -orient option is vertical, and the -wrap option is unspecified, then this +option has no effect (in that case all items are as wide as the column). <br><br> <dt>Command-Line Switch: <strong>-itemwidthequal</strong><br> @@ -466,16 +461,10 @@ Database Name: <strong>itemWidthEqual</strong><br> Database Class: <strong>ItemWidthEqual</strong><br> <dd> Specifies a boolean that says whether all items should have the same width. -This option only has an effect when either of these sets of conditions are met: -a) the treectrl's -orient option is vertical, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -wrap option causes a 2-dimension arrangement of items, and -the treectrl's -itemwidth option is <= 0, or -b) the treectrl's -orient option is horizontal, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -itemwidth option is <= 0. +If more than one column is visible, then this option has no effect. +If the -orient option is vertical, and the -wrap option is unspecified, then this +option has no effect (in that case all items are as wide as the column). +If the -itemwidth option is specified, then this option has no effect. <br><br> <dt>Command-Line Switch: <strong>-itemwidthmultiple</strong><br> @@ -483,16 +472,10 @@ Database Name: <strong>itemWidthMultiple</strong><br> Database Class: <strong>ItemWidthMultiple</strong><br> <dd> Specifies a screen distance that every item's width will be evenly divisible by in any of the forms acceptable to <strong>Tk_GetPixels</strong>. -This option only has an effect when either of these sets of conditions are met: -a) the treectrl's -orient option is vertical, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -wrap option causes a 2-dimension arrangement of items, and -the treectrl's -itemwidth option is <= 0, or -b) the treectrl's -orient option is horizontal, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -itemwidth option is <= 0. +If more than one column is visible, then this option has no effect. +If the -orient option is vertical, and the -wrap option is unspecified, then this +option has no effect (in that case all items are as wide as the column). +If the -itemwidth option is specified, then this option has no effect. <br><br> <dt>Command-Line Switch: <strong>-linecolor</strong><br> @@ -614,9 +597,9 @@ The default value is true. Database Name: <strong>treeColumn</strong><br> Database Class: <strong>TreeColumn</strong><br> <dd> -Specifies an integer value that determines which -column displays the data in an hierarchical fashion. -Default is 0 meaning that the first column displays the tree. +Specifies a <a href="#column_description">column description</a> that determines which +column displays the buttons and lines. +The default is unspecified. <br><br> <dt>Command-Line Switch: <strong>-usetheme</strong><br> @@ -643,18 +626,22 @@ not request any size at all. Database Name: <strong>wrap</strong><br> Database Class: <strong>Wrap</strong><br> <dd> -Specifies how to arrange items inside treectrl's window. -The value must be an empty string, <strong>window</strong>, -or a list with an integer as first element -and either <strong>items</strong> or <strong>pixels</strong> as second element. -The empty string as wrap mode means that each item appears on -exactly one line on the screen. -In the other modes multiple items may be displayed in one screen line. -In <strong>window</strong> mode a screen line break may occur after any element; -in <strong>items</strong> mode a line break will only be made after the specified -number of items; -in <strong>pixels</strong> mode a line break will only be made after the -specified screen distance is reached. +Specifies whether items are arranged in a 1- or 2-dimensional layout. + +If the value is an empty string (the default), then items are arranged from top +to bottom (-orient vertical) or from left to right (-orient horizontal) in +a 1-dimensional layout. + +If the value is "<em>N</em> <strong>items</strong>", then a no more than <em>N</em> items will appear in +a vertical group (-orient vertical) or horizontal group (-orient horizontal). + +If the value is "<em>N</em> <strong>pixels</strong>", then a no vertical group of items will be +taller than <em>N</em> pixels (-orient vertical) or no horizontal group of items will +be wider than <em>N</em> pixels (-orient horizontal). + +If the value is <strong>window</strong>, then a no vertical group of items will be +taller than the window (-orient vertical) or no horizontal group of items will +be wider than the window (-orient horizontal). <br><br> <dt>Command-Line Switch: <strong>-xscrolldelay</strong><br> @@ -780,10 +767,10 @@ The following forms of the command are supported: <dl> <dt><a name="8"><i class='arg'>pathName</i> <b class='cmd'>column bbox</b> <i class='arg'>column</i></a><dd> -Returns a list with four elements giving an approximate bounding box +Returns a list with four elements giving the bounding box for the column header specified by <i class='arg'>column</i>. -If the treectrl is configured to don't display the column headers -by means of the <strong>-showheader</strong> option, +If the treectrl is configured not to display the column headers +by means of the <strong>-showheader</strong> option, then an empty list is returned instead. <br><br> @@ -980,10 +967,10 @@ command. <br><br> <dt><a name="26"><i class='arg'>pathName</i> <b class='cmd'>contentbox</b></a><dd> -Returns a list with four elements giving an approximate bounding box -for the space used to display the items inside the columns, -i.e. the space of the treectrl widget without -the surrounding borders and the column headers. +Returns a list with four elements giving the bounding box +for the space used to display the items, +i.e. the space of the treectrl window without +the surrounding borders or the column headers. <br><br> <dt><a name="27"><i class='arg'>pathName</i> <b class='cmd'>debug</b> <i class='arg'>option</i> ?<i class='arg'>arg arg ...</i>?</a><dd> @@ -1062,7 +1049,7 @@ debugging options <strong>-enable</strong> and <strong>-display</strong> are swi <dt><a name="30"><i class='arg'>pathName</i> <b class='cmd'>debug dinfo</b></a><dd> For every of the treectrl widget -a line with some internal valuess info about all items +a line with some internal values info about all items is printed to stdout. The command returns the empty string. @@ -1288,14 +1275,15 @@ The following forms of the command are supported: <dl> <dt><a name="51"><i class='arg'>pathName</i> <b class='cmd'>item ancestors</b> <i class='arg'>itemDesc</i></a><dd> -Returns a list containing the numerical indexes of all ancestors -of the item specified by <i class='arg'>itemDesc</i> from its parent up to the -root item. +Returns a list containing the item ids of the ancestors +of the item specified by <i class='arg'>itemDesc</i>. The first list value is the parent, +the second is the parent's parent, an so on. The last list value will be the +root item if <i class='arg'>itemDesc</i> is a descendant of the root item. <br><br> <dt><a name="52"><i class='arg'>pathName</i> <b class='cmd'>item bbox</b> <i class='arg'>itemDesc</i> ?<i class='arg'>column</i>? ?<i class='arg'>element</i>?</a><dd> -Returns a list with four elements giving an approximate bounding box +Returns a list with four elements giving the bounding box for the item described by <i class='arg'>itemDesc</i>. If no further argument is specified, the bbox spans the area of the item over all columns. If a <i class='arg'>column</i> is specified, only the area of the item @@ -1313,7 +1301,7 @@ values accepted by the <b class='cmd'>item configure</b> command. <br><br> <dt><a name="54"><i class='arg'>pathName</i> <b class='cmd'>item children</b> <i class='arg'>itemDesc</i></a><dd> -Returns a list containing the numerical indexes of all children +Returns a list containing the item ids of all children of the item specified by <i class='arg'>itemDesc</i> in the correct order from the first child to the last child. @@ -1463,9 +1451,10 @@ and b) each ancestor's <strong>-visible</strong> option is true <dt><a name="61"><i class='arg'>pathName</i> <b class='cmd'>item delete</b> <i class='arg'>first</i> ?<i class='arg'>last</i>?</a><dd> Deletes the specified item(s). -<i class='arg'>First</i> and <i class='arg'>last</i> must be the string <strong>all</strong> or an <i class='arg'>itemDesc</i>. -If either <i class='arg'>first</i> or <i class='arg'>last</i> is specified as <strong>all</strong>, all items are -deleted; if <i class='arg'>first</i> is specified as <i class='arg'>itemDesc</i> and <i class='arg'>last</i> isn't +<i class='arg'>First</i> and <i class='arg'>last</i> must be the string <strong>all</strong> or a valid +<a href="#item_description">item description</a>. +If either <i class='arg'>first</i> or <i class='arg'>last</i> is specified as <strong>all</strong>, then all items are +deleted. If <i class='arg'>first</i> is specified and <i class='arg'>last</i> isn't specified, the item described by <i class='arg'>first</i> is deleted. If both <i class='arg'>first</i> and <i class='arg'>last</i> are specified, they must decribe items with a common ancestor; @@ -1476,6 +1465,12 @@ If the current <strong>active</strong> item is deleted, the root item becomes th If the current selection <strong>anchor</strong> item is deleted, the root item becomes the new anchor item. There is no way to delete the root item of the treectrl widget; in all cases the specification of the root item is ignored. +<br><br> +For each call to this command, two events may be generated. +If any of the deleted items are selected, then a <strong><Selection></strong> event +is generated just before the items are deleted. +If any items were actually deleted, then an <strong><ItemDelete></strong> event event is generated just before the items +are deleted. <br><br> <dt><a name="62"><i class='arg'>pathName</i> <b class='cmd'>item dump</b> <i class='arg'>itemDesc</i></a><dd> @@ -1570,7 +1565,7 @@ and an <strong><Expand-after></strong> event after the item state was chan <br><br> <dt><a name="69"><i class='arg'>pathName</i> <b class='cmd'>item firstchild</b> <i class='arg'>parent</i> ?<i class='arg'>child</i>?</a><dd> -If <i class='arg'>child</i> is not specified, returns the numerical index of the first +If <i class='arg'>child</i> is not specified, returns the item id of the first child of the item described by <i class='arg'>parent</i>. If <i class='arg'>child</i> is specified, it must described an item that is not an ancestor of <i class='arg'>parent</i>. @@ -1579,8 +1574,8 @@ Then it will become the new first child of <i class='arg'>parent</i>. <br><br> <dt><a name="70"><i class='arg'>pathName</i> <b class='cmd'>item id</b> <i class='arg'>itemDesc</i></a><dd> -This command resolves the item description <i class='arg'>itemDesc</i> into a unique item -identifier (see <a href="#item_description">ITEM DESCRIPTION</a> below). If the item described by +This command resolves the <a href="#item_description">item description</a> <i class='arg'>itemDesc</i> into a unique item +identifier. If the item described by <i class='arg'>itemDesc</i> doesn't exist, this command returns an empty string. <br><br> @@ -1610,24 +1605,24 @@ parent of the item decribed by <i class='arg'>descendant</i>, 0 otherwise. <br><br> <dt><a name="73"><i class='arg'>pathName</i> <b class='cmd'>item isopen</b> <i class='arg'>itemDesc</i></a><dd> -Returns 1, if the item described by <i class='arg'>itemDesc</i> has cuurently the +Returns 1 if the item described by <i class='arg'>itemDesc</i> has the state <strong>open</strong> switched on, 0 otherwise. <br><br> <dt><a name="74"><i class='arg'>pathName</i> <b class='cmd'>item lastchild</b> <i class='arg'>parent</i> ?<i class='arg'>child</i>?</a><dd> -If <i class='arg'>child</i> is not specified, returns the numerical index of the last +If <i class='arg'>child</i> is not specified, returns the item id of the last child of the item described by <i class='arg'>parent</i>. -If <i class='arg'>child</i> is specified, it must described an item +If <i class='arg'>child</i> is specified, it must describe an item that is not an ancestor of <i class='arg'>parent</i>. Then it will become the new last child of <i class='arg'>parent</i>. <br><br> <dt><a name="75"><i class='arg'>pathName</i> <b class='cmd'>item nextsibling</b> <i class='arg'>sibling</i> ?<i class='arg'>next</i>?</a><dd> -If <i class='arg'>next</i> is not specified, returns the numerical index of the next +If <i class='arg'>next</i> is not specified, returns the item id of the next sibling of the item described by <i class='arg'>sibling</i>. -If <i class='arg'>next</i> is specified, it must described an item +If <i class='arg'>next</i> is specified, it must describe an item that is not an ancestor of <i class='arg'>sibling</i>. Then it will become the new next sibling of <i class='arg'>sibling</i>. @@ -1650,25 +1645,26 @@ is not visible. <br><br> <dt><a name="78"><i class='arg'>pathName</i> <b class='cmd'>item parent</b> <i class='arg'>itemDesc</i></a><dd> -Returns the numerical index of the parent of the item +Returns the item id of the parent of the item described by <i class='arg'>itemDesc</i>. <br><br> <dt><a name="79"><i class='arg'>pathName</i> <b class='cmd'>item prevsibling</b> <i class='arg'>sibling</i> ?<i class='arg'>prev</i>?</a><dd> -If <i class='arg'>prev</i> is not specified, returns the numerical index of the previous +If <i class='arg'>prev</i> is not specified, returns the item id of the previous sibling of the item described by <i class='arg'>sibling</i>. -If <i class='arg'>prev</i> is specified, it must described an item +If <i class='arg'>prev</i> is specified, it must describe an item that is not an ancestor of <i class='arg'>sibling</i>. Then it will become the new previous sibling of <i class='arg'>sibling</i>. <br><br> <dt><a name="80"><i class='arg'>pathName</i> <b class='cmd'>item range</b> <i class='arg'>first</i> <i class='arg'>last</i></a><dd> -Returns a list containing the unique identifiers of all items +Returns a list containing the item ids of all items in the range between <i class='arg'>first</i> and <i class='arg'>last</i>, inclusive. The order between <i class='arg'>first</i> and <i class='arg'>last</i> doesn't matter, -and the result is always ordered by the increasing index of the items. +and the result is always sorted by the increasing order of the items (as +returned by the <b class='cmd'>item order</b> command). The items specified by <i class='arg'>first</i> and <i class='arg'>last</i> must share a common ancestor. @@ -1676,13 +1672,15 @@ ancestor. <dt><a name="81"><i class='arg'>pathName</i> <b class='cmd'>item remove</b> <i class='arg'>itemDesc</i></a><dd> Removes the item described by <i class='arg'>itemDesc</i> -from the children list of its father, so that it will become an orphan. +from the list of children of its parent, so that it will become an orphan. <br><br> <dt><a name="82"><i class='arg'>pathName</i> <b class='cmd'>item rnc</b> <i class='arg'>itemDesc</i></a><dd> Returns a list of two integers, which corresponds to the row and column -of the item described by <i class='arg'>itemDesc</i>. +of the item described by <i class='arg'>itemDesc</i>. The row and column corresponds to +the on-screen arrangement of items as determined by the -orient and -wrap +options. If the item is not displayed, this command returns an empty string. <br><br> <dt><a name="83"><i class='arg'>pathName</i> <b class='cmd'>item sort</b> <i class='arg'>itemDesc</i> ?<i class='arg'>option ...</i>?</a><dd> @@ -1777,32 +1775,34 @@ The following forms of the command are supported: <dt><a name="86"><i class='arg'>pathName</i> <b class='cmd'>item state forcolumn</b> <i class='arg'>itemDesc</i> <i class='arg'>column</i> ?<i class='arg'>stateDescList</i>?</a><dd> -Just like <b class='cmd'>item state set</b> but manipulates user-defined states for a single -item column, not the item as a whole. +Just like <b class='cmd'>item state set</b> but manipulates dynamic states for a single +item column, not the item as a whole. If <i class='arg'>stateDescList</i> is unspecified, +this command returns a list containing the names of all the dynamic states +which are switched on in <i class='arg'>column</i>. <br><br> <dt><a name="87"><i class='arg'>pathName</i> <b class='cmd'>item state get</b> <i class='arg'>itemDesc</i> ?<i class='arg'>stateName</i>?</a><dd> If no <i class='arg'>stateName</i> is specified, returns a list containing -the names of all (predefined and user defined) states +the names of all (static and dynamic) states which are currently switched on for the item described by <i class='arg'>itemDesc</i>. If a <i class='arg'>stateName</i> is specified, 1 is returned if the specified state is currently switched on for the item, 0 otherwise. <br><br> -<dt><a name="88"><i class='arg'>pathName</i> <b class='cmd'>item state set</b> <i class='arg'>itemDesc</i> ?<i class='arg'>lastItem</i>? ?<i class='arg'>stateDescList</i>?</a><dd> +<dt><a name="88"><i class='arg'>pathName</i> <b class='cmd'>item state set</b> <i class='arg'>itemDesc</i> ?<i class='arg'>lastItem</i>? <i class='arg'>stateDescList</i></a><dd> Every element of <i class='arg'>stateDescList</i> -must describe a user defined state (see <a href="#states">STATES</a> below), -with the particularity that the state name may have also a leading <strong>~</strong>. +must be the name of a dynamic state (see <a href="#states">STATES</a> below), +optionally preceded by a <strong>~</strong> or <strong>!</strong> character. Every state with a leading <strong>!</strong> will be switched off for the item described by <i class='arg'>itemDesc</i>, every state with a leading <strong>~</strong> will be toggled, and every state without leading <strong>!</strong> or <strong>~</strong> will be switched on. If <i class='arg'>lastItem</i> is specified, the state changes will be made for all items in the range betwen <i class='arg'>itemDesc</i> and <i class='arg'>lastItem</i>. -<i class='arg'>ItemDesc</i> may be the string <strong>all</strong>, +If <i class='arg'>ItemDesc</i> is the string <strong>all</strong>, then the state changes are made for all items of the treectrl widget. </dl> @@ -1818,9 +1818,10 @@ The following forms of the command are supported: <dl> <dt><a name="90"><i class='arg'>pathName</i> <b class='cmd'>item style elements</b> <i class='arg'>itemDesc</i> <i class='arg'>column</i></a><dd> -A list is returned -containing the currently defined elements of the style, -which is set for the item described by <i class='arg'>itemDesc</i> in <i class='arg'>column</i>. +This command returns a list containing the names of elements which were +configured by the <b class='cmd'>item element configure</b> command for the item +described by <i class='arg'>itemDesc</i> in <i class='arg'>column</i>. If there is no style assigned +to <i class='arg'>column</i> an error is returned. <br><br> <dt><a name="91"><i class='arg'>pathName</i> <b class='cmd'>item style map</b> <i class='arg'>itemDesc</i> <i class='arg'>column</i> <i class='arg'>style</i> <i class='arg'>map</i></a><dd> @@ -2186,11 +2187,11 @@ Deprecated. Use the <b class='cmd'>item count</b> command instead. <br><br> <dt><a name="119"><i class='arg'>pathName</i> <b class='cmd'>orphans</b></a><dd> -Returns a list containing the numerical ids of all items -which has no parent item. -An item is created without having a parent, -and can later become an orphan again -by means of the <b class='cmd'>item remove</b> widget command. +Returns a list containing the item ids of all items +which have no parent. +When an item is created, it has no parent by default, +and can later become an orphan +by means of the <b class='cmd'>item remove</b> widget command. The root item is not returned. <br><br> <dt><a name="120"><i class='arg'>pathName</i> <b class='cmd'>range</b> <i class='arg'>first</i> <i class='arg'>last</i></a><dd> @@ -2200,7 +2201,7 @@ Deprecated. Use the <b class='cmd'>item range</b> command instead. <br><br> <dt><a name="121"><i class='arg'>pathName</i> <b class='cmd'>state</b> <i class='arg'>option</i> ?<i class='arg'>stateName</i>?</a><dd> -This command is used to manipulate the list of user defined states, +This command is used to manipulate the list of user-defined states, see section <a href="#states">STATES</a> below. The exact behavior of the command depends on the <i class='arg'>option</i> argument that follows the <b class='cmd'>state</b> argument. @@ -2211,26 +2212,26 @@ The following forms of the command are supported: <dt><a name="122"><i class='arg'>pathName</i> <b class='cmd'>state define</b> <i class='arg'>stateName</i></a><dd> Defines a new state with the name <i class='arg'>stateName</i>, -which must not be the name of a predefined or already user defined state. +which must not be the name of an existing state. <br><br> <dt><a name="123"><i class='arg'>pathName</i> <b class='cmd'>state linkage</b> <i class='arg'>stateName</i></a><dd> Returns a string indicating -whether the specified state is user defined +whether the specified state is user-defined by means of the <b class='cmd'>state define</b> widget command (<strong>dynamic</strong>) or predefined by the treectrl widget itself (<strong>static</strong>). <br><br> <dt><a name="124"><i class='arg'>pathName</i> <b class='cmd'>state names</b></a><dd> -Returns a list containing the names of all user defined states. +Returns a list containing the names of all user-defined states. <br><br> <dt><a name="125"><i class='arg'>pathName</i> <b class='cmd'>state undefine</b> ?<i class='arg'>stateName ...</i>?</a><dd> -Every <i class='arg'>stateName</i> must be the name of a user defined state. -Removes this state from the list of user defined states. +Every <i class='arg'>stateName</i> must be the name of a user-defined state. +Removes this state from the list of user-defined states. </dl> <dt><a name="126"><i class='arg'>pathName</i> <b class='cmd'>see</b> <i class='arg'>itemDesc</i></a><dd> @@ -2253,13 +2254,14 @@ It has several forms, depending on <i class='arg'>option</i>: <dt><a name="128"><i class='arg'>pathName</i> <b class='cmd'>selection add</b> <i class='arg'>first</i> ?<i class='arg'>last</i>?</a><dd> <i class='arg'>First</i> and <i class='arg'>last</i> (if specified) -must be the string <strong>all</strong> or an <i class='arg'>itemDesc</i>. -Selects all of the items in the range between -<i class='arg'>first</i> and <i class='arg'>last</i>, inclusive, +must be the string <strong>all</strong> or a valid <a href="#item_description">item description</a>. +Adds every unselected item in the range between +<i class='arg'>first</i> and <i class='arg'>last</i>, inclusive, to the selection without affecting the selection state of items outside that range. If one of the arguments is the string <strong>all</strong>, -all items of the treectrl widget are added to the selection instead. -A <strong><Selection></strong> event is generated. +every unselected item in the treectrl widget is added to the selection. +A <strong><Selection></strong> event is generated if any items were added to the +selection. <br><br> <dt><a name="129"><i class='arg'>pathName</i> <b class='cmd'>selection anchor</b> ?<i class='arg'>itemDesc</i>?</a><dd> @@ -2276,14 +2278,15 @@ Returns the numerical id of the selection anchor item. <dt><a name="130"><i class='arg'>pathName</i> <b class='cmd'>selection clear</b> ?<i class='arg'>first</i>? ?<i class='arg'>last</i>?</a><dd> <i class='arg'>First</i> and <i class='arg'>last</i> (if specified) -must be the string <strong>all</strong> or an <i class='arg'>itemDesc</i>. +must be the string <strong>all</strong> or a valid <a href="#item_description">item description</a>. If any of the items between <i class='arg'>first</i> and <i class='arg'>last</i> (inclusive) are selected, they are deselected. The selection state is not changed for items outside this range. -If no additional arguments is given -or one of the arguments is the string <strong>all</strong>, -the selection is completely cleared instead. -A <strong><Selection></strong> event is generated. +If no additional arguments are given, +or if one of the arguments is the string <strong>all</strong>, +then all items are removed from the selection. +A <strong><Selection></strong> event is generated if any items were removed from the +selection. <br><br> <dt><a name="131"><i class='arg'>pathName</i> <b class='cmd'>selection count</b></a><dd> @@ -2294,7 +2297,7 @@ of items in the treectrl that are currently selected. <br><br> <dt><a name="132"><i class='arg'>pathName</i> <b class='cmd'>selection get</b></a><dd> -Returns a list containing the numerical ids of +Returns a list containing the item ids of all of the items in the treectrl that are currently selected. If there are no items selected in the treectrl then an empty string is returned. @@ -2302,27 +2305,24 @@ string is returned. <br><br> <dt><a name="133"><i class='arg'>pathName</i> <b class='cmd'>selection includes</b> <i class='arg'>itemDesc</i></a><dd> -Returns 1 if the item indicated by <i class='arg'>itemDesc</i> is currently +Returns 1 if the item described by <i class='arg'>itemDesc</i> is currently selected, 0 if it isn't. <br><br> <dt><a name="134"><i class='arg'>pathName</i> <b class='cmd'>selection modify</b> <i class='arg'>select</i> <i class='arg'>deselect</i></a><dd> Both arguments <i class='arg'>select</i> and <i class='arg'>deselect</i> must be -the string <strong>all</strong> or a possibly empty list of <i class='arg'>itemDesc</i>s. -Selects all of the items described by <i class='arg'>select</i>, -then deselects all items described by <i class='arg'>deselect</i>, -without affecting the selection state of any item -not mentioned in both arguments. -If one item is described in both arguments <i class='arg'>select</i> and <i class='arg'>deselect</i>, -it is added to the selection. -A <strong><Selection></strong> event is generated. +the string <strong>all</strong> or a possibly-empty list of <a href="#item_description">item descriptions</a>. +Any unselected items in <i class='arg'>select</i> are added to the selection, +and any selected items in <i class='arg'>deselect</i> are removed from the selection (except +for those items which are also in <i class='arg'>select</i>). +A <strong><Selection></strong> event is generated if any items were selected or deselected. </dl> <dt><a name="135"><i class='arg'>pathName</i> <b class='cmd'>style</b> <i class='arg'>option</i> ?<i class='arg'>element</i>? ?<i class='arg'>arg arg ...</i>?</a><dd> -This command is used to manipulate styles, which could be considered -as a geometry manager for the elements of one item. +This command is used to manipulate styles, which can be thought of +as a geometry manager for elements. The exact behavior of the command depends on the <i class='arg'>option</i> argument that follows the <b class='cmd'>style</b> argument. The following forms of the command are supported: @@ -2649,8 +2649,7 @@ The following options are supported for columns: <dl> <dt><strong><strong>-arrow</strong></strong> <i class='arg'>direction</i><dd> -Indicates whether or not an arrow should be drawn in the column header -to the right of the column title. +Indicates whether or not an arrow should be drawn in the column header. <i class='arg'>Direction</i> must have one of the values <strong>none</strong> (the default), <strong>up</strong>, or <strong>down</strong>. @@ -2667,7 +2666,7 @@ If an image is specified for a certain state, it overrides the -arrowbitmap opti <br><br> <dt><strong><strong>-arrowside</strong></strong> <i class='arg'>side</i><dd> -Indicates on which side an arrow should be drawn, if at all. +Indicates on which side of the bitmap/image/text the arrow should be drawn. <i class='arg'>Side</i> must be either <strong>left</strong> or <strong>right</strong> (the default). <br><br> @@ -2679,7 +2678,7 @@ if there is more space available for drawing the arrow then needed. <br><br> <dt><strong><strong>-arrowpadx</strong></strong> <i class='arg'>amount</i><dd> <i class='arg'>Amount</i> specifies how much padding to -leave on the left and right side of the arrow. +leave on the left and right of the arrow. <i class='arg'>Amount</i> may be a list of two values to specify padding for left and right separately; it defaults to 6. @@ -2734,7 +2733,7 @@ This option overrides the <strong>-bitmap</strong> column option. <br><br> <dt><strong><strong>-imagepadx</strong></strong> <i class='arg'>amount</i><dd> <i class='arg'>Amount</i> specifies how much padding to -leave on the left and right side of the image. +leave on the left and right of the image (or bitmap). <i class='arg'>Amount</i> may be a list of two values to specify padding for left and right separately; it defaults to 6. @@ -2742,15 +2741,15 @@ it defaults to 6. <br><br> <dt><strong><strong>-imagepady</strong></strong> <i class='arg'>amount</i><dd> <i class='arg'>Amount</i> specifies how much padding to -leave on the top and bottom of the image. +leave on the top and bottom of the image (or bitmap). <i class='arg'>Amount</i> may be a list of two values to specify padding for top and bottom separately; it defaults to 0. <br><br> <dt><strong><strong>-itembackground</strong></strong> <i class='arg'>colorList</i><dd> -Specifies a list of colors, which should be used as -alternating background color for the items of this column. +Specifies a list of zero or more colors, which are used as +alternating background colors for items in this column. See also the <strong>-backgroundmode</strong> widget option for more on this. <br><br> @@ -2801,7 +2800,7 @@ whenever a column must be specified. <br><br> <dt><strong><strong>-text</strong></strong> <i class='arg'>text</i><dd> -Specifies a text to be displayed inside the column title. +Specifies a text string to be displayed as the column title. <br><br> <dt><strong><strong>-textcolor</strong></strong> <i class='arg'>color</i><dd> @@ -2821,7 +2820,7 @@ of text. <br><br> <dt><strong><strong>-textpadx</strong></strong> <i class='arg'>amount</i><dd> <i class='arg'>Amount</i> specifies how much padding to -leave on the left and right side of the text. +leave on the left and right of the text. <i class='arg'>Amount</i> may be a list of two values to specify padding for left and right separately; it defaults to 6. @@ -2925,17 +2924,16 @@ is true. <h2><a name="states">STATES</a></h2> <p> -A state consists basically of just a string: its <i class='arg'>stateName</i>. -For every item a set of these states is managed, -which means that every item can have every state switched on or off. +For every item a set of boolean states is managed. These states play an +integral role in the appearance of each item. The following states are predefined for every item: <dl> <dt><strong>active</strong><dd> -At every time this state is set for exactly one item, -which therefore is called the active item. +At all times this state is set for exactly one item. The active item is +used with keyboard navigation. When the treectrl widget is created or when the active item is deleted, -the root item will become the active element. +the root item will become the active item. This state can be modified by means of the widget command <b class='cmd'>activate</b>. <br><br> @@ -2946,9 +2944,9 @@ It cannot be modified. <br><br> <dt><strong>focus</strong><dd> This state is set for every item, -if the treectrl widget has currently the focus. +if the treectrl widget currently has the focus. It cannot be modified by means of a widget command, -but is maintained as reaction of a <FocusIn> or <FocusOut> event. +but is maintained in reaction to the <FocusIn> and <FocusOut> events. <br><br> <dt><strong>open</strong><dd> @@ -2958,33 +2956,19 @@ the descendants of the item are displayed If this state is switched off, the descendants of the item are not displayed - the item is collapsed. -For a new item this state is switched on. -It can be modified by means of the widget commands +For a new item this state is switched on by default. +This state can be modified by means of the widget commands <b class='cmd'>item expand</b>, <b class='cmd'>item collapse</b>, or <b class='cmd'>item toggle</b>. <br><br> <dt><strong>selected</strong><dd> -This state is set for every item, which is included in the selection. +This state is set for every item included in the selection. It can be modified by means of the widget command <b class='cmd'>selection</b>. </dl> <p> By means of the <b class='cmd'>state define</b> widget command -up to 27 additional <i class='arg'>stateName</i>s can be defined. - -<p> -Some widget commands expect a <i class='arg'>stateDesc</i> argument, -which is a <i class='arg'>stateName</i> -optionally preceded by an exclamation mark (<strong>!</strong>). -If the <i class='arg'>stateName</i> has no leading <strong>!</strong> -it describes a currently switched on state, -if it has a leading <strong>!</strong> it describes a currently switched off state. - -<p> -Some widget commands expect a <i class='arg'>statePattern</i> argument, -which should be a non empty list of <i class='arg'>stateDesc</i>s. -The pattern matches, if for every element of the list -the <i class='arg'>stateDesc</i> describes the same state as the item currently has. +up to 27 additional states can be defined. <h2><a name="per-state_options">PER-STATE OPTIONS</a></h2> <p> @@ -3399,6 +3383,9 @@ Indicates the item nearest to the point given by <i class='arg'>x</i> and <i cla <br><br> <dt><strong>rnc</strong> <i class='arg'>row column</i><dd> Indicates the item in the given <i class='arg'>row</i> and <i class='arg'>column</i>. +The row and column corresponds to +the on-screen arrangement of items as determined by the -orient and -wrap +options. You can memorize <strong>rnc</strong> as abbreviation of "row 'n' column". <br><br> diff --git a/doc/treectrl.man b/doc/treectrl.man index 9ed125d..01dbc94 100644 --- a/doc/treectrl.man +++ b/doc/treectrl.man @@ -3,11 +3,11 @@ See the file "license.terms" for information on usage and redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES. - $Id: treectrl.man,v 1.30 2005/07/15 01:39:20 treectrl Exp $} -][manpage_begin treectrl n 2.0] + $Id: treectrl.man,v 1.31 2005/07/23 00:35:20 treectrl Exp $} +][manpage_begin treectrl n 2.1] [moddesc {Tk Commands}] [titledesc {Create and manipulate hierarchical multicolumn widgets}] -[require treectrl 2.0] +[require treectrl 2.1] [description] [list_begin definitions] @@ -165,7 +165,7 @@ double-buffered, so it works with a buffer size as big as the biggest item. [tkoption_def -height height Height] Specifies the desired height for the window in any of the forms acceptable to [fun Tk_GetPixels]. -The default is 200 pixel. +The default is 200 pixels. If this option is less than or equal to zero then the window will not request any size at all. @@ -193,40 +193,23 @@ use it. [tkoption_def -itemwidth itemWidth ItemWidth] Specifies a fixed width for every item in any of the forms acceptable to [fun Tk_GetPixels]. -This option only has an effect when either of these sets of conditions are met: -a) the treectrl's -orient option is vertical, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -wrap option causes a 2-dimension arrangement of items, or -b) the treectrl's -orient option is horizontal, and -only a single column is visible, and -the visible column's -width option is "". +If more than one column is visible, then this option has no effect. +If the -orient option is vertical, and the -wrap option is unspecified, then this +option has no effect (in that case all items are as wide as the column). [tkoption_def -itemwidthequal itemWidthEqual ItemWidthEqual] Specifies a boolean that says whether all items should have the same width. -This option only has an effect when either of these sets of conditions are met: -a) the treectrl's -orient option is vertical, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -wrap option causes a 2-dimension arrangement of items, and -the treectrl's -itemwidth option is <= 0, or -b) the treectrl's -orient option is horizontal, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -itemwidth option is <= 0. +If more than one column is visible, then this option has no effect. +If the -orient option is vertical, and the -wrap option is unspecified, then this +option has no effect (in that case all items are as wide as the column). +If the -itemwidth option is specified, then this option has no effect. [tkoption_def -itemwidthmultiple itemWidthMultiple ItemWidthMultiple] Specifies a screen distance that every item's width will be evenly divisible by in any of the forms acceptable to [fun Tk_GetPixels]. -This option only has an effect when either of these sets of conditions are met: -a) the treectrl's -orient option is vertical, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -wrap option causes a 2-dimension arrangement of items, and -the treectrl's -itemwidth option is <= 0, or -b) the treectrl's -orient option is horizontal, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -itemwidth option is <= 0. +If more than one column is visible, then this option has no effect. +If the -orient option is vertical, and the -wrap option is unspecified, then this +option has no effect (in that case all items are as wide as the column). +If the -itemwidth option is specified, then this option has no effect. [tkoption_def -linecolor lineColor LineColor] Specifies the color which should be used for drawing @@ -296,9 +279,9 @@ should draw the connecting lines between children of the root item. The default value is true. [tkoption_def -treecolumn treeColumn TreeColumn] -Specifies an integer value that determines which -column displays the data in an hierarchical fashion. -Default is 0 meaning that the first column displays the tree. +Specifies a [sectref {COLUMN DESCRIPTION} {column description}] that determines which +column displays the buttons and lines. +The default is unspecified. [tkoption_def -usetheme useTheme UseTheme] Specifies a boolean value that determines whether this widget should draw @@ -313,18 +296,22 @@ If this option is less than or equal to zero then the window will not request any size at all. [tkoption_def -wrap wrap Wrap] -Specifies how to arrange items inside treectrl's window. -The value must be an empty string, [const window], -or a list with an integer as first element -and either [const items] or [const pixels] as second element. -The empty string as wrap mode means that each item appears on -exactly one line on the screen. -In the other modes multiple items may be displayed in one screen line. -In [const window] mode a screen line break may occur after any element; -in [const items] mode a line break will only be made after the specified -number of items; -in [const pixels] mode a line break will only be made after the -specified screen distance is reached. +Specifies whether items are arranged in a 1- or 2-dimensional layout. + +If the value is an empty string (the default), then items are arranged from top +to bottom (-orient vertical) or from left to right (-orient horizontal) in +a 1-dimensional layout. + +If the value is "[emph N] [const items]", then a no more than [emph N] items will appear in +a vertical group (-orient vertical) or horizontal group (-orient horizontal). + +If the value is "[emph N] [const pixels]", then a no vertical group of items will be +taller than [emph N] pixels (-orient vertical) or no horizontal group of items will +be wider than [emph N] pixels (-orient horizontal). + +If the value is [const window], then a no vertical group of items will be +taller than the window (-orient vertical) or no horizontal group of items will +be wider than the window (-orient horizontal). [tkoption_def -xscrolldelay xScrollDelay ScrollDelay] Specifies the amount of time before the default binding should handle @@ -422,10 +409,10 @@ The following forms of the command are supported: [list_begin definitions] [call [arg pathName] [cmd {column bbox}] [arg column]] -Returns a list with four elements giving an approximate bounding box +Returns a list with four elements giving the bounding box for the column header specified by [arg column]. -If the treectrl is configured to don't display the column headers -by means of the [option -showheader] option, +If the treectrl is configured not to display the column headers +by means of the [option -showheader] option, then an empty list is returned instead. [call [arg pathName] [cmd {column cget}] [arg column] [arg option]] @@ -585,10 +572,10 @@ this case the command returns an empty string. command. [call [arg pathName] [cmd contentbox]] -Returns a list with four elements giving an approximate bounding box -for the space used to display the items inside the columns, -i.e. the space of the treectrl widget without -the surrounding borders and the column headers. +Returns a list with four elements giving the bounding box +for the space used to display the items, +i.e. the space of the treectrl window without +the surrounding borders or the column headers. [call [arg pathName] [cmd debug] [arg option] [opt [arg {arg arg ...}]]] This command is used to facilitate debugging of the treectrl widget. @@ -656,7 +643,7 @@ debugging options [option -enable] and [option -display] are switched on. [call [arg pathName] [cmd {debug dinfo}]] For every of the treectrl widget -a line with some internal valuess info about all items +a line with some internal values info about all items is printed to stdout. The command returns the empty string. @@ -849,13 +836,14 @@ The following forms of the command are supported: [list_begin definitions] [call [arg pathName] [cmd {item ancestors}] [arg itemDesc]] -Returns a list containing the numerical indexes of all ancestors -of the item specified by [arg itemDesc] from its parent up to the -root item. +Returns a list containing the item ids of the ancestors +of the item specified by [arg itemDesc]. The first list value is the parent, +the second is the parent's parent, an so on. The last list value will be the +root item if [arg itemDesc] is a descendant of the root item. [call [arg pathName] [cmd {item bbox}] [arg itemDesc] [opt [arg column]] \ [opt [arg element]]] -Returns a list with four elements giving an approximate bounding box +Returns a list with four elements giving the bounding box for the item described by [arg itemDesc]. If no further argument is specified, the bbox spans the area of the item over all columns. If a [arg column] is specified, only the area of the item @@ -869,7 +857,7 @@ Returns the current value of the configuration option for the item specified by values accepted by the [cmd "item configure"] command. [call [arg pathName] [cmd {item children}] [arg itemDesc]] -Returns a list containing the numerical indexes of all children +Returns a list containing the item ids of all children of the item specified by [arg itemDesc] in the correct order from the first child to the last child. @@ -997,9 +985,10 @@ and b) each ancestor's [option -visible] option is true [call [arg pathName] [cmd {item delete}] [arg first] [opt [arg last]]] Deletes the specified item(s). -[arg First] and [arg last] must be the string [const all] or an [arg itemDesc]. -If either [arg first] or [arg last] is specified as [const all], all items are -deleted; if [arg first] is specified as [arg itemDesc] and [arg last] isn't +[arg First] and [arg last] must be the string [const all] or a valid +[sectref {ITEM DESCRIPTION} {item description}]. +If either [arg first] or [arg last] is specified as [const all], then all items are +deleted. If [arg first] is specified and [arg last] isn't specified, the item described by [arg first] is deleted. If both [arg first] and [arg last] are specified, they must decribe items with a common ancestor; @@ -1010,6 +999,12 @@ If the current [const active] item is deleted, the root item becomes the new act If the current selection [const anchor] item is deleted, the root item becomes the new anchor item. There is no way to delete the root item of the treectrl widget; in all cases the specification of the root item is ignored. +[nl] +For each call to this command, two events may be generated. +If any of the deleted items are selected, then a [const <Selection>] event +is generated just before the items are deleted. +If any items were actually deleted, then an [const <ItemDelete>] event event is generated just before the items +are deleted. [call [arg pathName] [cmd {item dump}] [arg itemDesc]] Returns a list with six elements in the form @@ -1095,15 +1090,15 @@ an [const <Expand-before>] event before the item state is changed, and an [const <Expand-after>] event after the item state was changed. [call [arg pathName] [cmd {item firstchild}] [arg parent] [opt [arg child]]] -If [arg child] is not specified, returns the numerical index of the first +If [arg child] is not specified, returns the item id of the first child of the item described by [arg parent]. If [arg child] is specified, it must described an item that is not an ancestor of [arg parent]. Then it will become the new first child of [arg parent]. [call [arg pathName] [cmd {item id}] [arg itemDesc]] -This command resolves the item description [arg itemDesc] into a unique item -identifier (see [sectref {ITEM DESCRIPTION}] below). If the item described by +This command resolves the [sectref {ITEM DESCRIPTION} {item description}] [arg itemDesc] into a unique item +identifier. If the item described by [arg itemDesc] doesn't exist, this command returns an empty string. [call [arg pathName] [cmd {item image}] [arg itemDesc] [opt [arg column]] \ @@ -1128,20 +1123,20 @@ Returns 1 if the item described by [arg itemDesc] is a direct or indirect parent of the item decribed by [arg descendant], 0 otherwise. [call [arg pathName] [cmd {item isopen}] [arg itemDesc]] -Returns 1, if the item described by [arg itemDesc] has cuurently the +Returns 1 if the item described by [arg itemDesc] has the state [const open] switched on, 0 otherwise. [call [arg pathName] [cmd {item lastchild}] [arg parent] [opt [arg child]]] -If [arg child] is not specified, returns the numerical index of the last +If [arg child] is not specified, returns the item id of the last child of the item described by [arg parent]. -If [arg child] is specified, it must described an item +If [arg child] is specified, it must describe an item that is not an ancestor of [arg parent]. Then it will become the new last child of [arg parent]. [call [arg pathName] [cmd {item nextsibling}] [arg sibling] [opt [arg next]]] -If [arg next] is not specified, returns the numerical index of the next +If [arg next] is not specified, returns the item id of the next sibling of the item described by [arg sibling]. -If [arg next] is specified, it must described an item +If [arg next] is specified, it must describe an item that is not an ancestor of [arg sibling]. Then it will become the new next sibling of [arg sibling]. @@ -1158,31 +1153,34 @@ result of this command is the row the item falls in. If the optional argument is not visible. [call [arg pathName] [cmd {item parent}] [arg itemDesc]] -Returns the numerical index of the parent of the item +Returns the item id of the parent of the item described by [arg itemDesc]. [call [arg pathName] [cmd {item prevsibling}] [arg sibling] [opt [arg prev]]] -If [arg prev] is not specified, returns the numerical index of the previous +If [arg prev] is not specified, returns the item id of the previous sibling of the item described by [arg sibling]. -If [arg prev] is specified, it must described an item +If [arg prev] is specified, it must describe an item that is not an ancestor of [arg sibling]. Then it will become the new previous sibling of [arg sibling]. [call [arg pathName] [cmd {item range}] [arg first] [arg last]] -Returns a list containing the unique identifiers of all items +Returns a list containing the item ids of all items in the range between [arg first] and [arg last], inclusive. The order between [arg first] and [arg last] doesn't matter, -and the result is always ordered by the increasing index of the items. +and the result is always sorted by the increasing order of the items (as +returned by the [cmd {item order}] command). The items specified by [arg first] and [arg last] must share a common ancestor. [call [arg pathName] [cmd {item remove}] [arg itemDesc]] Removes the item described by [arg itemDesc] -from the children list of its father, so that it will become an orphan. +from the list of children of its parent, so that it will become an orphan. [call [arg pathName] [cmd {item rnc}] [arg itemDesc]] Returns a list of two integers, which corresponds to the row and column -of the item described by [arg itemDesc]. +of the item described by [arg itemDesc]. The row and column corresponds to +the on-screen arrangement of items as determined by the -orient and -wrap +options. If the item is not displayed, this command returns an empty string. [call [arg pathName] [cmd {item sort}] [arg itemDesc] [opt [arg {option ...}]]] Sorts the children of the item described by [arg itemDesc], @@ -1266,30 +1264,32 @@ The following forms of the command are supported: [call [arg pathName] [cmd {item state forcolumn}] [arg itemDesc] [arg column] \ [opt [arg stateDescList]]] -Just like [cmd {item state set}] but manipulates user-defined states for a single -item column, not the item as a whole. +Just like [cmd {item state set}] but manipulates dynamic states for a single +item column, not the item as a whole. If [arg stateDescList] is unspecified, +this command returns a list containing the names of all the dynamic states +which are switched on in [arg column]. [call [arg pathName] [cmd {item state get}] [arg itemDesc] \ [opt [arg {stateName}]]] If no [arg stateName] is specified, returns a list containing -the names of all (predefined and user defined) states +the names of all (static and dynamic) states which are currently switched on for the item described by [arg itemDesc]. If a [arg stateName] is specified, 1 is returned if the specified state is currently switched on for the item, 0 otherwise. [call [arg pathName] [cmd {item state set}] [arg itemDesc] \ - [opt [arg lastItem]] [opt [arg stateDescList]]] + [opt [arg lastItem]] [arg stateDescList]] Every element of [arg stateDescList] -must describe a user defined state (see [sectref STATES] below), -with the particularity that the state name may have also a leading [const ~]. +must be the name of a dynamic state (see [sectref STATES] below), +optionally preceded by a [const ~] or [const !] character. Every state with a leading [const !] will be switched off for the item described by [arg itemDesc], every state with a leading [const ~] will be toggled, and every state without leading [const !] or [const ~] will be switched on. If [arg lastItem] is specified, the state changes will be made for all items in the range betwen [arg itemDesc] and [arg lastItem]. -[arg ItemDesc] may be the string [const all], +If [arg ItemDesc] is the string [const all], then the state changes are made for all items of the treectrl widget. [list_end] @@ -1303,9 +1303,10 @@ The following forms of the command are supported: [list_begin definitions] [call [arg pathName] [cmd {item style elements}] [arg itemDesc] [arg column]] -A list is returned -containing the currently defined elements of the style, -which is set for the item described by [arg itemDesc] in [arg column]. +This command returns a list containing the names of elements which were +configured by the [cmd {item element configure}] command for the item +described by [arg itemDesc] in [arg column]. If there is no style assigned +to [arg column] an error is returned. [call [arg pathName] [cmd {item style map}] [arg itemDesc] [arg column] \ [arg style] [arg map]] @@ -1628,17 +1629,17 @@ Deprecated. Use the [cmd {column count}] command instead. Deprecated. Use the [cmd {item count}] command instead. [call [arg pathName] [cmd orphans]] -Returns a list containing the numerical ids of all items -which has no parent item. -An item is created without having a parent, -and can later become an orphan again -by means of the [cmd {item remove}] widget command. +Returns a list containing the item ids of all items +which have no parent. +When an item is created, it has no parent by default, +and can later become an orphan +by means of the [cmd {item remove}] widget command. The root item is not returned. [call [arg pathName] [cmd range] [arg first] [arg last]] Deprecated. Use the [cmd {item range}] command instead. [call [arg pathName] [cmd state] [arg option] [opt [arg stateName]]] -This command is used to manipulate the list of user defined states, +This command is used to manipulate the list of user-defined states, see section [sectref STATES] below. The exact behavior of the command depends on the [arg option] argument that follows the [cmd state] argument. @@ -1647,20 +1648,20 @@ The following forms of the command are supported: [list_begin definitions] [call [arg pathName] [cmd {state define}] [arg stateName]] Defines a new state with the name [arg stateName], -which must not be the name of a predefined or already user defined state. +which must not be the name of an existing state. [call [arg pathName] [cmd {state linkage}] [arg stateName]] Returns a string indicating -whether the specified state is user defined +whether the specified state is user-defined by means of the [cmd {state define}] widget command ([const dynamic]) or predefined by the treectrl widget itself ([const static]). [call [arg pathName] [cmd {state names}]] -Returns a list containing the names of all user defined states. +Returns a list containing the names of all user-defined states. [call [arg pathName] [cmd {state undefine}] [opt [arg {stateName ...}]]] -Every [arg stateName] must be the name of a user defined state. -Removes this state from the list of user defined states. +Every [arg stateName] must be the name of a user-defined state. +Removes this state from the list of user-defined states. [list_end] [call [arg pathName] [cmd see] [arg itemDesc]] @@ -1678,13 +1679,14 @@ It has several forms, depending on [arg option]: [list_begin definitions] [call [arg pathName] [cmd {selection add}] [arg first] [opt [arg last]]] [arg First] and [arg last] (if specified) -must be the string [const all] or an [arg itemDesc]. -Selects all of the items in the range between -[arg first] and [arg last], inclusive, +must be the string [const all] or a valid [sectref {ITEM DESCRIPTION} {item description}]. +Adds every unselected item in the range between +[arg first] and [arg last], inclusive, to the selection without affecting the selection state of items outside that range. If one of the arguments is the string [const all], -all items of the treectrl widget are added to the selection instead. -A [const <Selection>] event is generated. +every unselected item in the treectrl widget is added to the selection. +A [const <Selection>] event is generated if any items were added to the +selection. [call [arg pathName] [cmd {selection anchor}] [opt [arg itemDesc]]] If [arg itemDesc] is specified, @@ -1698,45 +1700,43 @@ Returns the numerical id of the selection anchor item. [call [arg pathName] [cmd {selection clear}] \ [opt [arg first]] [opt [arg last]]] [arg First] and [arg last] (if specified) -must be the string [const all] or an [arg itemDesc]. +must be the string [const all] or a valid [sectref {ITEM DESCRIPTION} {item description}]. If any of the items between [arg first] and [arg last] (inclusive) are selected, they are deselected. The selection state is not changed for items outside this range. -If no additional arguments is given -or one of the arguments is the string [const all], -the selection is completely cleared instead. -A [const <Selection>] event is generated. +If no additional arguments are given, +or if one of the arguments is the string [const all], +then all items are removed from the selection. +A [const <Selection>] event is generated if any items were removed from the +selection. [call [arg pathName] [cmd {selection count}]] Returns an integer indicating the number of items in the treectrl that are currently selected. [call [arg pathName] [cmd {selection get}]] -Returns a list containing the numerical ids of +Returns a list containing the item ids of all of the items in the treectrl that are currently selected. If there are no items selected in the treectrl then an empty string is returned. [call [arg pathName] [cmd {selection includes}] [arg itemDesc]] -Returns 1 if the item indicated by [arg itemDesc] is currently +Returns 1 if the item described by [arg itemDesc] is currently selected, 0 if it isn't. [call [arg pathName] [cmd {selection modify}] [arg select] [arg deselect]] Both arguments [arg select] and [arg deselect] must be -the string [const all] or a possibly empty list of [arg itemDesc]s. -Selects all of the items described by [arg select], -then deselects all items described by [arg deselect], -without affecting the selection state of any item -not mentioned in both arguments. -If one item is described in both arguments [arg select] and [arg deselect], -it is added to the selection. -A [const <Selection>] event is generated. +the string [const all] or a possibly-empty list of [sectref {ITEM DESCRIPTION} {item descriptions}]. +Any unselected items in [arg select] are added to the selection, +and any selected items in [arg deselect] are removed from the selection (except +for those items which are also in [arg select]). +A [const <Selection>] event is generated if any items were selected or deselected. [list_end] [call [arg pathName] [cmd style] [arg option] [opt [arg element]] \ [opt [arg {arg arg ...}]]] -This command is used to manipulate styles, which could be considered -as a geometry manager for the elements of one item. +This command is used to manipulate styles, which can be thought of +as a geometry manager for elements. The exact behavior of the command depends on the [arg option] argument that follows the [cmd style] argument. The following forms of the command are supported: @@ -2027,8 +2027,7 @@ The following options are supported for columns: [list_begin opt] [opt_def [option -arrow] [arg direction]] -Indicates whether or not an arrow should be drawn in the column header -to the right of the column title. +Indicates whether or not an arrow should be drawn in the column header. [arg Direction] must have one of the values [const none] (the default), [const up], or [const down]. @@ -2042,7 +2041,7 @@ use to draw the arrow if this column's -arrow option is not [const none]. If an image is specified for a certain state, it overrides the -arrowbitmap option. [opt_def [option -arrowside] [arg side]] -Indicates on which side an arrow should be drawn, if at all. +Indicates on which side of the bitmap/image/text the arrow should be drawn. [arg Side] must be either [const left] or [const right] (the default). [opt_def [option -arrowgravity] [arg side]] @@ -2052,7 +2051,7 @@ if there is more space available for drawing the arrow then needed. [opt_def [option -arrowpadx] [arg amount]] [arg Amount] specifies how much padding to -leave on the left and right side of the arrow. +leave on the left and right of the arrow. [arg Amount] may be a list of two values to specify padding for left and right separately; it defaults to 6. @@ -2098,21 +2097,21 @@ This option overrides the [option -bitmap] column option. [opt_def [option -imagepadx] [arg amount]] [arg Amount] specifies how much padding to -leave on the left and right side of the image. +leave on the left and right of the image (or bitmap). [arg Amount] may be a list of two values to specify padding for left and right separately; it defaults to 6. [opt_def [option -imagepady] [arg amount]] [arg Amount] specifies how much padding to -leave on the top and bottom of the image. +leave on the top and bottom of the image (or bitmap). [arg Amount] may be a list of two values to specify padding for top and bottom separately; it defaults to 0. [opt_def [option -itembackground] [arg colorList]] -Specifies a list of colors, which should be used as -alternating background color for the items of this column. +Specifies a list of zero or more colors, which are used as +alternating background colors for items in this column. See also the [option -backgroundmode] widget option for more on this. [opt_def [option -justify] [arg justification]] @@ -2154,7 +2153,7 @@ Defines a unique name for the column which can be used whenever a column must be specified. [opt_def [option -text] [arg text]] -Specifies a text to be displayed inside the column title. +Specifies a text string to be displayed as the column title. [opt_def [option -textcolor] [arg color]] Specifies a color, which should be used as foreground color @@ -2171,7 +2170,7 @@ of text. [opt_def [option -textpadx] [arg amount]] [arg Amount] specifies how much padding to -leave on the left and right side of the text. +leave on the left and right of the text. [arg Amount] may be a list of two values to specify padding for left and right separately; it defaults to 6. @@ -2261,17 +2260,16 @@ is true. [list_end] [section STATES] -A state consists basically of just a string: its [arg stateName]. -For every item a set of these states is managed, -which means that every item can have every state switched on or off. +For every item a set of boolean states is managed. These states play an +integral role in the appearance of each item. The following states are predefined for every item: [list_begin definitions] [lst_item [const active]] -At every time this state is set for exactly one item, -which therefore is called the active item. +At all times this state is set for exactly one item. The active item is +used with keyboard navigation. When the treectrl widget is created or when the active item is deleted, -the root item will become the active element. +the root item will become the active item. This state can be modified by means of the widget command [cmd activate]. [lst_item [const enabled]] @@ -2280,9 +2278,9 @@ It cannot be modified. [lst_item [const focus]] This state is set for every item, -if the treectrl widget has currently the focus. +if the treectrl widget currently has the focus. It cannot be modified by means of a widget command, -but is maintained as reaction of a <FocusIn> or <FocusOut> event. +but is maintained in reaction to the <FocusIn> and <FocusOut> events. [lst_item [const open]] If this state is switched on, @@ -2291,32 +2289,18 @@ the descendants of the item are displayed If this state is switched off, the descendants of the item are not displayed - the item is collapsed. -For a new item this state is switched on. -It can be modified by means of the widget commands +For a new item this state is switched on by default. +This state can be modified by means of the widget commands [cmd {item expand}], [cmd {item collapse}], or [cmd {item toggle}]. [lst_item [const selected]] -This state is set for every item, which is included in the selection. +This state is set for every item included in the selection. It can be modified by means of the widget command [cmd selection]. [list_end] [para] By means of the [cmd {state define}] widget command -up to 27 additional [arg stateName]s can be defined. - -[para] -Some widget commands expect a [arg stateDesc] argument, -which is a [arg stateName] -optionally preceded by an exclamation mark ([const !]). -If the [arg stateName] has no leading [const !] -it describes a currently switched on state, -if it has a leading [const !] it describes a currently switched off state. - -[para] -Some widget commands expect a [arg statePattern] argument, -which should be a non empty list of [arg stateDesc]s. -The pattern matches, if for every element of the list -the [arg stateDesc] describes the same state as the item currently has. +up to 27 additional states can be defined. [section {PER-STATE OPTIONS}] @@ -2684,6 +2668,9 @@ Indicates the item nearest to the point given by [arg x] and [arg y]. [lst_item "[const rnc] [arg {row column}]"] Indicates the item in the given [arg row] and [arg column]. +The row and column corresponds to +the on-screen arrangement of items as determined by the -orient and -wrap +options. You can memorize [const rnc] as abbreviation of "row 'n' column". [lst_item [const root]] diff --git a/doc/treectrl.n b/doc/treectrl.n index 38fd512..2aac72e 100644 --- a/doc/treectrl.n +++ b/doc/treectrl.n @@ -6,14 +6,14 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" $Id: treectrl.n,v 1.46 2005/07/15 01:39:20 treectrl Exp $ +'\" $Id: treectrl.n,v 1.47 2005/07/23 00:35:21 treectrl Exp $ .so man.macros -.TH "treectrl" n 2.0 treectrl "Tk Commands" +.TH "treectrl" n 2.1 treectrl "Tk Commands" .BS .SH "NAME" treectrl \- Create and manipulate hierarchical multicolumn widgets .SH "SYNOPSIS" -package require \fBtreectrl 2.0\fR +package require \fBtreectrl 2.1\fR .sp \fBtreectrl\fR \fIpathName\fR ?\fIoptions\fR? .sp @@ -189,7 +189,7 @@ package require \fBtreectrl 2.0\fR .sp \fIpathName\fR \fBitem state get\fR \fIitemDesc\fR ?\fIstateName\fR? .sp -\fIpathName\fR \fBitem state set\fR \fIitemDesc\fR ?\fIlastItem\fR? ?\fIstateDescList\fR? +\fIpathName\fR \fBitem state set\fR \fIitemDesc\fR ?\fIlastItem\fR? \fIstateDescList\fR .sp \fIpathName\fR \fBitem style\fR \fIcommand\fR \fIitemDesc\fR ?\fIarg ...\fR? .sp @@ -569,7 +569,7 @@ Database Class: \fBHeight\fR .IP Specifies the desired height for the window in any of the forms acceptable to \fBTk_GetPixels\fR. -The default is 200 pixel. +The default is 200 pixels. If this option is less than or equal to zero then the window will not request any size at all. .LP @@ -625,14 +625,9 @@ Database Class: \fBItemWidth\fR .fi .IP Specifies a fixed width for every item in any of the forms acceptable to \fBTk_GetPixels\fR. -This option only has an effect when either of these sets of conditions are met: -a) the treectrl's -orient option is vertical, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -wrap option causes a 2-dimension arrangement of items, or -b) the treectrl's -orient option is horizontal, and -only a single column is visible, and -the visible column's -width option is "". +If more than one column is visible, then this option has no effect. +If the -orient option is vertical, and the -wrap option is unspecified, then this +option has no effect (in that case all items are as wide as the column). .LP .nf .ta 6c @@ -643,16 +638,10 @@ Database Class: \fBItemWidthEqual\fR .fi .IP Specifies a boolean that says whether all items should have the same width. -This option only has an effect when either of these sets of conditions are met: -a) the treectrl's -orient option is vertical, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -wrap option causes a 2-dimension arrangement of items, and -the treectrl's -itemwidth option is <= 0, or -b) the treectrl's -orient option is horizontal, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -itemwidth option is <= 0. +If more than one column is visible, then this option has no effect. +If the -orient option is vertical, and the -wrap option is unspecified, then this +option has no effect (in that case all items are as wide as the column). +If the -itemwidth option is specified, then this option has no effect. .LP .nf .ta 6c @@ -663,16 +652,10 @@ Database Class: \fBItemWidthMultiple\fR .fi .IP Specifies a screen distance that every item's width will be evenly divisible by in any of the forms acceptable to \fBTk_GetPixels\fR. -This option only has an effect when either of these sets of conditions are met: -a) the treectrl's -orient option is vertical, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -wrap option causes a 2-dimension arrangement of items, and -the treectrl's -itemwidth option is <= 0, or -b) the treectrl's -orient option is horizontal, and -only a single column is visible, and -the visible column's -width option is "", and -the treectrl's -itemwidth option is <= 0. +If more than one column is visible, then this option has no effect. +If the -orient option is vertical, and the -wrap option is unspecified, then this +option has no effect (in that case all items are as wide as the column). +If the -itemwidth option is specified, then this option has no effect. .LP .nf .ta 6c @@ -833,9 +816,9 @@ Database Class: \fBTreeColumn\fR .fi .IP -Specifies an integer value that determines which -column displays the data in an hierarchical fashion. -Default is 0 meaning that the first column displays the tree. +Specifies a \fBcolumn description\fR that determines which +column displays the buttons and lines. +The default is unspecified. .LP .nf .ta 6c @@ -871,18 +854,18 @@ Database Class: \fBWrap\fR .fi .IP -Specifies how to arrange items inside treectrl's window. -The value must be an empty string, \fBwindow\fR, -or a list with an integer as first element -and either \fBitems\fR or \fBpixels\fR as second element. -The empty string as wrap mode means that each item appears on -exactly one line on the screen. -In the other modes multiple items may be displayed in one screen line. -In \fBwindow\fR mode a screen line break may occur after any element; -in \fBitems\fR mode a line break will only be made after the specified -number of items; -in \fBpixels\fR mode a line break will only be made after the -specified screen distance is reached. +Specifies whether items are arranged in a 1- or 2-dimensional layout. +If the value is an empty string (the default), then items are arranged from top +to bottom (-orient vertical) or from left to right (-orient horizontal) in +a 1-dimensional layout. +If the value is "\fIN\fR \fBitems\fR", then a no more than \fIN\fR items will appear in +a vertical group (-orient vertical) or horizontal group (-orient horizontal). +If the value is "\fIN\fR \fBpixels\fR", then a no vertical group of items will be +taller than \fIN\fR pixels (-orient vertical) or no horizontal group of items will +be wider than \fIN\fR pixels (-orient horizontal). +If the value is \fBwindow\fR, then a no vertical group of items will be +taller than the window (-orient vertical) or no horizontal group of items will +be wider than the window (-orient horizontal). .LP .nf .ta 6c @@ -1000,10 +983,10 @@ The following forms of the command are supported: .RS .TP \fIpathName\fR \fBcolumn bbox\fR \fIcolumn\fR -Returns a list with four elements giving an approximate bounding box +Returns a list with four elements giving the bounding box for the column header specified by \fIcolumn\fR. -If the treectrl is configured to don't display the column headers -by means of the \fB-showheader\fR option, +If the treectrl is configured not to display the column headers +by means of the \fB-showheader\fR option, then an empty list is returned instead. .TP \fIpathName\fR \fBcolumn cget\fR \fIcolumn\fR \fIoption\fR @@ -1158,10 +1141,10 @@ this case the command returns an empty string. command. .TP \fIpathName\fR \fBcontentbox\fR -Returns a list with four elements giving an approximate bounding box -for the space used to display the items inside the columns, -i.e. the space of the treectrl widget without -the surrounding borders and the column headers. +Returns a list with four elements giving the bounding box +for the space used to display the items, +i.e. the space of the treectrl window without +the surrounding borders or the column headers. .TP \fIpathName\fR \fBdebug\fR \fIoption\fR ?\fIarg arg ...\fR? This command is used to facilitate debugging of the treectrl widget. @@ -1228,7 +1211,7 @@ debugging options \fB-enable\fR and \fB-display\fR are switched on. .TP \fIpathName\fR \fBdebug dinfo\fR For every of the treectrl widget -a line with some internal valuess info about all items +a line with some internal values info about all items is printed to stdout. The command returns the empty string. .TP @@ -1411,12 +1394,13 @@ The following forms of the command are supported: .RS .TP \fIpathName\fR \fBitem ancestors\fR \fIitemDesc\fR -Returns a list containing the numerical indexes of all ancestors -of the item specified by \fIitemDesc\fR from its parent up to the -root item. +Returns a list containing the item ids of the ancestors +of the item specified by \fIitemDesc\fR. The first list value is the parent, +the second is the parent's parent, an so on. The last list value will be the +root item if \fIitemDesc\fR is a descendant of the root item. .TP \fIpathName\fR \fBitem bbox\fR \fIitemDesc\fR ?\fIcolumn\fR? ?\fIelement\fR? -Returns a list with four elements giving an approximate bounding box +Returns a list with four elements giving the bounding box for the item described by \fIitemDesc\fR. If no further argument is specified, the bbox spans the area of the item over all columns. If a \fIcolumn\fR is specified, only the area of the item @@ -1430,7 +1414,7 @@ Returns the current value of the configuration option for the item specified by values accepted by the \fBitem configure\fR command. .TP \fIpathName\fR \fBitem children\fR \fIitemDesc\fR -Returns a list containing the numerical indexes of all children +Returns a list containing the item ids of all children of the item specified by \fIitemDesc\fR in the correct order from the first child to the last child. .TP @@ -1558,9 +1542,10 @@ and b) each ancestor's \fB-visible\fR option is true .TP \fIpathName\fR \fBitem delete\fR \fIfirst\fR ?\fIlast\fR? Deletes the specified item(s). -\fIFirst\fR and \fIlast\fR must be the string \fBall\fR or an \fIitemDesc\fR. -If either \fIfirst\fR or \fIlast\fR is specified as \fBall\fR, all items are -deleted; if \fIfirst\fR is specified as \fIitemDesc\fR and \fIlast\fR isn't +\fIFirst\fR and \fIlast\fR must be the string \fBall\fR or a valid +\fBitem description\fR. +If either \fIfirst\fR or \fIlast\fR is specified as \fBall\fR, then all items are +deleted. If \fIfirst\fR is specified and \fIlast\fR isn't specified, the item described by \fIfirst\fR is deleted. If both \fIfirst\fR and \fIlast\fR are specified, they must decribe items with a common ancestor; @@ -1571,6 +1556,12 @@ If the current \fBactive\fR item is deleted, the root item becomes the new activ If the current selection \fBanchor\fR item is deleted, the root item becomes the new anchor item. There is no way to delete the root item of the treectrl widget; in all cases the specification of the root item is ignored. +.sp +For each call to this command, two events may be generated. +If any of the deleted items are selected, then a \fB<Selection>\fR event +is generated just before the items are deleted. +If any items were actually deleted, then an \fB<ItemDelete>\fR event event is generated just before the items +are deleted. .TP \fIpathName\fR \fBitem dump\fR \fIitemDesc\fR Returns a list with six elements in the form @@ -1651,15 +1642,15 @@ an \fB<Expand-before>\fR event before the item state is changed, and an \fB<Expand-after>\fR event after the item state was changed. .TP \fIpathName\fR \fBitem firstchild\fR \fIparent\fR ?\fIchild\fR? -If \fIchild\fR is not specified, returns the numerical index of the first +If \fIchild\fR is not specified, returns the item id of the first child of the item described by \fIparent\fR. If \fIchild\fR is specified, it must described an item that is not an ancestor of \fIparent\fR. Then it will become the new first child of \fIparent\fR. .TP \fIpathName\fR \fBitem id\fR \fIitemDesc\fR -This command resolves the item description \fIitemDesc\fR into a unique item -identifier (see \fBITEM DESCRIPTION\fR below). If the item described by +This command resolves the \fBitem description\fR \fIitemDesc\fR into a unique item +identifier. If the item described by \fIitemDesc\fR doesn't exist, this command returns an empty string. .TP \fIpathName\fR \fBitem image\fR \fIitemDesc\fR ?\fIcolumn\fR? ?\fIimage\fR? ?\fIcolumn image ...\fR? @@ -1679,20 +1670,20 @@ Returns 1 if the item described by \fIitemDesc\fR is a direct or indirect parent of the item decribed by \fIdescendant\fR, 0 otherwise. .TP \fIpathName\fR \fBitem isopen\fR \fIitemDesc\fR -Returns 1, if the item described by \fIitemDesc\fR has cuurently the +Returns 1 if the item described by \fIitemDesc\fR has the state \fBopen\fR switched on, 0 otherwise. .TP \fIpathName\fR \fBitem lastchild\fR \fIparent\fR ?\fIchild\fR? -If \fIchild\fR is not specified, returns the numerical index of the last +If \fIchild\fR is not specified, returns the item id of the last child of the item described by \fIparent\fR. -If \fIchild\fR is specified, it must described an item +If \fIchild\fR is specified, it must describe an item that is not an ancestor of \fIparent\fR. Then it will become the new last child of \fIparent\fR. .TP \fIpathName\fR \fBitem nextsibling\fR \fIsibling\fR ?\fInext\fR? -If \fInext\fR is not specified, returns the numerical index of the next +If \fInext\fR is not specified, returns the item id of the next sibling of the item described by \fIsibling\fR. -If \fInext\fR is specified, it must described an item +If \fInext\fR is specified, it must describe an item that is not an ancestor of \fIsibling\fR. Then it will become the new next sibling of \fIsibling\fR. .TP @@ -1709,31 +1700,34 @@ result of this command is the row the item falls in. If the optional argument is not visible. .TP \fIpathName\fR \fBitem parent\fR \fIitemDesc\fR -Returns the numerical index of the parent of the item +Returns the item id of the parent of the item described by \fIitemDesc\fR. .TP \fIpathName\fR \fBitem prevsibling\fR \fIsibling\fR ?\fIprev\fR? -If \fIprev\fR is not specified, returns the numerical index of the previous +If \fIprev\fR is not specified, returns the item id of the previous sibling of the item described by \fIsibling\fR. -If \fIprev\fR is specified, it must described an item +If \fIprev\fR is specified, it must describe an item that is not an ancestor of \fIsibling\fR. Then it will become the new previous sibling of \fIsibling\fR. .TP \fIpathName\fR \fBitem range\fR \fIfirst\fR \fIlast\fR -Returns a list containing the unique identifiers of all items +Returns a list containing the item ids of all items in the range between \fIfirst\fR and \fIlast\fR, inclusive. The order between \fIfirst\fR and \fIlast\fR doesn't matter, -and the result is always ordered by the increasing index of the items. +and the result is always sorted by the increasing order of the items (as +returned by the \fBitem order\fR command). The items specified by \fIfirst\fR and \fIlast\fR must share a common ancestor. .TP \fIpathName\fR \fBitem remove\fR \fIitemDesc\fR Removes the item described by \fIitemDesc\fR -from the children list of its father, so that it will become an orphan. +from the list of children of its parent, so that it will become an orphan. .TP \fIpathName\fR \fBitem rnc\fR \fIitemDesc\fR Returns a list of two integers, which corresponds to the row and column -of the item described by \fIitemDesc\fR. +of the item described by \fIitemDesc\fR. The row and column corresponds to +the on-screen arrangement of items as determined by the -orient and -wrap +options. If the item is not displayed, this command returns an empty string. .TP \fIpathName\fR \fBitem sort\fR \fIitemDesc\fR ?\fIoption ...\fR? Sorts the children of the item described by \fIitemDesc\fR, @@ -1809,28 +1803,30 @@ The following forms of the command are supported: .RS .TP \fIpathName\fR \fBitem state forcolumn\fR \fIitemDesc\fR \fIcolumn\fR ?\fIstateDescList\fR? -Just like \fBitem state set\fR but manipulates user-defined states for a single -item column, not the item as a whole. +Just like \fBitem state set\fR but manipulates dynamic states for a single +item column, not the item as a whole. If \fIstateDescList\fR is unspecified, +this command returns a list containing the names of all the dynamic states +which are switched on in \fIcolumn\fR. .TP \fIpathName\fR \fBitem state get\fR \fIitemDesc\fR ?\fIstateName\fR? If no \fIstateName\fR is specified, returns a list containing -the names of all (predefined and user defined) states +the names of all (static and dynamic) states which are currently switched on for the item described by \fIitemDesc\fR. If a \fIstateName\fR is specified, 1 is returned if the specified state is currently switched on for the item, 0 otherwise. .TP -\fIpathName\fR \fBitem state set\fR \fIitemDesc\fR ?\fIlastItem\fR? ?\fIstateDescList\fR? +\fIpathName\fR \fBitem state set\fR \fIitemDesc\fR ?\fIlastItem\fR? \fIstateDescList\fR Every element of \fIstateDescList\fR -must describe a user defined state (see \fBSTATES\fR below), -with the particularity that the state name may have also a leading \fB~\fR. +must be the name of a dynamic state (see \fBSTATES\fR below), +optionally preceded by a \fB~\fR or \fB!\fR character. Every state with a leading \fB!\fR will be switched off for the item described by \fIitemDesc\fR, every state with a leading \fB~\fR will be toggled, and every state without leading \fB!\fR or \fB~\fR will be switched on. If \fIlastItem\fR is specified, the state changes will be made for all items in the range betwen \fIitemDesc\fR and \fIlastItem\fR. -\fIItemDesc\fR may be the string \fBall\fR, +If \fIItemDesc\fR is the string \fBall\fR, then the state changes are made for all items of the treectrl widget. .RE .TP @@ -1842,9 +1838,10 @@ The following forms of the command are supported: .RS .TP \fIpathName\fR \fBitem style elements\fR \fIitemDesc\fR \fIcolumn\fR -A list is returned -containing the currently defined elements of the style, -which is set for the item described by \fIitemDesc\fR in \fIcolumn\fR. +This command returns a list containing the names of elements which were +configured by the \fBitem element configure\fR command for the item +described by \fIitemDesc\fR in \fIcolumn\fR. If there is no style assigned +to \fIcolumn\fR an error is returned. .TP \fIpathName\fR \fBitem style map\fR \fIitemDesc\fR \fIcolumn\fR \fIstyle\fR \fImap\fR Like the \fBitem style set\fR command, this command may be used to assign a @@ -2139,17 +2136,17 @@ Deprecated. Use the \fBcolumn count\fR command instead. Deprecated. Use the \fBitem count\fR command instead. .TP \fIpathName\fR \fBorphans\fR -Returns a list containing the numerical ids of all items -which has no parent item. -An item is created without having a parent, -and can later become an orphan again -by means of the \fBitem remove\fR widget command. +Returns a list containing the item ids of all items +which have no parent. +When an item is created, it has no parent by default, +and can later become an orphan +by means of the \fBitem remove\fR widget command. The root item is not returned. .TP \fIpathName\fR \fBrange\fR \fIfirst\fR \fIlast\fR Deprecated. Use the \fBitem range\fR command instead. .TP \fIpathName\fR \fBstate\fR \fIoption\fR ?\fIstateName\fR? -This command is used to manipulate the list of user defined states, +This command is used to manipulate the list of user-defined states, see section \fBSTATES\fR below. The exact behavior of the command depends on the \fIoption\fR argument that follows the \fBstate\fR argument. @@ -2158,20 +2155,20 @@ The following forms of the command are supported: .TP \fIpathName\fR \fBstate define\fR \fIstateName\fR Defines a new state with the name \fIstateName\fR, -which must not be the name of a predefined or already user defined state. +which must not be the name of an existing state. .TP \fIpathName\fR \fBstate linkage\fR \fIstateName\fR Returns a string indicating -whether the specified state is user defined +whether the specified state is user-defined by means of the \fBstate define\fR widget command (\fBdynamic\fR) or predefined by the treectrl widget itself (\fBstatic\fR). .TP \fIpathName\fR \fBstate names\fR -Returns a list containing the names of all user defined states. +Returns a list containing the names of all user-defined states. .TP \fIpathName\fR \fBstate undefine\fR ?\fIstateName ...\fR? -Every \fIstateName\fR must be the name of a user defined state. -Removes this state from the list of user defined states. +Every \fIstateName\fR must be the name of a user-defined state. +Removes this state from the list of user-defined states. .RE .TP \fIpathName\fR \fBsee\fR \fIitemDesc\fR @@ -2189,13 +2186,14 @@ It has several forms, depending on \fIoption\fR: .TP \fIpathName\fR \fBselection add\fR \fIfirst\fR ?\fIlast\fR? \fIFirst\fR and \fIlast\fR (if specified) -must be the string \fBall\fR or an \fIitemDesc\fR. -Selects all of the items in the range between -\fIfirst\fR and \fIlast\fR, inclusive, +must be the string \fBall\fR or a valid \fBitem description\fR. +Adds every unselected item in the range between +\fIfirst\fR and \fIlast\fR, inclusive, to the selection without affecting the selection state of items outside that range. If one of the arguments is the string \fBall\fR, -all items of the treectrl widget are added to the selection instead. -A \fB<Selection>\fR event is generated. +every unselected item in the treectrl widget is added to the selection. +A \fB<Selection>\fR event is generated if any items were added to the +selection. .TP \fIpathName\fR \fBselection anchor\fR ?\fIitemDesc\fR? If \fIitemDesc\fR is specified, @@ -2208,44 +2206,42 @@ Returns the numerical id of the selection anchor item. .TP \fIpathName\fR \fBselection clear\fR ?\fIfirst\fR? ?\fIlast\fR? \fIFirst\fR and \fIlast\fR (if specified) -must be the string \fBall\fR or an \fIitemDesc\fR. +must be the string \fBall\fR or a valid \fBitem description\fR. If any of the items between \fIfirst\fR and \fIlast\fR (inclusive) are selected, they are deselected. The selection state is not changed for items outside this range. -If no additional arguments is given -or one of the arguments is the string \fBall\fR, -the selection is completely cleared instead. -A \fB<Selection>\fR event is generated. +If no additional arguments are given, +or if one of the arguments is the string \fBall\fR, +then all items are removed from the selection. +A \fB<Selection>\fR event is generated if any items were removed from the +selection. .TP \fIpathName\fR \fBselection count\fR Returns an integer indicating the number of items in the treectrl that are currently selected. .TP \fIpathName\fR \fBselection get\fR -Returns a list containing the numerical ids of +Returns a list containing the item ids of all of the items in the treectrl that are currently selected. If there are no items selected in the treectrl then an empty string is returned. .TP \fIpathName\fR \fBselection includes\fR \fIitemDesc\fR -Returns 1 if the item indicated by \fIitemDesc\fR is currently +Returns 1 if the item described by \fIitemDesc\fR is currently selected, 0 if it isn't. .TP \fIpathName\fR \fBselection modify\fR \fIselect\fR \fIdeselect\fR Both arguments \fIselect\fR and \fIdeselect\fR must be -the string \fBall\fR or a possibly empty list of \fIitemDesc\fRs. -Selects all of the items described by \fIselect\fR, -then deselects all items described by \fIdeselect\fR, -without affecting the selection state of any item -not mentioned in both arguments. -If one item is described in both arguments \fIselect\fR and \fIdeselect\fR, -it is added to the selection. -A \fB<Selection>\fR event is generated. +the string \fBall\fR or a possibly-empty list of \fBitem descriptions\fR. +Any unselected items in \fIselect\fR are added to the selection, +and any selected items in \fIdeselect\fR are removed from the selection (except +for those items which are also in \fIselect\fR). +A \fB<Selection>\fR event is generated if any items were selected or deselected. .RE .TP \fIpathName\fR \fBstyle\fR \fIoption\fR ?\fIelement\fR? ?\fIarg arg ...\fR? -This command is used to manipulate styles, which could be considered -as a geometry manager for the elements of one item. +This command is used to manipulate styles, which can be thought of +as a geometry manager for elements. The exact behavior of the command depends on the \fIoption\fR argument that follows the \fBstyle\fR argument. The following forms of the command are supported: @@ -2526,8 +2522,7 @@ do not use item state names. The following options are supported for columns: .TP \fB\fB-arrow\fR\fR \fIdirection\fR -Indicates whether or not an arrow should be drawn in the column header -to the right of the column title. +Indicates whether or not an arrow should be drawn in the column header. \fIDirection\fR must have one of the values \fBnone\fR (the default), \fBup\fR, or \fBdown\fR. .TP @@ -2541,7 +2536,7 @@ use to draw the arrow if this column's -arrow option is not \fBnone\fR. If an image is specified for a certain state, it overrides the -arrowbitmap option. .TP \fB\fB-arrowside\fR\fR \fIside\fR -Indicates on which side an arrow should be drawn, if at all. +Indicates on which side of the bitmap/image/text the arrow should be drawn. \fISide\fR must be either \fBleft\fR or \fBright\fR (the default). .TP \fB\fB-arrowgravity\fR\fR \fIside\fR @@ -2551,7 +2546,7 @@ if there is more space available for drawing the arrow then needed. .TP \fB\fB-arrowpadx\fR\fR \fIamount\fR \fIAmount\fR specifies how much padding to -leave on the left and right side of the arrow. +leave on the left and right of the arrow. \fIAmount\fR may be a list of two values to specify padding for left and right separately; it defaults to 6. @@ -2597,21 +2592,21 @@ This option overrides the \fB-bitmap\fR column option. .TP \fB\fB-imagepadx\fR\fR \fIamount\fR \fIAmount\fR specifies how much padding to -leave on the left and right side of the image. +leave on the left and right of the image (or bitmap). \fIAmount\fR may be a list of two values to specify padding for left and right separately; it defaults to 6. .TP \fB\fB-imagepady\fR\fR \fIamount\fR \fIAmount\fR specifies how much padding to -leave on the top and bottom of the image. +leave on the top and bottom of the image (or bitmap). \fIAmount\fR may be a list of two values to specify padding for top and bottom separately; it defaults to 0. .TP \fB\fB-itembackground\fR\fR \fIcolorList\fR -Specifies a list of colors, which should be used as -alternating background color for the items of this column. +Specifies a list of zero or more colors, which are used as +alternating background colors for items in this column. See also the \fB-backgroundmode\fR widget option for more on this. .TP \fB\fB-justify\fR\fR \fIjustification\fR @@ -2653,7 +2648,7 @@ Defines a unique name for the column which can be used whenever a column must be specified. .TP \fB\fB-text\fR\fR \fItext\fR -Specifies a text to be displayed inside the column title. +Specifies a text string to be displayed as the column title. .TP \fB\fB-textcolor\fR\fR \fIcolor\fR Specifies a color, which should be used as foreground color @@ -2670,7 +2665,7 @@ of text. .TP \fB\fB-textpadx\fR\fR \fIamount\fR \fIAmount\fR specifies how much padding to -leave on the left and right side of the text. +leave on the left and right of the text. \fIAmount\fR may be a list of two values to specify padding for left and right separately; it defaults to 6. @@ -2750,16 +2745,15 @@ is true. Use the column to the left, or the column to the left whose -visible option is true. .SH "STATES" -A state consists basically of just a string: its \fIstateName\fR. -For every item a set of these states is managed, -which means that every item can have every state switched on or off. +For every item a set of boolean states is managed. These states play an +integral role in the appearance of each item. The following states are predefined for every item: .TP \fBactive\fR -At every time this state is set for exactly one item, -which therefore is called the active item. +At all times this state is set for exactly one item. The active item is +used with keyboard navigation. When the treectrl widget is created or when the active item is deleted, -the root item will become the active element. +the root item will become the active item. This state can be modified by means of the widget command \fBactivate\fR. .TP \fBenabled\fR @@ -2768,9 +2762,9 @@ It cannot be modified. .TP \fBfocus\fR This state is set for every item, -if the treectrl widget has currently the focus. +if the treectrl widget currently has the focus. It cannot be modified by means of a widget command, -but is maintained as reaction of a <FocusIn> or <FocusOut> event. +but is maintained in reaction to the <FocusIn> and <FocusOut> events. .TP \fBopen\fR If this state is switched on, @@ -2779,28 +2773,16 @@ the descendants of the item are displayed If this state is switched off, the descendants of the item are not displayed - the item is collapsed. -For a new item this state is switched on. -It can be modified by means of the widget commands +For a new item this state is switched on by default. +This state can be modified by means of the widget commands \fBitem expand\fR, \fBitem collapse\fR, or \fBitem toggle\fR. .TP \fBselected\fR -This state is set for every item, which is included in the selection. +This state is set for every item included in the selection. It can be modified by means of the widget command \fBselection\fR. .PP By means of the \fBstate define\fR widget command -up to 27 additional \fIstateName\fRs can be defined. -.PP -Some widget commands expect a \fIstateDesc\fR argument, -which is a \fIstateName\fR -optionally preceded by an exclamation mark (\fB!\fR). -If the \fIstateName\fR has no leading \fB!\fR -it describes a currently switched on state, -if it has a leading \fB!\fR it describes a currently switched off state. -.PP -Some widget commands expect a \fIstatePattern\fR argument, -which should be a non empty list of \fIstateDesc\fRs. -The pattern matches, if for every element of the list -the \fIstateDesc\fR describes the same state as the item currently has. +up to 27 additional states can be defined. .SH "PER-STATE OPTIONS" The visual appearance of an item can change depending on the state the item is in, such as being the active item, being included in the selection, being @@ -3145,6 +3127,9 @@ Indicates the item nearest to the point given by \fIx\fR and \fIy\fR. .TP \fBrnc\fR \fIrow column\fR Indicates the item in the given \fIrow\fR and \fIcolumn\fR. +The row and column corresponds to +the on-screen arrangement of items as determined by the -orient and -wrap +options. You can memorize \fBrnc\fR as abbreviation of "row 'n' column". .TP \fBroot\fR |