NAME

hwtk::treectrl - Create and manipulate hierarchical multicolumn widgets

 

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.

 

SYNOPSIS

hwtk::treectrl - pathName ?option value? ...

 

STANDARD OPTIONS

-clientdata, clientData, ClientData

-height, height, Height

-helpcommand, helpcommand, Command

-relief, relief, Relief

-width, width, Width

 

WIDGET-SPECIFIC OPTIONS

 

Command-Line Name: -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.

 

Command-Line Name: -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.

 

Command-Line Name: -listener

Database Name: listener

Database Class: ActionListener

Action listener object. User can derive hwtk::interface::HWTreectrllistener and create class where user can overwrite the methods for all actions (events like Selection, ButtonPress, KeyPress, and so on).

 

Command-Line Name: -menu

Database Name: menu

Database Class: Menu

Context menu posted for RMB (Right Mouse Button) on tree control.

 

Command-Line Name: -selectcommand

Database Name: selectcommand

Database Class: Command

Tcl script executed on selection in the tree control.

%-char substitutions are:

 

Command-Line Name: -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.

 

Command-Line Name: -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.

 

Command-Line Name: -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.

 

Command-Line Name: -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+.

 

Command-Line Name: -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.

 

Command-Line Name: -stripes

Database Name: stripes

Database Class: Stripes

Sets the background stripes. default is true.

 

Command-Line Name: -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.

 

 

WIDGET COMMAND

In addition to the standard configure, cget, identify, instate, and state commands, treectrl support the following additional widget commands:

 

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 section `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. by 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 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 combo box the drop-down values are retrieved 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 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” apir

 

pathName item create ?option value ...?

Creates some new items and optionally returns a list of unique identifiers for those items. The new items have the states open and enabled set by default. If the treectrl widget currently has the focus, the state focus is also set.

 

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 decribe 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 typecget name option

Returns the property of the editor given type. valid options are

-class, -displaytype

 

pathName types

Returns the list of editors available (both standard and registered) in the widget.

 

EXAMPLES

 

hwtk::dialog .dlg -title "hwtk::treectrl - demo"

set recess [.dlg recess]

set tree [hwtk::treectrl $recess.tree -stripes true -showroot no]

pack $tree -expand true -fill both;

 

# create elements for entities column

$tree element create entityimage image;

$tree element create entitycheck boolcheck -editable 1

$tree element create entityname combobox -editable 1 -valuelistcommand ::tree::GetValues -valueacceptcommand ::tree::UpdateCommand

# create elements and styles for id column

$tree element create elemid text -editable 1

# create elements and styles for color column

$tree element create elemcolor intcolor -editable 1

# create elements and styles for boolean column

$tree element create elemcheck boolcheck -editable 1

# create elements and styles for file column

$tree element create elemfile filesave -editable 1

 

$tree column create entities -text Entities -expand 0 -elements {entityimage entitycheck entityname};

$tree column create id -text Id -sort true -itemjustify right -sort false -expand 0 -elements {elemid}

$tree column create color -image palette-16.png -itemjustify center -justify center -expand 0 -elements {elemcolor};

$tree column create bool -text check -itemjustify center -justify center -expand 0 -elements {elemcheck};

$tree column create file -text File -itemjustify left -justify left -expand 0 -elements {elemfile};

 

set images {entityCards-16.png entityIncludes-16.png entityMaterials-16.png entityNodes-16.png entitySets-16.png}

 

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

    $tree item create -parent [expr {int(rand()*$i)}] -values [list entityimage $im  entityname $im entitycheck 1 elemid $i elemcolor $_i elemcheck 1 elemfile [pwd]]

}

 

.dlg post;

 

#hwtk::treectrl