# tree widget # A [GtkTreeView](http://developer.gnome.org/gtk2/2.24/GtkTreeView.html) packed inside a [GtkScrolledWindow](http://developer.gnome.org/gtk2/2.24/GtkScrolledWindow.html) --- ## Definition ## ``` text varname value value command... command... command... filename... filename... filename... state activity... activity... parameter... data... data... data... filename ``` "..." denotes acceptance of multiples of the same thing. ## Tag Attributes ## See the [GtkTreeView](http://developer.gnome.org/gtk2/2.24/GtkTreeView.html#GtkTreeView.object-hierarchy) 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 | | column-resizeable | Resizeable state of column(s) | _state0_ `|` _state1_ `|` ... | 0.8.4 | | column-sizing | Sizing mode of column(s) | _mode0_ `|` _mode1_ `|` ... (`0` default, `1` autosize or >= `2` fixed width in pixels) | 0.8.4 | | 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](http://developer.gnome.org/gtk2/2.24/gtk2-Stock-Items.html#GTK-STOCK-ABOUT:CAPS)) | | ## 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](http://developer.gnome.org/gtk2/2.24/GtkTreeView.html#GtkTreeView-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](http://developer.gnome.org/gtk2/2.24/GtkTreeSelection.html#GtkTreeSelection-changed)" signal is emitted when the selection has changed (please see link about this). The "[cursor-changed](http://developer.gnome.org/gtk2/2.24/GtkTreeView.html#GtkTreeView-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](http://developer.gnome.org/gtk2/2.24/GtkWidget.html#GtkWidget-button-press-event), [button-release-event](http://developer.gnome.org/gtk2/2.24/GtkWidget.html#GtkWidget-button-release-event), [configure-event](http://developer.gnome.org/gtk2/2.24/GtkWidget.html#GtkWidget-configure-event), [enter-notify-event](http://developer.gnome.org/gtk2/2.24/GtkWidget.html#GtkWidget-enter-notify-event), [leave-notify-event](http://developer.gnome.org/gtk2/2.24/GtkWidget.html#GtkWidget-leave-notify-event), [focus-in-event](http://developer.gnome.org/gtk2/2.24/GtkWidget.html#GtkWidget-focus-in-event), [focus-out-event](http://developer.gnome.org/gtk2/2.24/GtkWidget.html#GtkWidget-focus-out-event), [hide](http://developer.gnome.org/gtk2/2.24/GtkWidget.html#GtkWidget-hide), [show](http://developer.gnome.org/gtk2/2.24/GtkWidget.html#GtkWidget-show), [realize](http://developer.gnome.org/gtk2/2.24/GtkWidget.html#GtkWidget-realize), [key-press-event](http://developer.gnome.org/gtk2/2.24/GtkWidget.html#GtkWidget-key-press-event), [key-release-event](http://developer.gnome.org/gtk2/2.24/GtkWidget.html#GtkWidget-key-release-event), [map-event](http://developer.gnome.org/gtk2/2.24/GtkWidget.html#GtkWidget-map-event), [unmap-event](http://developer.gnome.org/gtk2/2.24/GtkWidget.html#GtkWidget-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](http://developer.gnome.org/gtk2/2.24/GtkWindow.html#gtk-window-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_ `|` ... ---