tree

Name

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

Synopsis

tree [-option value...]

Screenshot

Options

-children

type: list (default: "")

List of rows. Each row consists of a list of cell entries.

-columns

type: integer

Number of columns

-hasFocus

type: 1

This sets the focus to the widget. To unset the focus it must be set to another widet.

-headersClickable

type: boolean (default: true)

Whether the headers are clickable.

-headersVisible

type: boolean (default: true)

Whether to show the headers.

-heightGroup

type: string (default: "")

heightGroup 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

type: int

Height which is requested in the parent widget. The actual height can be larger.

-name

type: string

Name of the widget, can be used to set options in an rc file.

-onButtonPress

type: string (default: "")

Tcl command which is executed if a mouse button is press inside the widget. Before evaluation the following percent strings are substituated: TABLE %% | % %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) TABLE

-onButtonRelease

type: string (default: "")

Tcl command which is executed if a mouse button is released inside the widget. Before evaluation the following percent strings are substituated: TABLE %% | % %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) TABLE

-onPopupMenu

type: string (default: "")

Tcl command which is executed if the "popup-menu" signal is recieved, which is normally the case if the user presses Shift-F10. Before evaluation the following percent strings are substituated: %w by widget name.

-onRowCollapsed

type: string (default: "")

Command to execute in the global scope if a row is collapsed. Before evaluation the following percent strings are substituted: TABLE %% | % %w | widget name %p | list of paths of the collapsed row /TABLE

-onRowExpanded

type: string (default: "")

Command to execute in the global scope if a row is expanded. Before evaluation the following percent strings are substituted: TABLE %% | % %w | widget name %p | list of paths of the expanded row /TABLE

-onSelectionChanged

type: string (default: "")

Command to execute in the global scope if the selection could be changed. Occasionaly it is executed, if the selection has not changed. Therefor the "%p" parameter can also be the empty string, which is not a valid path. Before evaluation the following percent strings are substituted: TABLE %% | % %w | widget name %p | list of paths of the selection /TABLE

-selectionMode

type: ONEOF single, browse, multiple, extended

Selection mode

-sizeGroup

type: string (default: "")

sizeGroup 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

type: string (default: "")

Titles of the columns

-types

type: ONEOF boolean, integer, float, string, markup, 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

type: 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

type: boolean (default: 1)

Whether or not the item is visible.

-widthGroup

type: string (default: "")

widthGroup 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

type: 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 anymore.

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

type: 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

type: 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

Value of the cell. The type must correspond to the type of the column.

-visible

type: boolean (default: 1)

Whether this cell is visible.

id collapse [-option value...]

Collapse a row.

Options

-path

type: 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

type: boolean (default: true)

Whether the width of the column should automatically increase if necessary

-onCellData

type: 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 TABLE %% | % %w | widget name %p | path of the cell %v | value (content) of the cell /TABLE

-onEdited

type: 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 TABLE %% | % %w | widget name %p | path of selected cell %v | new text (value) /TABLE

-onToggled

type: 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 TABLE %% | % %w | widget name %p | path of selected cell /TABLE

-visible

type: boolean (default: 1)

Whether this column is visible.

-clickable

type: boolean

Whether it can be clicked on the column header and sort this column.

-title

type: string (default: "")

Title of the column.

-resizable

type: boolean (default: 1)

Whether the column can be resized by the user.

-reorderable

Whether the column can be moved to another place in the tree.

-minWidth

type: integer

Minimum width of the column in pixel.

-maxWidth

type: integer

Maximum width of the column in pixel.

-titleAlign

type: left, center, right or a float between 0 and 1

Horizontal alignment of the title.

-align

type: a list of the horizontal and vertical alignment or one of topLeft, top, topRight, left, center, right, bottomLeft, bottom, or bottomRight

Alignment of the cells.

-width

type: integer

Width of the cells.

-height

type: integer

Height of the cells.

-xPad

type: integer

Horizontal padding of the column.

-yPad

type: integer

Vertical padding of the column.

-background

type: color

Background color of the cells.

-foreground

type: color

Foreground color of the cells.

-font

type: FONT

Font used for the rendering of the cells.

-fontFamily

Font family used for the rendering of the cells.

-fontStyle

type: ONEOF normal, oblique, italic (default: normal)

Font style used for the rendering of the cells.

-fontVariant

type: ONEOF normal, smallCaps (default: normal)

Font variant used for the rendering of the cells.

-fontWeight

type: ONEOF ultralight, light, normal, bold, ultrabold, heavy (default: normal)

Font weight used for the rendering of the cells.

-fontRise

type: integer (default: 0)

How many pixels the text should be risen.

-fontStretch

type: ONEOF ultraCondensed, extraCondensed, condensed, semiCondensed, normal, semiExpanded, expanded, extraExpanded, ultraExpanded (default: normal)

Font stretch used for the rendering of the cells.

-fontSize

type: integer

Font size used for the rendering of the cells.

-fontScale

type: float ORONEOF xx-small, x-small, small, medium, large, x-large, xx-large (default: normal)

Font scale used for the rendering of the cells.

-strikethrough

type: boolean (default: 0)

Whether the text is struck through.

-underline

type: ONEOF none, single, float, low (default: none)

How the text in the cells should be underlined.

-editable

type: boolean (default: 0)

Whether the text in the cells can be edited.

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

type: pathOrReference (default: 0)

Which row to expand.

-recursive

type: 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

type: boolean (default: false)

If set to true, the given rows are added to the selection, else the selection contains only the given rows.

-unselect

type: boolean (default: false)

If set to true, the selection is removed from the given rows.

-single

type: 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

type: a list of the horizontal and vertical alignment or one of topLeft, top, topRight, left, center, right, bottomLeft, bottom, or bottomRight

Specifies where the row shall be shown.

-path

type: pathOrReference

Specifies which row shall be shown.

-column

type: integer

Specifies which column shall be shown.

id setCursor pathOrReference [-option value...]

Sets the cursor to a specific row.

Options

-column

type: integer

Sets the cursor to a specific column in the row

-startEdit

type: 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


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}] break
$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

results in

See also

list, GtkTreeView, GtkTreeStore