What's New in TkTreeCtrl 2.2

Item Command

Arguments/Result Changed	What changed
item count	New option -visible added to return the number of items that are displayed (i.e., those whose ancestors are all expanded etc).
item create	New option -tags specifies an initial list of tags for created items.
item id	Returns a list of item ids if the item description matches multiple items.
New	Comment
item descendants	Returns the ids of the children, grandchildren, etc of an item.
item enabled	Gets and sets the enabled state for items. All items are enabled when first created. Disabled items cannot be selected, and are ignored by the default key-navigation bindings.

Tag Command

New	Comment
tag add	Add tags to items. For example: .t tag add all {a b c} will add tags "a", "b" and "c" to every item.
tag expr	Evaluate a tag expression against items. For example: .t tag expr $item a returns 1 if an item has tag "a". Also: .t tag expr $item a\|\|b returns 1 if an item has tag "a" or "b".
tag names	Return a list of tag names assigned to items. For example: .t tag names $item returns the tag list for an item, and: .t tag names all returns every tag assigned to any item.
tag remove	Remove tags from items. For example: .t tag remove all {b c} will remove tags "b" and "c" from any items that have them.

Item Tags

Tags are textual labels applied to items to group them together. Tags do not affect the appearance or behaviour of items. Tags can be used in item descriptions to operate on multiple items. More information can be found in the man page.

Window Element

Window elements can now be properly clipped so they don't draw over the column header, borders, or outside the bounds of the item columns they occupy. This is accomplished by making the window you want to display a child of a borderless frame widget, and setting the new -clip option of the window element to TRUE. So if your program displays a canvas widget in a window element, you would change this code:

set canvas [canvas .t.canvas ...]
.t item element configure $item $column myElement -window $canvas

to this:

set frame [frame .t.clip -borderwidth 0]
set canvas [canvas $frame.canvas ...]
.t item element configure $item $column myElement -window $frame -clip yes

The -clip option tells the window element to manage the geometry of both the -window widget (i.e, the frame) and its first child widget (i.e., the canvas). In this case, the frame widget is kept sized and positioned so that it is never out-of-bounds. You can see this in the "Big List" and "Firefox Privacy" demos.

Item Descriptions

New keywords were added to allow multiple items to be specified by an item description:

The keyword list specifies a list of other item descriptions:
```
.t item id "list [list $a $b $c]"
```
The keyword range operates like the item range command:
```
.t item id "range $first $last"
```
The keyword tag matches any items that meet a tag expression:
```
.t item id "tag $tagExpr"
```

New modifiers were added to match multiple items:

The modifier ancestors operates like the item ancestors command:
```
.t item id "$item ancestors"
```
The modifier children operates like the item children command:
```
.t item id "$item children"
```
The modifier descendants operates like the item descendants command:
```
.t item id "$item descendants"
```

New qualifiers were added to refine which items are matched:

The qualifier !visible matches items that are not displayed:

.t item id "first !visible" ; # find the first item that is not displayed

The qualifier state matches items that have certain states set (or not set if '!' is used):

.t item id "first state {selected !open}" ; # find the first item that is selected and collapsed

The qualifier tag matches items that meet a tag expression:

.t item id "$item children tag $tagExpr" ; # find children of $item that have certain tags

Also, the keyword all may now be followed by a list of qualifiers: For example:

.t item id "all !visible state myState" ; # find every item that is not displayed with user-defined state "myState"

The following commands can now operate on multiple items in a single call:

item configure
item element configure
item id
item image
item style map
item style set
item state forcolumn
item state set
item remove
item span
item text

Demo Changes

New demo "My Computer". Demonstrates disabled items used as headers.

Bug Fixes

item create: Fixed bug where -nextsibling and -prevsibling options could specify an orphan item.
item delete: Stopped items possibly being double-deleted by nested calls through <Selection> and <ItemDelete> binding scripts.
item expand, item collapse, item toggle: Only operate on items which exist when the command is called, not any that might get created by <Expand> or <Collapse> binding scripts.
When a style with window elements spanned more than one column, the window might be improperly sized during display updates.

What's New in TkTreeCtrl 2.1.1

Column Command

