The
gtk:tree-view widget displays any object that implements the
gtk:tree-model interface.
Please refer to the tree view conceptual overview for an overview of all
the objects and data types related to the tree view and how they work
together.
Figure: GtkTreeView
Several different coordinate systems are exposed in the
gtk:tree-view
API:
- Widget coordinates
- Coordinates relative to the widget. Usually the GDK window from the gtk:widget-window function.
- GDK window coordinates (Bin window)
- Coordinates relative to the GDK window that the gtk:tree-view widget renders to.
- Tree coordinates
- Coordinates relative to the entire scrollable area of the gtk:tree-view widget. These coordinates start at (0, 0) for row 0 of the tree view.
Several functions are available for converting between the different
coordinate systems. The most common translations are between widget and GDK
window coordinates and between GDK window and tree view coordinates. For the former you can use the
gtk:tree-view-convert-widget-to-bin-window-coords
function (and vice versa), for the latter the
gtk:tree-view-convert-bin-window-to-tree-coords function (and vice
versa).
GtkTreeView as GtkBuildable
The
gtk:tree-view implementation of the
gtk:buildable interface accepts
gtk:tree-view-column objects as
<child> elements and exposes the internal
gtk:tree-selection object in UI
definitions.
Example: A UI definition fragment with the
gtk:tree-view widget
<object class="GtkTreeView" id="treeview">
<property name="model">liststore1</property>
<child>
<object class="GtkTreeViewColumn" id="test-column">
<property name="title">Test</property>
<child>
<object class="GtkCellRendererText" id="test-renderer"/>
<attributes>
<attribute name="text">1</attribute>
</attributes>
</child>
</object>
</child>
<child internal-child="selection">
<object class="GtkTreeSelection" id="selection">
<signal name="changed" handler="on_treeview_selection_changed"/>
</object>
</child>
</object> CSS nodes
treeview.view
├── header
│ ├── <column header>
┊ ┊
│ ╰── <column header>
│
╰── [rubberband]
The
gtk:tree-view implementation has a main CSS node with name
treeview and
.view style class. It has a subnode with name
header, which is the parent for all the widgets of the column header CSS nodes. For rubberband selection, a subnode with name
rubberband
is used.
Style Property Details
- allow-rules
- The allow-rules style property of type :boolean (Read)
Allow drawing of alternating color rows.
Default value: true - even-row-color
- The even-row-color style property of type gdk:color (Read)
Color to use for even rows. - expander-size
- The expander-size style property of type :int (Read)
Size of the expander arrow.
Allowed values: >= 0
Default value: 14 - grid-line-pattern
- The grid-line-pattern style property of type :string (Read)
Dash pattern used to draw the tree view grid lines.
Default value: "" - grid-line-width
- The grid-line-width style property of type :int (Read)
Width, in pixels, of the tree view grid lines.
Allowed values: >= 0
Default value: 1 - horizontal-separator
- The horizontal-separator style property of tpye :int (Read)
Horizontal space between cells. Must be an even number.
Allowed values: >= 0
Default value: 2 - indent-expanders
- The indent-expanders style property of type :boolean (Read)
Make the expanders indented.
Default value: true - odd-row-color
- The odd-row-color style property of type gdk:color (Read)
Color to use for odd rows. - tree-line-pattern
- The tree-line-pattern style property of type :string (Read)
Dash pattern used to draw the tree view lines.
Default value: "" - tree-line-width
- The tree-line-width style property of type :int (Read)
Width, in pixels, of the tree view lines.
Allowed values: >= 0
Default value: 1 - vertical-separator
- The vertical-separator style property of type :int (Read)
Vertical space between cells. Must be an even number.
Allowed values: >= 0
Default value: 2
Signal Details
The "columns-changed" signal
lambda (view) :run-last
The number of columns of the tree view has changed.
- view
- The gtk:tree-view widget on which the signal is emitted.
The "cursor-changed" signal
lambda (view) :run-last
The position of the cursor (focused cell) has changed.
- view
- The gtk:tree-view widget on which the signal is emitted.
The "expand-collapse-cursor-row" signal
lambda (view arg1 arg2 arg3) :action
- view
- The gtk:tree-view widget on which the signal is emitted.
- arg1
- an undocumented boolean
- arg2
- an undocumented boolean
- arg3
- an undocumented boolean
The "move-cursor" signal
lambda (view step direction) :action
Key binding signal which gets emitted when the user presses one of the
cursor keys. Applications should not connect to it, but may emit it with the
g:signal-emit function if they need to control the cursor programmatically. In contrast to the
gtk:tree-view-get-cursor and
gtk:tree-view-set-cursor-on-cell functions when moving horizontally the
"move-cursor" signal does not reset the current
selection.
- view
- The gtk:tree-view widget on which the signal is emitted.
- step
- The granularity of the move, as a value of the gtk:movement-step enumeration. The :logical-positions, :visual-positions, :display-lines, :pages and :buffer-ends values are supported. The :visual-positions and :logical-positions values are treated identically.
- direction
- The integer with the direction to move: +1 to move
forwards and -1 to move backwards. The resulting movement is undefined for all other values.
- Returns
- True if step is supported, false otherwise.
The "row-activated" signal
lambda (view path column) :action
The signal is emitted when the
gtk:tree-view-row-activated function
is called or the user double clicks a tree view row. It is also emitted when a non-editable row is selected and one of the
Space,
Shift+Space,
Return or
Enter keys is pressed.
- view
- The gtk:tree-view widget on which the signal is emitted.
- path
- The gtk:tree-path instance for the activated row.
- column
- The gtk:tree-view-column object in which the activation occurred.
The "row-collapsed" signal
lambda (view iter path) :run-last
The given row has been collapsed (child nodes are hidden).
- view
- The gtk:tree-view widget on which the signal is emitted.
- iter
- The gtk:tree-iter iterator of the collapsed row.
- path
- The gtk:tree-path instance that points to the row.
The "row-expanded" signal
lambda (view iter path) :run-last
The given row has been expanded (child nodes are shown).
- view
- The gtk:tree-view widget on which the signal is emitted.
- iter
- The gtk:tree-iter iterator of the expanded row.
- path
- The gtk:tree-path instance that points to the row.
The "select-all" signal
lambda (view) :action
- view
- The gtk:tree-view widget on which the signal is emitted.
The "select-cursor-parent" signal
lambda (view) :action
- view
- The gtk:tree-view widget on which the signal is emitted.
The "select-cursor-row" signal
lambda (view arg) :action
- view
- The gtk:tree-view widget on which the signal is emitted.
- arg
- an undocumented boolean
The "start-interactive-search" signal
lambda (view) :action
- view
- The gtk:tree-view widget on which the signal is emitted.
The "test-collapse-row" signal
lambda (view iter path) :run-last
The given row is about to be collapsed (hide its children nodes). Use
this signal if you need to control the collapsibility of individual rows.
- view
- The gtk:tree-view widget on which the signal is emitted.
- iter
- The gtk:tree-iter iterator of the row to collapsed.
- path
- The gtk:tree-path instance that points to the row.
- Returns
- False to allow collapsing, true to reject.
The "test-expand-row" signal
lambda (view iter path) :run-last
The given row is about to be expanded (show its children nodes). Use this
signal if you need to control the expandability of individual rows.
- view
- The gtk:tree-view widget on which the signal is emitted.
- iter
- The gtk:tree-iter iterator of the row to expand.
- path
- The gtk:tree-path instance that points to the row.
- Returns
- False to allow expansion, true to reject.
The "toggle-cursor-row" signal
lambda (view) :action
- view
- The gtk:tree-view widget on which the signal is emitted.
The "unselect-all" signal
lambda (view) :action
- view
- The gtk:tree-view widget on which the signal is emitted.
