hwtk::treectrl

Create and manipulate hierarchical multicolumn widgets.

Format

hwtk::treectrl - pathName ?option value? …

Description

The treectrl command creates a new window (given by the pathName argument) and makes it into a treectrl widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the treectrl such as its background color and relief. The treectrl command returns the path name of the new window. At the time this command is invoked, there must not exist a window named pathName, but pathName’s parent must exist.

A treectrl is a listbox widget which displays items in a one- or two-dimensional arrangement. Items have a parent-child relationship with other items. Items may be arranged from top-to-bottom or from left-to-right. Items may be spread about one or more columns. Each item-column may be configured to span one or more adjacent item-columns. The visibility of items can be set individually.

Items have a set of states, which are boolean properties. For each column of an item there is a style associated, which determines how to display the item’s column taking into account the item’s current state set. New states may be defined to further control the appearance of items; these custom states may be turned on or off in individual columns of items.

Multiple rows of column headers are supported. Column headers have platform-native appearance on Windows, Mac OS X, and Gtk+. The appearance of column headers may be customized using styles.

Columns may be rearranged by the user using drag-and-drop. One column can be specified to display the data in a hierarchical structure. The visibility of columns can be set individually.

A treectrl can display a user-resizable selection rectangle called the marquee. Another feature, the drag image, may be used to provide feedback during drag-and-drop operations. Both of these are features commonly found in file browsers.

A treectrl can generate events when various things happen, such as changes to the selection, or a parent item being toggled open or closed. Scripts may be bound to these events. New events can be defined.

A treectrl can display a background image. The background image can be configured to be scrolled and tiled on each axis individually.

Standard Options

-clientdata
Database name: clientData
Database class: ClientData
Acts as a data storage for a widgets. User can store any data and this will not have any effect on widget property.
-height
Database name: height
Database class: Height
If specified, the widget’s requested height in pixels.
-helpcommand
Database name: helpcommand
Database class: Command
Dynamic help which calls an assigned -helpcommand when the user moves the mouse on the widget. The text which is returned by the -helpcommand will be in turn be displayed on the tooltip.
-relief
Database name: relief
Database class: Relief
Specifies the 3D effect desired for the widget. Acceptable values are raised, sunken, flat, ridge, solid, and groove. The value indicates how the interior of the widget should appear relative to its exterior; for example, raised means the interior of the widget should appear to protrude from the screen, relative to the exterior of the widget.
-width
Database name: width
Database class: Width
Specifies the width of a widget.

Widget Specific Options

-backgroundimage
Database name: backgroundImage
Database class: BackgroundImage
Specifies the name of an image to draw as the list background. Other options control whether the image is tiled and whether the image scrolls. If the image is transparent it is drawn on top of any column -itembackground colors.
-closeeditor
Database name: closeEditor
Database class: CloseEditor
Boolean option when set to true, the editor unposts upon successful set value. Default is set to false.
-columndnd
Database name: columndnd
Database class: Dnd
Boolean value that, when true, allows columns to be dragged and dropped elsewhere. Defaults to false.
-itemdnd
Database name: itemdnd
Database class: Dnd
Boolean value that, when true, allows items to be dragged and dropped elsewhere. Defaults to true.
-listener
Database name: listener
Database class: ActionListener
Action listener object. You can derive hwtk::interface::HWTreectrllistener and create a class where you can overwrite the methods for all actions, such as events like Selection, ButtonPress, KeyPressetc...
-menu
Database name: menu
Database class: Menu
Context menu posted for RMB (Right Mouse Button) on tree control.
-selectcommand
Database name: selectcommand
Database class: Command
Tcl script executed on selection in the tree control
%-char substitutions are
  • %W widget path
  • %S selected items
  • %c count (number of items selected)
