Itcl Treemap Widget

The treemap widget displays a tree hierarchy in a limited space, without the need for scrollbars. Each node of the tree is represented by an rectangular space, with a name at the top. A node's subtrees are laid out inside the node's display-space, and the amount of space allotted to each subtree is proportional to its weight - the ratio between the number of nodes in the subtree and the number of nodes in the entire tree.

Each node of the tree is assigned a node-ID which can be used to manipulate the node via the widget command. Nodes can have their configuration options changed, event-handlers bound on them and can be expanded and pruned.

Nodes are added to the tree by supplying a Tcl command to create the children of the root node. This command is appended with the node-ID of the parent node which should be passed as a parameter to the "create_node" widget-command in order to create a new node. By giving a new create_children command as one of the node configuration options, one can specify how to create the children of the new node.

The node hierarchy can be queried through the "root", "parent" and "children" widget commands.

Synopsis

treemap pathName ?options?
create a new treemap widget named pathName.
pathName option ?args...?
manipulate the treemap widget name pathName.

Options

Name: width
Class: Width
Command-Line Switch: -width
Default: 10c
Specifies the width of the widget in screen units.

Name: height
Class: Height
Command-Line Switch: -height
Default: 10c
Specifies the height of the widget in screen units.

Name: orient
Class: Orient
Command-Line Switch: -orient
Default: vertical
Specifies the orientation in which the treemap draws its toplevel nodes. If "horizontal", the nodes are layed out left to right across the available space. If "vertical", the nodes are layed top to bottom vertically across the available space. Child child nodes are created with the opposite orientation to their parents.

Name: font
Class: Font
Command-Line Switch: -font
Default: -*-clean-medium-r-*-*-8-*-*-*-*-*-*-*
Specifies the font in which the names of each node is drawn.

Name: relief
Class: Relief
Command-Line Switch: -relief
Default: sunken
Specifies the relief in which the root node of the treemap is drawn.

Name: borderWidth
Class: BorderWidth
Command-Line Switch: -borderwidth
Default: 1
Specifies the borderwidth with which the root node of the treemap is drawn.

Name: name
Class: Name
Command-Line Switch: -name
Default: ""
Specifies the string drawn above the subnodes of the root of the treemap.

Name: nameAnchor
Class: NameAnchor
Command-Line Switch: -nameanchor
Default: w
Specifies the side of the name-label on which the root-node's name is drawn. Can be one of n, ne, e, se, s, sw, w, nw. See the Tk documentation for the anchor option for more details.

Name: depth
Class: Depth
Command-Line Switch: -depth
Default: 4
Specifies the depth to which the treemap will recurse when building the child-nodes via the create-children command. Nodes which are not expanded because their children lie below the depth so specified are displayed in the pruned- Background and prunedForeground colours. If this is set after the treemap has been created, via the configure widget command, it causes the treemap to be recalculated and redrawn with the new depth.

Name: background
Class: Background
Command-Line Switch: -background
Default: #ccc
Specifies the colour in which the nodes of the treemap are filled. Also used to determine the highlight/lowlight colours for the 3D borders of the nodes.

Name: foreground
Class: Foreground
Command-Line Switch: -foreground
Default: black
Specifies the colour in which the names of the nodes of the treemap are drawn.

Name: prunedBackground
Class: PrunedBackground
Command-Line Switch: -prunedbackground
Default: skyblue
Specifies the colour in which pruned nodes of the treemap are filled. Also used to determine the highlight/lowlight colours for the 3D borders of pruned nodes.

Name: prunedForeground
Class: PrunedForeground
Command-Line Switch: -prunedforeground
Default: black
Specifies the colour in which the names of pruned nodes of the treemap are drawn.

Name: none
Class: none
Command-Line Switch: -createchildrencommand
Specifies a Tcl command which is executed to create the children of a node. The command is appended with the node-ID of the parent node before execution. If this is set after the treemap has been created, via the configure widget command, it causes the treemap to be recalculated and redrawn.

Widget Command

pathName configure option value ?option value ...?
Configure the widget by changing one or more of its public variables.

pathName root
Return the node-ID of the root of the tree.

pathName parent node-ID
Return the node-ID of the parent of the node with the given ID, or the empty string if the node is the root of the tree.

pathName children node-ID
Return a list containing the node-IDs of the children of the node with the given ID.

pathName create_node parent ?options...?
Create a subnode of the given node and configure it with the given options. Allowable node configuration options are: These options act in the same way as the widget options of the same name.

pathName nodeconfigure node-ID
Configure the node with the given node ID.

pathName bind node-ID> event handler
Bind a Tcl script to be executed when the given event occurs on the node with the given ID. The handler is executed in the global scope.

pathName toggle node-ID
If the node with the given ID is pruned, then expand the node by a single level. Otherwise, prune the node by removing all it's children and colouring with the prunedBackground and prunedForeground colours. Toggling a node will cause the layout of the tree to be recalculated.

Bindings

By default, pressing Button-3 on a node expands or prunes that node. This binding can be overridden via the "bind" widget command.


Nat Pryce (np2@doc.ic.ac.uk)