Widget that displays any object that implements the
gtk-tree-model
interface.
Please refer to the tree widget conceptual overview for an overview of all
the objects and data types related to the tree widget and how they work
together.
Several different coordinate systems are exposed in the
gtk-tree-view
API. These are:
Coordinate systems in the
gtk-tree-view API:
- Widget coordinates
- Coordinates relative to the widget. Usually the window from the function gtk-widget-window.
- Bin window coordinates
- Coordinates relative to the 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.
Several functions are available for converting between the different
coordinate systems. The most common translations are between widget and bin
window coordinates and between bin window and tree coordinates. For the
former you can use the function
gtk-tree-view-convert-widget-to-bin-window-coords (and vice versa), for the latter the function
gtk-tree-view-convert-bin-window-to-tree-coords
(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 column header widgets' 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: "001001" - 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: "001001" - 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
Keybinding 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 function
g-signal-emit if they need to control the cursor
programmatically. In contrast to the functions
gtk-tree-view-get-cursor and
gtk-tree-view-set-cursor-on-cell
when moving horizontally "move-cursor" 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 values :logical-positions, :visual-positions, :display-lines, :pages and :buffer-ends are supported. The values :logical-positions and :visual-positions are treated identically.
- direction
- An integer with the direction to move: +1 to move
forwards; -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. For
selection handling refer to the tree widget conceptual overview as well as the
gtk-tree-selection API documentation.
- 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
- A 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
- A 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
- A 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
- A 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.
