gnocl::tree

A widget which displays text or other items arranged in a tree.

Synopsis

gnocl::tree [-option value...]

Screenshot

Options

-children list (default: "")
List of rows. Each row consists of a list of cell entries.
-columns integer
Number of columns
-enableSearch boolean
TO BE COMPLETED
-expanders boolean
TO BE COMPLETED
-fixedHeight boolean
TO BE COMPLETED
-hasFocus 1
This sets the focus to the widget. To unset the focus it must be set to another widget.
-headersClickable boolean (default: true)
Whether the headers are clickable.
-headersVisible boolean (default: true)
Whether to show the headers.
-heightGroup string (default: "")
The -heightGroup option can be an arbitrary string. All widgets with the same heightGroup request the same height. If packed with the fill flag set, they will have nevertheless different heights.
-heightRequest int
Height which is requested in the parent widget. The actual height can be larger.
-hoverExpand boolean
TO BE COMPLETED
-hoverSelection boolean
TO BE COMPLETED
-name string
Name of the widget, can be used to set options in an rc file.
-onButtonPress string (default: "")
Tcl command which is executed if a mouse button is press inside the widget. Before evaluation the following percent strings are substituted:

%w    widget name
%t    type of event: one of buttonPress, button2Press or button3Press
%x    x coordinate
%y    y coordinate
%b    button number
%s    state of the buttons and modifiers (bitmask)
-onButtonRelease string (default: "")
Tcl command which is executed if a mouse button is released inside the widget. Before evaluation the following percent strings are substituted:

%w    widget name
%t    type of event: always buttonRelease
%x    x coordinate
%y    y coordinate
%b    button number
%s    state of the buttons and modifiers (bitmask)
-onPopupMenu string (default: "")
Tcl command which is executed if the "popup-menu" signal is received, which is normally the case if the user presses Shift-F10. Before evaluation the following percent strings are substituted:

%w    widget name
-onRowCollapsed string (default: "")
Command to execute in the global scope if a row is collapsed. Before evaluation the following percent strings are substituted:

%w    widget name
%p    list of paths of the collapsed row
-onRowExpanded string (default: "")
Command to execute in the global scope if a row is expanded. Before evaluation the following percent strings are substituted:

%w    widget name
%p    list of paths of the expanded row
-onSelectionChanged string (default: "")
Command to execute in the global scope if the selection could be changed. Occasionally it is executed, if the selection has not changed. Therefore the "%p" parameter can also be the empty string, which is not a valid path. Before evaluation the following percent strings are substituted:

%w    widget name
%p    list of paths of the selection
-reorderable boolean
TO BE COMPLETED
-rubberband boolean
TO BE COMPLETED
-ruleHint boolean
TO BE COMPLETED
-selectionMode one of single, browse, multiple or extended
none
No selection is possible.

single 
None or one element may be selected.

browse 
Only one element is selected. Certain operations such as widget initialization or a search operation, may result in no element being selected. The user cannot deselect a currently selected element except by selecting another element.

multiple
Any number of elements may be selected. Clicks toggle the state of an item. Any number of elements may be selected. The Ctrl key may be used to enlarge the selection, and Shift key to select between the focus and the child pointed to. Some widgets may also allow Click-drag to select a range of elements.

extended
Deprecated, behaves identical to multiple.
-sizeGroup string (default: "")
The -sizeGroup option can be an arbitrary string. All widgets with the same sizeGroup request the same size. If packed with the fill flag set, they will have nevertheless different sizes.
-titles string (default: "")
Titles of the columns
-treeLines boolean
TO BE COMPLETED
-types one of boolean, integer, float, string, markup or  image (default: string)
Types of column entries. If type is markup the cell content is interpreted as markup-string. For special formatting of the other types the -onCellData callback can be used.
-scrollbar always, never, automatic (default: automatic)
When to show scrollbars. If the value is a list of two elements, the first value is for the horizontal scrollbar and the second value for the vertical scrollbar.
-visible boolean (default: 1)
Whether or not the item is visible.
-widthGroup string (default: "")
The -widthGroup option can be an arbitrary string. All widgets with the same widthGroup request the same width. If packed with the fill flag set, they will have nevertheless different widths.
-widthRequest int
Width which is requested in the parent widget. The actual width can be larger.

Description

The tree command creates a new tree widget. On creation at least on of the options -columns, -children, -titles or -types must be given. The number of columns of the created tree is the maximum of these four values. This number cannot be changed after creation, but hiding columns should do the job in most cases.

