Class tree-view - cl-cffi-gtk4 API documentation

Package: gtk

Class gtk:tree-view

Superclasses

gtk:widget, gobject:initially-unowned, gtk:accessible, gtk:buildable, gtk:constraint-target, gobject:object, common-lisp:standard-object, common-lisp:t

Documented Subclasses

None

Direct Slots

activate-on-single-click

The activate-on-single-click property of type :boolean (Read / Write)
Specifies whether the "row-activated" signal will be emitted after a single click.
Default value: false

enable-grid-lines

The enable-grid-lines property of type gtk:tree-view-grid-lines (Read / Write)
Whether grid lines should be drawn in the tree view.
Default value: :none

enable-search

The enable-search property of type :boolean (Read / Write)
Whether the tree view allows user to search through columns interactively.
Default value: true

enable-tree-lines

The enable-tree-lines property of type :boolean (Read / Write)
Whether tree lines should be drawn in the tree view.
Default value: false

expander-column

The expander-column property of type gtk:tree-view-column (Read / Write)
The column for the expander column.

fixed-height-mode

The fixed-height-mode property of type :boolean (Read / Write)
Setting this property to true speeds up the tree view by assuming that all rows have the same height. Only enable this option if all rows are the same height. Please see the gtk:tree-view-fixed-height-mode function for more information on this option.
Default value: false

headers-clickable

The headers-clickable property of type :boolean (Read / Write)
Whether column headers respond to click events.
Default value: true

headers-visible

The headers-visible property of type :boolean (Read / Write)
Wether to show the column header buttons.
Default value: true

hover-expand

The hover-expand property of type :boolean (Read / Write)
Enables or disables the hover expansion mode of the tree view. Hover expansion makes rows expand or collapse if the pointer moves over them.
Default value: false

hover-selection

The hover-selection property of type :boolean (Read / Write)
Enables or disables the hover selection mode of the tree view. Hover selection makes the selected row follow the pointer. Currently, this works only for the :single and :browse selection modes.
Default value: false

level-indentation

The level-indentation property of type :int (Read / Write)
The extra indentation for each level.
Allowed values: >= 0
Default value: 0

model

The model property of type gtk:tree-model (Read / Write)
The model for the tree view.

reorderable

The reorderable property of type :boolean (Read / Write)
The tree view is reorderable.
Default value: false

rubber-banding

The rubber-banding property of type :boolean (Read / Write)
Whether to enable selection of multiple items by dragging the mouse pointer.
Default value: false

search-column

The search-column property of type :int (Read / Write)
Model column to search through during interactive search.
The allowed values: >= -1
Default value: -1

show-expanders

The show-expanders property of type :boolean (Read / Write)
True if the view has expanders.
Default value: true

The tooltip-column property of type :int (Read / Write)
The column in the model containing the tooltip texts for the rows.
Allowed values: >= -1
Default value: -1

Details

Widget that displays any object that implements the gtk:tree-model interface.

Figure: GtkTreeView

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:

Figure: Tree view coordinates

Coordinate systems in the gtk:tree-view API:

Widget coordinates: Coordinates relative to the widget.
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 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 column header widgets' CSS nodes. For rubberband selection, a subnode with name rubberband is used.

Warning

The gtk:tree-view implementation is deprecated since 4.10. Use the gtk:list-view implementation for lists, and the gtk:column-view implementation for tabular lists.

Signal Details

The "columns-changed" signal

lambda (view)    :run-last

view: The gtk:tree-view widget on which the signal is emitted.

The number of columns of the tree view has changed.

The "cursor-changed" signal

lambda (view)    :run-last

view: The gtk:tree-view widget on which the signal is emitted.

The position of the cursor (focused cell) has changed.

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: undocumented boolean
arg2: undocumented boolean
arg3: undocumented boolean

The "move-cursor" signal

lambda (view step direction)    :action

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 :logical-positions and :visual-positions values are treated identically.
direction: The 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.

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 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 "move-cursor" does not reset the current selection.

The "row-activated" signal

lambda (view path column)    :action

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 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.