-selectmode
Database name: selectmode
Database class: SelectMode
Specifies one of several styles for manipulating the selection. The value of the option may be arbitrary, but the default bindings expect it to be either single, or extended; the default value is extended.
-showheader
Database name: showHeader
Database class: ShowHeader
Specifies a boolean value that determines whether this widget should display the header line with the column names at the top of the widget. The default value is true.
-showlines
Database name: showLines
Database class: ShowLines
Specifies a boolean value that determines whether this widget should draw the connecting lines between related items. The default value is true on Win32 and X11, false on Mac OS X and Gtk+.
-showroot
Database name: showRoot
Database class: ShowRoot
Specifies a boolean value that determines whether this widget should draw the root item. By suppressing the drawing of the root item the widget can have multiple items that appear as toplevel items. The default value is true.
-stripes
Database name: stripes
Database class: Stripes
Sets the background stripes. default is true.
-treecolumn
Database name: treeColumn
Database class: TreeColumn
Specifies a column description that determines which column displays the expand/collapse buttons and connecting lines between items. The default is unspecified. Defaults to first column.
-tristatesort
Database name: tristatesort
Database class: Sort
Boolean value that, when true, allows the use of the tristate sorting command specified in -tristatesortcommand for tristate sorting. Defaults to false.
-tristatesortcommand
Database name: tristateSortcommand
Database class: Command
The custom sorting command used to sort items when -tristatesort is true.

Widget Commands

