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
- -height
- Database name: height
- -helpcommand
- Database name: helpcommand
- -relief
- Database name: relief
- -width
- Database name: width
Widget Specific Options
- -backgroundimage
- Database name: backgroundImage
- -closeeditor
- Database name: closeEditor
- -columndnd
- Database name: columndnd
- -itemdnd
- Database name: itemdnd
- -listener
- Database name: listener
- -menu
- Database name: menu
- -selectcommand
- Database name: selectcommand
- -selectmode
- Database name: selectmode
- -showheader
- Database name: showHeader
- -showlines
- Database name: showLines
- -showroot
- Database name: showRoot
- -stripes
- Database name: stripes
- -treecolumn
- Database name: treeColumn
- -tristatesort
- Database name: tristatesort
- -tristatesortcommand
- Database name: tristateSortcommand
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
- -sort
- Boolean|true
- -text
- String | {}
- -image
- imageName |{}
- -itemjustify
- Direction|left
- -justify
- justify|left
- -expand
- Boolean|true
- -elements
- {}
- -width
- Size|{}
- -headermenu
- menu|{}
- -lock
- None
- 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 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
- -valuelistcommand
- {}
- -validatecommand
- {}
- -clientdata
- This is kind of place holder for information to the editor.
- -valueacceptcommand
- {}
- 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).
- 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.
- 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.
- 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.
- 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:
will restore pathName to the original state. If stateSpec is not specified, returns a list of the currently-enabled state flags.setchanges[pathNamestatespec]
pathNamestate$changes
- 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