Each row can be identified by its path. A path is a list of integers which describe recursively the position of the row relative to its parent: the highest level rows have the path 0, 1 etc.; the children of the second row the path {1 0}, {1 1}, {1 2} etc.; the children of the first child of the second child of the second row have the path {1 1 0 0}, {1 1 0 1}, {1 1 0 2} etc. The level above the first level has the empty path {}. Each element in a path may also be "end" which is equivalent to the last element in this level. A given path may point to different rows during the lifetime of a tree, since the position of a row is dependent on the sort order and changes if rows are inserted or deleted before the referenced row.

A path may be converted to a reference. A reference points during the lifetime of the tree and the lifetime of the referenced row to the same row, independent of sort order or insertion or deletion. Since a reference has to be stored inside the tree widget, it should be deleted if it is not needed any more.

Commands

id add pathOrReference row-list
Add rows as children to the pathOrReference pathOrReference. The new rows are placed behind existing rows. Use the empty path {} to add toplevel rows. The command returns a list of paths to every new row. If the column type is "image", the entry must be a percent string of type file which determines the image file to be loaded (e.g. ("%/./gnocl.png")
Options
-singleRow boolean (default: false)
If set to true, row-list is not a list of rows but only a list of elements for a single row. This option exists only to simplify the addition of one single row.
-singleColumn boolean (default: false)
If set to true, row-list is not a list of rows but only a list of one element for every row. This option exists only to simplify the addition of one single column.
id addBegin pathOrReference row-list
Same as add, but adds the new rows before existing rows.
id addEnd pathOrReference row-list
Same as add.
id cellConfigure pathOrReference column [-option value...]
Configure a cell.
Options
-value string
Value of the cell. The type must correspond to the type of the column.
-visible boolean (default: 1)
Whether this cell is visible.
id collapse [-option value...]
Collapse a row.
Options
-path pathOrReference (default: 0)
Which row to collapse.
id columnCget column option
Returns the value for one column option. The option may have any of the values accepted by columnConfigure. TODO: not yet all options implemented.
id columnConfigure column [-option value...]
Configure a column
Options
-autoResize boolean (default: true)
Whether the width of the column should automatically increase if necessary
-onCellData string (default: "")
Command which is executed, before the content of a cell is rendered. This can be used to configure the cells dependent on their content. The command must return valid row configuration options (e.g. "-foreground red"). Before evaluation the following percent strings are substituted:

%w    widget name
%p    path of the cell
%v    value (content) of the cell
-onEdited string (default: "")
Only valid for editable columns. Command which is executed, if a cell in this column is edited. Before evaluation the following percent strings are substituted:

%w    widget name
%p    path of selected cell
%v    new text (value)
-onToggled string (default: "")
Only valid for boolean columns. Command which is executed, if it a cell in this column is toggled. Before evaluation the following percent strings are substituted:

%w    widget name
%p    path of selected cell
-visible boolean (default: 1)
Whether this column is visible.
-clickable boolean
Whether it can be clicked on the column header and sort this column.
-title string (default: "")
Title of the column.
-resizable boolean (default: 1)
Whether the column can be resized by the user.
-reorderable boolean
Whether the column can be moved to another place in the tree.
-minWidth integer
Minimum width of the column in pixel.
-maxWidth integer
Maximum width of the column in pixel.
-titleAlign one of  left, center, right or a float between 0 and 1
Horizontal alignment of the title.
-align one of topLeft, top, topRight, left, center, right, bottomLeft, bottom, or bottomRight
Alignment of the cells.
-width integer
Width of the cells.
-height integer
Height of the cells.
-xPad integer
Horizontal padding of the column.
-yPad integer
Vertical padding of the column.
-background color
Background colour of the cells.
-foreground color
Foreground colour of the cells.
-font font
Font used for the rendering of the cells.
-fontFamily string
Font used for the rendering of the cells.
-fontStyle one of normal, oblique or italic (default: normal)
Font style used for the rendering of the cells.
-fontVariant one of normal or smallCaps (default: normal)
Font variant used for the rendering of the cells.
-fontWeight one of ultralight, light, normal, bold, ultrabold or heavy (default: normal)
Font weight used for the rendering of the cells.
-fontRise integer (default: 0)
How many pixels the text should be risen.
-fontStretch string (default: normal)
Font stretch used for the rendering of the cells. Use one of ultraCondensed, extraCondensed, condensed, semiCondensed, normal, semiExpanded, expanded, extraExpanded or ultraExpanded
-fontSize integer
Font size used for the rendering of the cells.
-fontScale float or one of xx-small, x-small, small, medium, large, x-large or xx-large (default: normal)
Font scale used for the rendering of the cells.
-strikethrough boolean (default: 0)
Whether the text is struck through.
-underline one of none, single, float, low (default: none)
How the text in the cells should be underlined.
-editable boolean (default: 0)
Whether the text in the cells can be edited.
-widget string (default: "")
Set id of alternative widget to display in the column header.
-wrapMode string (default: none)
Whether the text in the cells should be wrapped within the available row. One of word, char or none.
-wrapWith int (default: 0)
Set the width (in pixels) of text line prior to wrapping occurs.
id configure [-option value...]
Configure the widget. Option may have any of the values accepted by the tree command except from columns and -types.
id coordsToPath x y
Calculates from the given windows coordinates x and y (for example aquired from the onButtonPress callback) to a path. Returns a list of four elements: a path, a column, x cell coordinate and y cell coordinate.
id delete
Deletes the widget and the associated tcl command.
id deleteReference reference
Deletes a reference. The reference may not be used after it has been deleted.
id erase startPathOrReference ?endPathOrReference?
Deletes all rows between startPathOrReference and endPathOrReference. Deletes only one row if only startPathOrReference is given. If endPathOrReference is "end" deletes all child rows of the parent of startPathOrReference starting at startPathOrReference. "erase 0 end" deletes all rows.
id expand [-option value...]
Expand a row.
Options
-path pathOrReference (default: 0)
Which row to expand.
-recursive boolean (default: 1)
Whether to expand all children recursively.
id get pathOrReference column
Get the value of one cell.
id getNumChildren ?pathOrReference?
Returns the number of children for the given pathOrReference. If no pathOrReference is given the number of top level rows is returned.
id getReference path
Returns a reference to path.
id getSelection
Returns a list of the paths of the selected rows.
id onSelectionChanged
Executes the onSelectionChanged command, if there is any. Otherwise does nothing.
id setSelection pathOrReference-list [-option value...]
Selects each row that is given in pathOrReference-list. The onSelectionChanged callback is not called. If pathOrReference is "all" all rows are selected. To select more than one row, selectionMode must be set to multiple or extended.
Options
-add boolean (default: false)
If set to true, the given rows are added to the selection, else the selection contains only the given rows.
-unselect boolean (default: false)
If set to true, the selection is removed from the given rows.
-single boolean (default: false)
If set to true, pathOrReference-list is not a list of paths but only one single pathOrReference. This option exists only to simplify the selection of one single row.
id referenceToPath reference
Returns the path of reference.
id scrollToPosition [-option value...]
Scrolls the widget so that the specified row is visible. If only "-column" is given, the widget is scrolled only horizontal so that this column is visible. If neither "-column" nor "-path" is given, the widget is scrolled to the last expanded row.
Options
-align  one of topLeft, top, topRight, left, center, right, bottomLeft, bottom, or bottomRight
Specifies where the row shall be shown.
-path pathOrReference
Specifies which row shall be shown.
-column integer
Specifies which column shall be shown.
id setCursor pathOrReference [-option value...]
Sets the cursor to a specific row.
Options
-column integer
Sets the cursor to a specific column in the row
-startEdit boolean (default: 0)
Whether to start editing the cell given by column and row. The column has to be editable and the tree has to be realized.

Example

Two examples are given below. The first shows how to add items although doesn't show how to handle entries with spaces. The second example is more complex and shows how a marked-up list can be processes and disiplayed within a tree inorder to show the structuring of the markup. 
#---------------
# simple-tree.tcl
#---------------
#!/bin/sh
#\ exec tclsh "$0" "$@" package require Gnocl
set tree [gnocl::tree \
    -types {string integer} \
    -titles {"" "# of Legs"}]


$tree add {} {Mamals Birds Bugs}

$tree add 0 {{Cat 4} {Dog 4} {Human 2}}

foreach {paro pred} [$tree add 1 {Parrots Predator}] {}

$tree add $paro {{Cockatoo 2} {Amazone 2}}


$tree add $pred {{Hawk 2} {Eagle 2}}


$tree expand \
    -path "1" \
    -recursive 1


gnocl::window \
    -title "Tree" \
    -child $tree \
    -defaultWidth 300 \
    -defaultHeight 200


#--------------- # test-tree.tcl #--------------- # 26-Jan-2015 #--------------- #!/bin/sh #\ exec tclsh "$0" "$@" package require Gnocl #--------------- # Format heading with markup according to use. #--------------- # Args: # level Heading level, i.e. H1-5. # str String to be formatted. # toc Use, whether for treelist (default) or export to odt. # Returns: # none Marked up string. # proc headings:_format_string { level str {toc FALSE} } { switch $level { H1 { if { $toc } { return "<big><b>$str</b></big>" } return "<span foreground=\"blue\"><big>$str</big></span>" } H2 { if { $toc } { return "<b>$str</b>" } return "<span foreground=\"red\">$str</span>" } H3 { return "<b>$str</b>" } H4 { return $str } H5 { return "<i>$str</i>" } default {return $str} } } #--------------- # Return a tabulated table of contents with outline numbering from list of formatted headings. #--------------- # Args: # headings Mark up list of headings. # padding Space between outline numbers and heading text. # Returns: # Formatted list with pango/html markup. # proc headings:toc { headings {padding 3} } { foreach i "v w x y z" {set $i 0} for { set q 0 } { $q < [llength $headings] } { incr q } { set item [lindex $headings $q] set item [string trim $item] set tmp [string range $item 3 end-3] set pad [string repeat " " $padding] # add items to the toplevel if { [string first _H1 $item] != -1 } { incr v set tmp [headings:_format_string H1 $pad$tmp TRUE] append res "$tmp\n" foreach i "w x y z" {set $i 0} } if { [string first _H2 $item] != -1 } { incr w set tmp "<b>$v.$w)$pad$tmp</b>" append res "\t$tmp\n" foreach i "x y z" {set $i 0} } if { [string first _H3 $item] != -1 } { incr x set tmp [headings:_format_string H1 $pad$tmp TRUE] append res "\t\t$tmp\n" foreach i "y z" {set $i 0} } if { [string first _H4 $item] != -1 } { incr y set tmp [headings:_format_string H1 $pad$tmp TRUE] append res "\t\t\t$tmp\n" foreach i "z" {set $i 0} } if { [string first _H5 $item] != -1 } { incr z set tmp [headings:_format_string H1 $pad$tmp TRUE] append res "\t\t\t\t$tmp\n" } } return $res }

#--------------- # Popluate tree widget from list of formatted headings. #--------------- # Args: # headings Mark up list of headings # padding Space between outline numbers and heading text # Returns: # none # proc headings:outline {tree headings {padding 3} } { foreach i "v w x y z" {set $i 0} for { set q 0 } { $q < [llength $headings] } { incr q } { set item [lindex $headings $q] set item [string trim $item] set tmp [string range $item 3 end-3] set pad [string repeat " " $padding] # add items to the toplevel if { [string first _H1 $item] != -1 } { incr v set tmp "<big><b>$v)$pad$tmp</b></big>" set tmp [headings:_format_string H1 $tmp] set a [$tree add {} [list [list $tmp]] ] foreach i "w x y z" {set $i 0} } if { [string first _H2 $item] != -1 } { incr w set tmp "<b>$v.$w)$pad$tmp</b>" set tmp [headings:_format_string H2 $tmp] set b [ $tree add $a [list [list $tmp]] ] foreach i "x y z" {set $i 0} } if { [string first _H3 $item] != -1 } { incr x set tmp "$v.$w.$x)$pad$tmp" set tmp [headings:_format_string H3 $tmp] set c [$tree add [lindex $b 0] [list [list $tmp]] ] foreach i "y z" {set $i 0} } if { [string first _H4 $item] != -1 } { incr y set tmp "$v.$w.$x.$y)$pad$tmp" set tmp [headings:_format_string H4 $tmp] set d [$tree add [lindex $c 0] [list [list $tmp]] ] foreach i "z" {set $i 0} } if { [string first _H5 $item] != -1 } { incr z set tmp "<i>$v.$w.$x.$y.$z)$pad$tmp</i>" set tmp [headings:_format_string H5 $tmp] set e [$tree add [lindex $d 0] [list [list $tmp]] ] } } } if 1 { set headings { {_H1HEADINGH1_} {_H2HeadingH2_} {_H3HeadingH3_} {_H3HeadingH3_} {_H2HeadingH2_} {_H3HeadingH3_} {_H3HeadingH3_} {_H4HeadingH4_} {_H5HeadingH5_} {_H5HeadingH5_} {_H5HeadingH5_} {_H4HeadingH4_} {_H5HeadingH5_} {_H5HeadingH5_} {_H5HeadingH5_} {_H1HEADINGH1_} {_H2HeadingH2_} {_H3HeadingH3_} {_H3HeadingH3_} {_H2HeadingH2_} {_H3HeadingH3_} {_H3HeadingH3_} {_H1HEADINGH1_} {_H2HeadingH2_} {_H3HeadingH3_} {_H4HeadingH4_} {_H5HeadingH5_} {_H3HeadingH3_} {_H2HeadingH2_} {_H3HeadingH3_} {_H3HeadingH3_} } set tree [gnocl::tree \ -ruleHint 1 \ -treeLines TRUE \ -types {markup} \ -titles {Heading}] $tree expand \ -path "1" \ -recursive 1 gnocl::window \ -title "Tree" \ -child $tree \ -defaultWidth 300 \ -defaultHeight 500 headings:outline $tree $headings puts [headings:toc $headings] }


Comments