Arguments/Result Changed	What changed
column delete	Added an optional second argument allowing a range of columns to be deleted.

Bug Fixes

The item sort command will be much faster in many cases. There was a silly error in the pivot-finding code of quicksort which resulted in the slow-down.
A column header will be redisplayed if an image in the header is altered.
Fixed bus errors on some Unix systems due to alignment problems.

Other Changes

The Tk caret is now positioned over the active item when it changes. The Tk caret is used for the Magnifier accessibility application and IME on Windows, as well as XIM under Unix.
Improved the appearance of the column headers under OSX.
Added <MouseWheel> support to OSX.
Changing the -visible option of an item could be slow if any items were selected. That is because non-visible items may not be part of the selection. A change was made so that changes to the selection caused by modifying the -visible option of an item do not occur until the next display update.

Demo Changes

New demo "Column Spanning". Demonstrates a 100-column list where styles span from 1 to 20 columns each.
The loupe command (which performs screen capture to an image) is now implemented on Windows and OSX thanks to Jeff Hobbs.
The screen-magnifier image now resizes with the "loupe" window.

What's New in TkTreeCtrl 2.1

This version should be backwards compatible with 2.0, except for a few obscure changes.

TreeCtrl Configuration Options

New	Comment
-itemwidth
-itemwidthequal	Deprecates the column -widthhack option.
-itemwidthmultiple	Deprecates the column -stepwidth option.

Column Configuration Options

Deprecated	What to use instead
-stepwidth	treectrl's -itemwidthmultiple option
-widthhack	treectrl's -itemwidthequal option

Element Command

New	Comment
element perstate	Like [item element perstate].

Item Configuration Options

New	Comment
-height	Overrides the treectrl's -itemheight option

Item Command

Deprecated	What to use instead
item element actual	item element perstate
item complex	item element configure
Behaviour Changed	What changed
item bbox	No longer returns an error if no style had been assigned to the column.
item state forcolumn	No longer returns an error if no style had been assigned to the column.
item style set	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. Potential incompatibility
Arguments/Result Changed	What changed
item create	Added options: -count -height, -nextsibling, -open, -parent, -prevsibling, and -returnid. Multiple items may be created with one call using the -count option.
item element configure	Multiple elements in multiple columns may be configured with a single call. Use '+' to separate elements, and ',' to separate columns. See the docs.
item style set	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). Potential incompatibility
item text	When no column is specified, returns a list of one string per column.
New	Comment
item image	Partner to the [item text] command.
item element perstate	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. The following options no longer return a default value if the per-state option itself does not have a value specified: bitmap -foreground, -background border -relief text -fill, -font Potential incompatibility
item span	A style may now be displayed over multiple adjacent columns.

Notify Command

New	Comment
notify unbind	Let's you unbind all scripts from an object with one call.

Style Layout Changes

Column justification will now affect the position of elements in 2 situations which previously had no effect (Potential incompatibility):

If a -detach element had a fixed width larger than the other elements.
If an element had -iexpand x specified as well as -maxwidth, leaving some space available.

Element Changes

Bitmap, image and text elements are drawn clipped if given less space than they need.
Fixed line wrapping of text elements. It did not work for single lines of text at all (Potential incompatibility).
The text -wrap option can now be none to disable line wrapping.

Event Changes

The new static event <ItemVisibility> 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 SUBSTITUTIONS section in the help file, and the new demo "Big List".

Other Changes

On WinXP, the column header sort arrow is drawn like Explorer draws it if -usetheme is true.

Demo Changes

New demo "Big List". Demonstrates the new <ItemVisibility> event, using <Expand-before> to add items on demand, and column spanning.
The context menu has a Span submenu that lets you manipulate column spanning in items. See the item span command in the help file.
Under WinXP, the "Explorer" demos will use the new shellicon 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.

What's New in TkTreeCtrl 2.0

TreeCtrl Configuration Options

Replaced	What to use instead
-openbuttonimage	-buttonimage
-closedbuttonimage	-buttonimage
-openbuttonbitmap	-buttonbitmap
-closedbuttonbitmap	-buttonbitmap
Usage Changed	How it changed
-backgroundmode	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 agreement with the new "item order" command which replaces the "item index" command.
-treecolumn	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 buttons/lines.
New
-backgroundimage
-columnprefix
-columnresizemode
-itemprefix
-minitemheight
-usetheme

