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

Package: gtk

Class gtk:tree-view

Superclasses

gtk:container, gtk:widget, gtk:buildable, gtk:scrollable, 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)
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)
Set 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.
Default value: false

headers-clickable

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

headers-visible

The headers-visible property of type :boolean (Read / Write)
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. This mode is primarily intended for tree views in popups.
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. This mode is primarily intended for tree views in popups.
Default value: false

level-indentation

The level-indentation property of type :int (Read / Write)
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

rules-hint

The rules-hint property of type :boolean (Read / Write)
Set a hint to the theme engine to draw rows in alternating colors.
Warning: The rules-hint property has been deprecated since version 3.14. The theme is responsible for drawing rows using zebra striping.
Default value: false

search-column

The search-column property of type :int (Read / Write)
Model column to search through during interactive search.
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

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

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: an undocumented boolean
arg2: an undocumented boolean
arg3: an 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 :visual-positions and :logical-positions values are treated identically.
direction: The integer for 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.

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.

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.

The "row-collapsed" signal

lambda (view iter path)    :run-last

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 given row has been collapsed (child nodes are hidden).

The "row-expanded" signal

lambda (view iter path)    :run-last

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 given row has been expanded (child nodes are shown).

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

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 given row is about to be collapsed (hide its children nodes). Use this signal if you need to control the collapsibility of individual rows.

The "test-expand-row" signal

lambda (view iter path)    :run-last

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 given row is about to be expanded (show its children nodes). Use this signal if you need to control the expandability of individual rows.

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.