#
Prev |  | Next

# tree

## Name

tree -- A widget which 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`

Prev | Home | Next
Commands | Up | list