TreeCtrl Commands

Deprecated	What to use instead
compare	item compare
index	item id
numcolumns	column count
numitems	item count
range	item range

Column Configuration Options

Removed	What to use instead
-relief	-state
-sunken	-state
Renamed	New name
-arrowpad	-arrowpadx
Usage Changed	How it changed
-background	This is now a per-state option. See COLUMNS in the help file for valid state names.
New
-arrowbitmap
-arrowimage
-arrowpady
-maxwidth
-resize
-state
-textlines

Column Command

Deprecated	What to use instead
column index	column id
Arguments/Result Changed	What changed
column configure	A column description of "all" is allowed if at least one option-value pair is given.
column create	The result is a unique identifier. Previously the result was an index in the list of columns.
column delete	A column description of "all" is allowed.
New	Comment
column compare
column count	replaces "numcolumns"
column dragconfigure
column dragcget
column id	replaces "column index"
column list
column order

Item Command

Removed	What to use instead
item index	item order
New	Comment
item compare	replaces "compare"
item count	replaces "numitems"
item id	replaces "index"
item order	replaces "item index"
item range	replaces "range"

Notify Command

Arguments/Result Changed	What changed
notify generate	Added optional percentsCommand argument
notify install	Old syntax (supported but deprecated): notify install event eventName notify install detail eventName detail New syntax: notify install <eventName> notify install <eventName-detail>
notify linkage	Old syntax (supported but deprecated): notify linkage eventName notify linkage eventName detail New syntax: notify linkage <eventName> notify linkage <eventName-detail>
notify uninstall	see notify install above

Style Layout Options

Usage Changed	How it changed
-iexpand	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 update your code, you will probably want to change this: $T style layout $S $E -iexpand we to this: $T style layout $S $E -iexpand x 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.
New
-height
-maxheight
-maxwidth
-minheight
-minwidth
-sticky
-width

Element Changes

A new element type window was added. See the new demo "Firefox Privacy" and the ELEMENTS section in the help file.
All element types have a new per-state boolean option called -draw.
The text element type has a new option called -textvariable. See the new demo "Textvariable" and the ELEMENTS section in the help file.

Event Changes

2 new %-substitution characters %P and %? are allowed in binding scripts. See the EVENTS AND SCRIPT SUBSTITUTIONS section in the help file.
The new static event <ItemDelete> is generated when items are deleted. See the EVENTS AND SCRIPT SUBSTITUTIONS section in the help file.

Library Script Changes

filelist-bindings.tcl:

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.
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.
Two new dynamic events <Edit-begin> and <Edit-end> are generated when editing a file name.

treectrl.tcl:

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.

Other Changes

On WinXP, the column headers and open/close buttons are drawn using the system theme if -usetheme is true. The sort arrow is drawn the old-fashioned way.
On OSX/Aqua, the column headers and open/close buttons are drawn using the system theme if -usetheme is true. The sort arrow will be drawn by the Appearance Manager as well. This will override the -arrowside and -arrowgravity options.
Columns can be moved by drag-and-drop. See column dragconfigure in the help file.
Columns can be specified in new ways. See the COLUMN DESCRIPTION section in the help file.
Added new section DYNAMIC EVENTS to the help file.
Added new section PER-STATE OPTIONS to the help file.
The new style layout option -indent allows elements to be displayed in the button/line area. See the style layout command in the help file and the new demo "Firefox Privacy".
The new item description end is equivalent to last.
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). Otherwise the old pkgIndex.tcl file will set the TREECTRL_LIBRARY variable which will override where the library scripts are found.

Demo Changes

New demo "Firefox Privacy". Demonstrates the new window element type and -indent style layout option.
New demo "Textvariable". Demonstrates the new -textvariable option of the text element.
Added a new Event Browser window to display events generated by the main treectrl widget.
The context menu can be popped up in all the demo lists. A <Control-ButtonPress-1> binding for this was added under OSX/Aqua.
In the "Explorer" demos, the file name is hidden while editing the file name.