pathName cget option
Returns the current value of the configuration option given by option.
pathName collapse itemDesc
Switches off the open state of the item(s) described by itemDesc. If an item has descendants, then they are no longer displayed. If an item is already closed, then this command has no effect on that item. For every item that actually will be collapsed, two events are generated: a <Collapse-before> event before the item state is changed, and a <Collapse-after> event after the item state was changed.
pathName column option column arg..?
This command is used to manipulate the columns of the treectrl widget (see COLUMN OPTIONS below). The exact behavior of the command depends on the option argument that follows the column argument. The following forms of the command are supported:
pathName column create ?option value ...?
This command creates a new column in the treectrl widget. The new column is placed to the right of all other columns (except the tail column). Any option-value arguments configure the new column according to the column configure command. The return value is the unique identifier of the new column.
-visible
Boolean|true
Show/hide the column display.
-sort
Boolean|true
Column sort enable/disable
-text
String | {}
Column header text
-image
imageName |{}
Column header image
-itemjustify
Direction|left
Items in the column will be justified according to the given value. Default is left.
-justify
justify|left
Justify the column header text.
-expand
Boolean|true
Indicates whether or not any extra horizontal space should be distributed to this column. This option has no effect if the -width option is set.
-elements
{}
List of element names in order in which the item renders the elements.
-width
Size|{}
Specifies a fixed width for the column.
-headermenu
menu|{}
Specified menu will be populated on right mouse click on column header.
-lock
None
This option allows a column to stick to the left or right edge of the window. A locked column scrolls vertically but not horizontally. Must be one of none (the default), left, or right.
pathName column configure columnDesc ?option? ?value? ?option value …?
This command is similar to the configure widget command except that it modifies options associated with the columns specified by the column description columnDesc instead of modifying options for the overall treectrl widget. ColumnDesc may be the string tail to specify the tail column.
pathName column cget columnDesc option
This command returns the current value of the option named option for the column specified by the column description columnDesc. ColumnDesc may also be the string tail to specify the tail column. Option may have any of the values accepted by the column configure widget command.
pathName column delete first ?last?
Deletes the specified column(s). First and last must be valid column descriptions. If both first and last are specified, then they may refer to a single column only. The tail column cannot be deleted and it is an error to specify it. The order of first and last doesn’t matter, and first may be equal to last.
pathName column id columnDesc
This command resolves the column description columnDesc into a list of unique column identifiers. If the column(s) described by columnDesc don’t exist, this command returns an empty list.
pathName column list ?-visible?
This command returns a list of identifiers for every column (except the tail) from left to right. If -visible is given, only columns whose -visible option is true are returned.
pathName component ?arg arg …?
Since hwtk::treectrl is a compound widget wrapped on top of treectrl, this command returns the internal path for treectrl widget.
pathName component treectrl
pathName configure ?option? ?value option value …?
Query or modify the configuration options of the widget. If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. If option is specified with no value, then the command returns a list describing the named option: the elements of the list are the option name, database name, database class, default value, and current value. If no option is specified, returns a list describing all of the available options for pathName.
pathName deselect ?first? ?last?
First and last (if specified) must be valid item descriptions. If both first and last are specified, then they may refer to a single item only; in this case any selected items between first and last (inclusive) are removed from the selection without affecting the selected state of items outside that range. If only first is specified, then every selected item specified by first is removed from the selection. If neither first nor last are specified, then all selected items are removed from the selection. A <Selection> event is generated if any items were removed from the selection.
pathName editorpost item column element
Posts the editor for the given item, column, and element.
pathName editorunpost
Unposts the editor.
pathName element option element arg …?
This command is used to manipulate elements. The exact behavior of the command depends on the option argument that follows the element argument. The following forms of the command are supported:
pathName element cget element option
This command returns the current value of the option named option associated with the element given by element. Option may have any of the values accepted by the element configure widget command.
pathName element configure element ?option? ?value? ?option value …?
This command is similar to the configure widget command except that it modifies options associated with the element given by element instead of modifying options for the overall treectrl widget. If no option is specified, the command returns a list describing all of the available options for element (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given option(s) to have the given value(s) in element; in this case the command returns an empty string.
pathName element create name type displayType ?option value …?
Creates a new master element of type type with the unique user-defined name name and configures it with zero or more option/value pairs. See the subsections on individual element types in ELEMENTS AND STYLES for the options that are valid for each type of element. This command returns the name of the new element (the same as the name argument).
-editable
Boolean|false
If it is true then, editor will be posted on element on left click.
-valuelistcommand
{}
This command information is passed to the editor. The editor get the values in case of combobox the dropdown values are retrived from this command.
-validatecommand
{}
This is a callback command for editor. This command is called when ever there is change in value for editor. user can implement validate business in this method.
-clientdata
This is kind of place holder for information to the editor.
-valueacceptcommand
{}
Its a use callback for editor and this will be called before committing the new values.
pathName expand itemDesc
Switches on the open state of the item(s) described by itemDesc. If an item has descendants, then they are now displayed. If an item is already open, then this command has no effect on that item.
pathName hide itemDesc
The item is not displayed and consumes no space in the layout.
pathName identify element x y
Returns the name of the element under the point given by x and y, or an empty string if the point does not lie within any element. x and y are pixel coordinates relative to the widget. Some widgets accept other identify subcommands.
pathName instate statespec ?script?
Test the widget’s state. If script is not specified, returns 1 if the widget state matches statespec and 0 otherwise. If script is specified, equivalent to
if{[pathNameinstatestateSpec]}script
pathName item option ?arg …?
This command is used to manipulate items. The exact behavior of the command depends on the option argument that follows the item argument. The following forms of the command are supported:
pathName item cget itemDesc option
Returns the current value of the configuration option for the item specified by itemDesc whose name is option. Option may have any of the values accepted by the item configure command.
pathName item children itemDesc
Returns a list containing the item ids of all children of the item specified by itemDesc in the correct order from the first child to the last child.
pathName item configure itemDesc ?option? ?value? ?option value ...?
If no option is specified, returns a list describing all of the available options for the item given by itemDesc (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified).
If one or more option-value pairs are specified, then the command modifies the given item option(s) to have the given value(s); in this case the command returns an empty string. This is the only case where itemDesc may refer to multiple items.
The following options are supported by this command (see item create for the meaning of each option):
-button
Boolean|auto
-tags
tagList
-values
"element value" pair
pathName item create ?option value …?
Deletes the specified item(s). First and last must be valid item descriptions. If last isn’t specified, then first may specify multiple items. If both first and last are specified, they must each describe a single item with a common ancestor; then the range of items between first and last is deleted. The order of first and last doesn’t matter.
Deleting an item deletes any child items of the deleted item recursively. If the current active item is deleted, the root item becomes the new active item. If the current selection 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.
For each call to this command, two events may be generated. If any of the deleted items are selected, then they are removed from the selection and a <Selection> event is generated just before the items are deleted. If any items are going to be deleted, then an <ItemDelete> event is generated just before the items are deleted.
pathName item delete first ?last?
Deletes the specified item(s). First and last must be valid item descriptions. If last isn’t specified, then first may specify multiple items. If both first and last are specified, they must each describe a single item with a common ancestor; then the range of items between first and last is deleted. The order of first and last doesn’t matter.
Deleting an item deletes any child items of the deleted item recursively. If the current active item is deleted, the root item becomes the new active item. If the current selection 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.
For each call to this command, two events may be generated. If any of the deleted items are selected, then they are removed from the selection and a <Selection> event is generated just before the items are deleted. If any items are going to be deleted, then an <ItemDelete> event is generated just before the items are deleted.
pathName item id itemDesc
This command resolves the item description itemDesc into a list of unique item identifiers. If itemDesc doesn’t refer to any existing items, then this command returns an empty list.
pathName registertype name className displayType
User can register a custom editor.
pathName see itemDesc
Adjusts the treectrl view so that the item specified by itemDesc is visible.
If the item is already visible in the list, this command has no effect; otherwise, the treectrl will scroll appropriately so that the item is visible.
pathName select ?itemDesc?
If any items supplied then the items will be added to the selection. if no arguments passed this will return the list of selected items.
pathName show ?itemDesc?
The item visibility is turned on and it consumes space in the layout.
pathName state ?stateSpec?
Modify or inquire widget state. If stateSpec is present, sets the widget state: for each flag in stateSpec, sets the corresponding flag or clears it if prefixed by an exclamation point. Returns a new state spec indicating which flags were changed:
setchanges[pathNamestatespec]
pathNamestate$changes
will restore pathName to the original state. If stateSpec is not specified, returns a list of the currently-enabled state flags.
pathName typecget name option
Returns the property of the editor given type. Valid options are -class, -displaytype.
pathName typelist
Returns the list of editors available (both standard and registered) in the widget.
pathName types
Same as typelist.

Example

hwtk::dialog .d -title "::hwtk::treectrl"
set d [.d recess]

set t [hwtk::treectrl $d.t -showroot no]
pack $t -expand true -fill both

$t element create entityimage image
$t element create entitycheck boolcheck -editable 1
$t element create entityname str -editable 0
$t element create elemid text -editable 1
$t element create elemcolor intcolor -editable 1
$t element create elemcheck boolcheck -editable 1
$t element create elemfile filesave -editable 1

$t column create entities -text Entity -elements {entityimage entitycheck entityname} -expand 0
$t column create id -text ID -sorttype integer -elements {elemid}
$t column create color -image palette-16.png -elements {elemcolor} -expand 0
$t column create bool -text Visibility -elements {elemcheck} -expand 0
$t column create file -text File -elements {elemfile}

set images {entityCards-16.png entityIncludes-16.png entityMaterials-16.png entityNodes-16.png entitySets-16.png}
puts [time {
    for {set i 1} {$i < 100} {incr i} {
        set _i [expr {int(rand()*60)}]
        set _i [expr {$_i ? $_i : 1}]
        set im [lindex $images [expr {int(rand()*5)}]]
        $d.t item create -parent [expr {int(rand()*$i)}] \
                         -values [list  entityimage $im \
                                        entityname $im \
                                        entitycheck 1 \
                                        elemid $i \
                                        elemcolor $_i \
                                        elemcheck 1 \
                                        elemfile [pwd]]
    }
}]

.d post