# tree widget A GtkTreeView packed inside a GtkScrolledWindow ## Definition
    <tree tag_attr="value"...>
    	<label>text</label>
    	<variable>varname</variable>
    	<height>value</height>
    	<width>value</width>
    	<input>command</input>...
    	<input icon-column="index">command</input>...
    	<input stock-column="index">command</input>...
    	<input file>filename</input>...
    	<input file icon-column="index">filename</input>...
    	<input file stock-column="index">filename</input>...
    	<sensitive>state</sensitive>
    	<action>activity</action>...
    	<action signal="type">activity</action>...
    	<action function="type">parameter</action>...
    	<item>data</item>...
    	<item icon-name="image">data</item>...
    	<item stock-id="gtk-image">data</item>...
    	<output file>filename</output>
    </tree>
"..." denotes acceptance of multiples of the same thing. ## Tag Attributes See the GtkTreeView widget and ancestor class properties. The following custom tag attributes are available:
Name | Description | Value | Since
--- | --- | --- | ---
space-expand | Pack widget expanding into space | `true` or `false` | 0.7.21
space-fill | Pack widget filling space | `true` or `false` | 0.7.21
block-function-signals | Block signal emissions from functions | `true` or `false` | 0.7.21
file-monitor | Emit signal when input file(s) change | `true` or `false` | 0.8.1
auto-refresh | Auto refresh when input file(s) change | `true` or `false` | 0.8.1
hscrollbar-policy | Policy for the horizontal scrollbar | `0`, `1`, `2` (always, automatic, never) | 0.8.1
vscrollbar-policy | Policy for the vertical scrollbar | `0`, `1`, `2` (always, automatic, never) | 0.8.1
exported-column | The column to export data from | An integer >= `0` |
selected-row | The row to select on initialisation and refresh | An integer >= `0` | 0.8.1
column-header-active | Active state of column header(s) | state0 `|` state1 `|` ... | 0.8.1
column-visible | Visible state of column(s) | state0 `|` state1 `|` ... | 0.8.1
auto-sort | Automatically sort after loading data | `true` or `false` | 0.8.1
sort-column | The initial sort column when auto-sorting | An integer >= `0` | 0.8.1
sort-type | The initial sort direction when auto-sorting | `0`, `1` (ascending, descending) | 0.8.1
column-type | Data type of column(s) | type0 `|` type1 `|` ... (`string`, `int64`, `uint64` or `double`) | 0.8.1
column-sort-function | The sorting algorithm for each column | func0 `|` func1 `|` ... (`0` default, `1` strnatcmp or `2` strcasenatcmp) | 0.8.1
selection-mode | Selection method | `0`, `1`, `2`, `3` (none, single, browse, multiple) | 0.7.21
icon-name | Default GTK theme icon name for all rows |  |
stock-id | Default GTK stock icon ID for all rows | `gtk-about`, `gtk-add`, ... (full list) |
## Directives Some of these may have tag attribute equivalents.
Name | Description | Contents | Since
--- | --- | --- | ---
label | Column header labels | label0 `|` label1 `|` ... |
variable | Variable name |  |
variable export="false" | Variable name, not exported to shell |  | 0.8.3
height[1] | Initial minimum height | An integer > `0` or `-1` to ignore |
width[1] | Initial minimum width | An integer > `0` or `-1` to ignore |
input | Data input source | Shell command |
input icon-column="index" | Data input source | Shell command |
input stock-column="index" | Data input source | Shell command |
input file | Data input source | Filename |
input file icon-column="index" | Data input source | Filename |
input file stock-column="index" | Data input source | Filename |
sensitive | Sensitive state | `true` or `false` |
action | Execute command on default signal | Shell command |
action | Perform function on default signal | function:parameter |
action signal="type" | Execute command on signal | Shell command |
action signal="type" | Perform function on signal | function:parameter |
action function="type" | Perform function on default signal | parameter | 0.8.3
action condition="type" | Execute command on default signal conditionally | Shell command | 0.8.3
action condition="type" | Perform function on default signal conditionally | function:parameter | 0.8.3
action signal="type" condition="type" | Execute command on signal conditionally | Shell command | 0.8.3
action signal="type" condition="type" | Perform function on signal conditionally | function:parameter | 0.8.3
action function="type" condition="type" | Perform function on default signal conditionally | parameter | 0.8.3
item | Input data | data0 `|` data1 `|` ... |
item icon-name="image" | Input data | data0 `|` data1 `|` ... |
item stock-id="gtk-image" | Input data | data0 `|` data1 `|` ... |
output file | Data output target | Filename | 0.8.1
## Signals The default signal is "row-activated", emitted when the user double-clicks a row and also when a row is selected and one of the keys Space, Shift+Space, Return or Enter is pressed. The "changed" signal is emitted when the selection has changed (please see link about this). The "cursor-changed" signal is emitted when the position of the cursor (focused cell) has changed. The "file-changed" signal is emitted if file-monitor is true and the input file being monitored has changed. The following signals are connected-up for all widgets: button-press-event, button-release-event, configure-event, enter-notify-event, leave-notify-event, focus-in-event, focus-out-event, hide, show, realize, key-press-event, key-release-event, map-event, unmap-event ## Functions The following functions can be performed upon this widget by any widget capable of emitting signals:
Type | Description | Parameter | Since
--- | --- | --- | ---
enable | Sensitise widget | Variable name |
disable | Desensitise widget | Variable name |
show | Show widget | Variable name | 0.8.1
hide | Hide widget | Variable name | 0.8.1
grabfocus | Grab input focus | Variable name | 0.8.1
refresh | Reload input data | Variable name |
save[2] | Save widget data | Variable name | 0.8.1
clear | Remove all widget data | Variable name | 0.7.21
removeselected | Remove selected widget data | Variable name |
The following general functions can be performed by any widget capable of emitting signals:
Type | Description | Parameter | Since
--- | --- | --- | ---
break | Break out of actions list | None | 0.8.3
command | Execute command | Shell command |
exit | Exit dialog | A value for the `EXIT` variable |
closewindow | Close dialog | Variable name |
launch | Launch dialog | Variable name |
presentwindow | Present dialog | Variable name | 0.8.1
## Conditions The following conditions can be used within the condition attribute of action directives:
Type | Description | Argument | Since
--- | --- | --- | ---
active_is_true(argument) | Active state of toggle widget | Variable name | 0.8.3
active_is_false(argument) | Active state of toggle widget | Variable name | 0.8.3
command_is_true(argument) | Output of shell command | Shell command | 0.8.3
command_is_false(argument) | Output of shell command | Shell command | 0.8.3
file_is_true(argument) | Contents of a file | Filename | 0.8.3
file_is_false(argument) | Contents of a file | Filename | 0.8.3
sensitive_is_true(argument) | Sensitive state of widget | Variable name | 0.8.3
sensitive_is_false(argument) | Sensitive state of widget | Variable name | 0.8.3
visible_is_true(argument) | Visible state of widget | Variable name | 0.8.3
visible_is_false(argument) | Visible state of widget | Variable name | 0.8.3
true means "true", "yes" or a non-zero value, false means "false", "no" or zero, therefore the shell command is expected to echo one of these values to stdout. ## Notes 1. This widget has a default dimension of 200x100 which can be overridden with the height and/or width directives. 2. When saving, due to the multiple input data formats, the columns are output in the following raw state: icon-name `|` stock-id `|` data0 `|` data1 `|` ... button, checkbox, colorbutton, comboboxentry, comboboxtext, combobox, edit, entry, eventbox, expander, fontbutton, frame, hbox, hscale, hseparator, list, menubar, menuitemseparator, menuitem, menu, notebook, pixmap, progressbar, radiobutton, separator, spinbutton, statusbar, table, terminal, text, timer, togglebutton, tree, vbox, vscale, vseparator, window,