TreeView
A widget for displaying both trees and lists
Widget that displays any object that implements the iface@Gtk.TreeModel interface.
Please refer to the section-tree-widget.html for an overview of all the objects and data types related to the tree widget and how they work together.
Coordinate systems in GtkTreeView API
Several different coordinate systems are exposed in the GtkTreeView API. These are:
Widget coordinates: Coordinates relative to the widget (usually
widget->window).Bin window coordinates: Coordinates relative to the window that GtkTreeView renders to.
Tree coordinates: Coordinates relative to the entire scrollable area of GtkTreeView. 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 method@Gtk.TreeView.convert_widget_to_bin_window_coords (and vice versa), for the latter method@Gtk.TreeView.convert_bin_window_to_tree_coords (and vice versa).
GtkTreeView as GtkBuildable
The GtkTreeView implementation of the GtkBuildable interface accepts class@Gtk.TreeViewColumn objects as <child> elements and exposes the internal class@Gtk.TreeSelection in UI definitions.
An example of a UI definition fragment with GtkTreeView:
<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
│ ├── button
│ │ ╰── [sort-indicator]
┊ ┊
│ ╰── button
│ ╰── [sort-indicator]
│
├── [rubberband]
╰── [dndtarget]GtkTreeView has a main CSS node with name treeview and style class .view. It has a subnode with name header, which is the parent for all the column header widgets' CSS nodes.
Each column header consists of a button, which among other content, has a child with name sort-indicator, which carries the .ascending or .descending style classes when the column header should show a sort indicator. The CSS is expected to provide a suitable image using the -gtk-icon-source property.
For rubberband selection, a subnode with name rubberband is used.
For the drop target location during DND, a subnode with name dndtarget is used.
Skipped during bindings generation
parameter
tx: tx: Out parameter is not supportedparameter
wx: wx: Out parameter is not supportedparameter
bx: bx: Out parameter is not supportedparameter
wx: wx: Out parameter is not supportedparameter
bx: bx: Out parameter is not supportedparameter
tx: tx: Out parameter is not supportedparameter
path: path: Out parameter is not supportedparameter
path: path: Out parameter is not supportedparameter
path: path: Out parameter is not supportedparameter
path: path: Out parameter is not supportedmethod
get_row_separator_func: Return type TreeViewRowSeparatorFunc is unsupportedmethod
get_search_equal_func: Return type TreeViewSearchEqualFunc is unsupportedparameter
model: model: Out parameter is not supportedparameter
start_path: start_path: Out parameter is not supportedmethod
insert_column_with_attributes: Varargs parameter is not supportedparameter
path: path: Out parameter is not supportedmethod
enable-grid-lines: Property has no getter nor setter
Constructors
Properties
The accessible role of the given GtkAccessible implementation.
The activate-on-single-click property specifies whether the "row-activated" signal will be emitted after a single click.
A list of css classes applied to this widget.
Setting the ::fixed-height-mode property to true speeds up GtkTreeView by assuming that all rows have the same height. Only enable this option if all rows are the same height. Please see gtk_tree_view_set_fixed_height_mode() for more information on this option.
Whether the widget should grab focus when it is clicked with the mouse.
Horizontal GtkAdjustment of the scrollable widget.
Enables or disables the emission of the ::query-tooltip signal on @widget.
Whether to use the hexpand property.
Enables or disables the hover expansion mode of @tree_view. Hover expansion makes rows expand or collapse if the pointer moves over them.
Enables or disables the hover selection mode of @tree_view. Hover selection makes the selected row follow the pointer. Currently, this works only for the selection modes %GTK_SELECTION_SINGLE and %GTK_SELECTION_BROWSE.
Determines when horizontal scrolling should start.
The GtkLayoutManager instance to use to compute the preferred size of the widget, and allocate its children.
Extra indentation for each level.
Margin on bottom side of widget.
Margin on start of widget, horizontally.
Whether the widget will receive the default action when it is focused.
The scale factor of the widget.
true if the view has expanders.
Sets the text of tooltip to be the given string, which is marked up with Pango markup.
Sets the text of tooltip to be the given string.
Vertical GtkAdjustment of the scrollable widget.
Whether to use the vexpand property.
Determines when vertical scrolling should start.
Functions
Enable or disable an action installed with gtk_widget_class_install_action().
Looks up the action in the action groups associated with
Activates the default.activate action from @widget.
For widgets that can be “activated” (buttons, menu items, etc.), this function activates them.
Adds @controller to @widget so that it will receive events.
Adds a style class to @widget.
Adds a widget to the list of mnemonic labels for this widget.
Queues an animation frame update and adds a callback to be called before each frame.
This function is only used by GtkWidget subclasses, to assign a size, position and (optionally) baseline to their child widgets.
Requests the user's screen reader to announce the given message.
Appends @column to the list of columns. If @tree_view has “fixed_height” mode enabled, then @column must have its “sizing” property set to be GTK_TREE_VIEW_COLUMN_FIXED.
Called by widgets as the user moves around the window using keyboard shortcuts.
Recursively collapses all visible, expanded nodes in @tree_view.
Collapses a row (hides its child rows, if they exist).
Resizes all columns to their optimal width. Only works after the treeview has been realized.
Computes the bounds for @widget in the coordinate space of @target.
Computes whether a container should give this widget extra space when possible.
Translates the given @point in @widget's coordinates to coordinates relative to @target’s coordinate system.
Computes a matrix suitable to describe a transformation from
The number of columns of the treeview has changed.
The position of the cursor (focused cell) has changed.
Signals that all holders of a reference to the widget should release the reference that they hold.
Emitted when the text direction of a widget changes.
Emitted when @widget is hidden.
Emitted if keyboard navigation fails.
Emitted when @widget is going to be mapped.
Emitted when a widget is activated via a mnemonic.
The GtkTreeView::move-cursor signal is a class@Gtk.SignalAction which gets emitted when the user presses one of the cursor keys.
Emitted when the focus is moved.
Emitted when the widget’s tooltip is about to be shown.
Emitted when @widget is associated with a GdkSurface.
The "row-activated" signal is emitted when the method method@Gtk.TreeView.row_activated is called.
The given row has been collapsed (child nodes are hidden).
The given row has been expanded (child nodes are shown).
Emitted when @widget is shown.
Emitted when the widget state changes.
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 given row is about to be expanded (show its children nodes). Use this signal if you need to control the expandability of individual rows.
Emitted when @widget is going to be unmapped.
Emitted when the GdkSurface associated with @widget is destroyed.
Creates a new PangoContext with the appropriate font map, font options, font description, and base direction for drawing text for this widget.
Creates a new PangoLayout with the appropriate font map, font description, and base direction for drawing text for this widget.
Creates a cairo_surface_t representation of the row at @path. This image is used for a drag icon.
Clears the template children for the given widget.
Checks to see if a drag movement has passed the GTK drag threshold.
Turns @tree_view into a drop destination for automatic DND. Calling this method sets GtkTreeView:reorderable to false.
Turns @tree_view into a drag source for automatic DND. Calling this method sets GtkTreeView:reorderable to false.
Expands the row at @path. This will also expand all parent rows of
Retrieves the accessible parent for an accessible object.
Retrieves the accessible role of an accessible object.
Returns the baseline that has currently been allocated to @widget.
Returns the height that has currently been allocated to @widget.
Returns the width that has currently been allocated to @widget.
Gets the first ancestor of @widget with type @widget_type.
Retrieves the accessible implementation for the given GtkAccessible.
Fills the bounding rectangle in bin_window coordinates for the cell at the row specified by @path and the column specified by @column. If @path is null, or points to a node not found in the tree, the @y and @height fields of the rectangle will be filled with 0. If @column is null, the @x and @width fields will be filled with 0. The returned rectangle is equivalent to the
Returns the baseline that has currently been allocated to @widget.
Gets the ID of the @buildable object.
Fills the bounding rectangle in bin_window coordinates for the cell at the row specified by @path and the column specified by @column. If @path is null, or points to a path not currently displayed, the @y and @height fields of the rectangle will be filled with 0. If @column is null, the @x and @width fields will be filled with 0. The sum of all cell rects does not cover the entire tree; there are extra pixels in between rows, for example. The returned rectangle is equivalent to the @cell_area passed to gtk_cell_renderer_render(). This function is only valid if @tree_view is realized.
Gets the value set with gtk_widget_set_child_visible().
Gets the clipboard object for @widget.
Gets the GtkTreeViewColumn at the given position in the #tree_view.
Returns a GList of all the GtkTreeViewColumns currently in @tree_view. The returned list must be freed with g_list_free ().
Gets the reading direction for a particular widget.
Get the GdkDisplay for the toplevel window associated with this widget.
Retrieves the first accessible child of an accessible object.
Returns the widget’s first child.
Returns the current focus child of @widget.
Gets the font map of @widget.
Obtains the frame clock for a widget.
Returns which grid lines are enabled in @tree_view.
Retrieves the GtkAdjustment used for horizontal scrolling.
Gets the horizontal GtkScrollablePolicy.
Returns the widget’s last child.
Queries the number of columns in the given @tree_view.
Retrieves the next accessible sibling of an accessible object
Returns the widget’s next sibling.
Gets a PangoContext with the appropriate font map, font description, and base direction for this widget.
Query a platform state, such as focus.
Retrieves the minimum and natural size of a widget, taking into account the widget’s preference for height-for-width management.
Returns the widget’s previous sibling.
Gets the primary clipboard of @widget.
Determines whether @widget is realized.
Gets whether the widget prefers a height-for-width layout or a width-for-height layout.
Returns the GtkEntry which is currently in use as interactive search entry for @tree_view. In case the built-in entry is being used, null will be returned.
Gets the GtkTreeSelection associated with @tree_view.
Returns the widget’s sensitivity.
Gets the settings object holding the settings used for this widget.
Returns the content width or height of the widget.
Returns the widget state as a flag set.
Returns the style context associated to @widget.
Fetch an object build from the template XML for @widget_type in this @widget instance.
Retrieves the GtkAdjustment used for vertical scrolling.
Determines whether the widget is visible.
Fills @visible_rect with the currently-visible region of the buffer, in tree coordinates. Convert to bin_window coordinates with gtk_tree_view_convert_tree_to_bin_window_coords(). Tree coordinates start at 0,0 for row 0 of the tree, and cover the entire scrollable area of the tree.
Gets the vertical GtkScrollablePolicy.
Returns whether @css_class is currently applied to @widget.
Determines whether @widget is the current default widget within its toplevel.
Determines if the widget should show a visible indication that it has the global input focus.
Returns whether the widget is currently being destroyed.
Creates and initializes child widgets defined in templates.
Inserts @group into @widget.
Inserts @widget into the child widget list of @parent.
Inserts @widget into the child widget list of @parent.
This inserts the @column into the @tree_view at @position. If @position is -1, then the column is inserted at the end. If @tree_view has “fixed_height” mode enabled, then @column must have its “sizing” property set to be GTK_TREE_VIEW_COLUMN_FIXED.
Convenience function that inserts a new column into the GtkTreeView with the given cell renderer and a GtkTreeCellDataFunc to set cell renderer attributes (normally using data from the model). See also gtk_tree_view_column_set_cell_data_func(), gtk_tree_view_column_pack_start(). If @tree_view has “fixed_height” mode enabled, then the new column will have its “sizing” property set to be GTK_TREE_VIEW_COLUMN_FIXED.
Determines whether @widget is somewhere inside @ancestor, possibly with intermediate containers.
Determines whether @widget can be drawn to.
Returns whether a rubber banding operation is currently being done in @tree_view.
Returns the widget’s effective sensitivity.
Emits the ::keynav-failed signal on the widget.
Returns the widgets for which this widget is the target of a mnemonic.
Calls @func on all expanded rows.
Emits the ::mnemonic-activate signal.
Moves @column to be after to @base_column. If @base_column is null, then
Returns a GListModel to track the children of @widget.
Returns a GListModel to track the class@Gtk.EventControllers of @widget.
Flags the widget for a rerun of the vfunc@Gtk.Widget.size_allocate function.
Flags a widget to have its size renegotiated.
Removes @column from @tree_view.
Removes @controller from @widget, so that it doesn't process events anymore.
Removes a style from @widget.
Removes a widget from the list of mnemonic labels for this widget.
Removes a tick callback previously registered with gtk_widget_add_tick_callback().
Resets the accessible @property to its default value.
Resets the accessible @relation to its default value.
Resets the accessible @state to its default value.
Activates the cell determined by @path and @column.
Returns true if the node pointed to by @path is expanded in @tree_view.
Moves the alignments of @tree_view to the position specified by @column and
Scrolls the tree view such that the top-left corner of the visible area is @tree_x, @tree_y, where @tree_x and @tree_y are specified in tree coordinates. The @tree_view must be realized before this function is called. If it isn't, you probably want to be using gtk_tree_view_scroll_to_cell().
Sets the parent and sibling of an accessible object.
Sets whether @widget should be mapped along with its parent.
Sets a user function for determining where a column may be dropped when dragged. This function is called on every column pair in turn at the beginning of a column drag to determine where a drop can take place. The arguments passed to @func are: the @tree_view, the GtkTreeViewColumn being dragged, the two GtkTreeViewColumns determining the drop spot, and
Sets the current keyboard focus to be at @path, and selects it. This is useful when you want to focus the user’s attention on a particular row. If
Sets a named cursor to be shown when pointer devices point towards @widget.
Sets the current keyboard focus to be at @path, and selects it. This is useful when you want to focus the user’s attention on a particular row. If
Sets the reading direction on a particular widget.
Sets the row that is highlighted for feedback. If @path is null, an existing highlight is removed.
Set @child as the current focus child of @widget.
Sets the font map to use for Pango rendering.
Sets which grid lines to draw in @tree_view.
Sets the horizontal adjustment of the GtkScrollable.
Sets the GtkScrollablePolicy.
Set all margins to the same value.
Set start and end margin to horizontal and top and bottom margin to vertical
Set margins.
Sets the row separator function, which is used to determine whether a row should be drawn as a separator. If the row separator function is null, no separators are drawn. This is the default value.
Sets the entry which the interactive search code will use for this
Sets the compare function for the interactive search capabilities; note that somewhat like strcmp() returning 0 for equality GtkTreeViewSearchEqualFunc returns false on matches.
Sets the sensitivity of a widget.
Sets the minimum size of a widget.
Turns on flag values in the current widget state.
Sets the tip area of @tooltip to the area @path, @column and @cell have in common. For example if @path is null and @column is set, the tip area will be set to the full area covered by @column. See also gtk_tooltip_set_tip_area().
Sets the tip area of @tooltip to be the area covered by the row at @path. See also gtk_tree_view_set_tooltip_column() for a simpler alternative. See also gtk_tooltip_set_tip_area().
Sets the vertical adjustment of the GtkScrollable.
Sets the visibility state of @widget.
Sets the GtkScrollablePolicy.
Returns whether @widget should contribute to the measuring and allocation of its parent.
Triggers a tooltip query on the display where the toplevel of @widget is located.
Undoes the effect of gtk_tree_view_enable_model_drag_dest(). Calling this method sets GtkTreeView:reorderable to false.
Undoes the effect of gtk_tree_view_enable_model_drag_source(). Calling this method sets GtkTreeView:reorderable to false.
Turns off flag values for the current widget state.
Updates the next accessible sibling of @self.