A widget for displaying both trees and lists
Widget that displays any object that implements the [[email protected]] interface.
Please refer to the [tree widget conceptual overview](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 [
[email protected]_widget_to_bin_window_coords] (and vice versa), for the latter [
[email protected]_bin_window_to_tree_coords] (and vice versa).
`GtkTreeView` as `GtkBuildable`
The `GtkTreeView` implementation of the `GtkBuildable` interface accepts [[email protected]] objects as `<child>` elements
and exposes the internal [[email protected]] in UI definitions.
An example of a UI definition fragment with `GtkTreeView`:
```xml <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.
- public int append_column (TreeViewColumn column)
Appends column to the list of columns.
- public void collapse_all ()
Recursively collapses all visible, expanded nodes in
this.
- public bool collapse_row (TreePath path)
Collapses a row (hides its child rows, if they exist).
- public void columns_autosize ()
Resizes all columns to their optimal width.
- public void convert_bin_window_to_tree_coords (int bx, int by, out int tx, out int ty)
Converts bin_window coordinates to coordinates for the tree (the full
scrollable area of the tree).
- public void convert_bin_window_to_widget_coords (int bx, int by, out int wx, out int wy)
Converts bin_window coordinates to widget relative coordinates.
- public void convert_tree_to_bin_window_coords (int tx, int ty, out int bx, out int by)
Converts tree coordinates (coordinates in full scrollable area of the
tree) to bin_window coordinates.
- public void convert_tree_to_widget_coords (int tx, int ty, out int wx, out int wy)
Converts tree coordinates (coordinates in full scrollable area of the
tree) to widget coordinates.
- public void convert_widget_to_bin_window_coords (int wx, int wy, out int bx, out int by)
Converts widget coordinates to coordinates for the bin_window.
- public void convert_widget_to_tree_coords (int wx, int wy, out int tx, out int ty)
Converts widget coordinates to coordinates for the tree (the full
scrollable area of the tree).
- public Paintable? create_row_drag_icon (TreePath path)
Creates a `cairo_surface_t` representation of the row at path
.
- public void enable_model_drag_dest (ContentFormats formats, DragAction actions)
Turns this into a drop destination
for automatic DND.
- public void enable_model_drag_source (ModifierType start_button_mask, ContentFormats formats, DragAction actions)
Turns this into a drag source for
automatic DND.
- public void expand_all ()
Recursively expands all nodes in the this
.
- public bool expand_row (TreePath path, bool open_all)
Opens the row so its children are visible.
- public void expand_to_path (TreePath path)
Expands the row at path.
- public bool get_activate_on_single_click ()
- public void get_background_area (TreePath? path, TreeViewColumn? column, out Rectangle rect)
Fills the bounding rectangle in bin_window coordinates for the cell at
the row specified by path and the column specified by column.
- public void get_cell_area (TreePath? path, TreeViewColumn? column, out Rectangle rect)
Fills the bounding rectangle in bin_window coordinates for the cell at
the row specified by path and the column specified by column.
- public unowned TreeViewColumn? get_column (int n)
Gets the `GtkTreeViewColumn` at the given position in the
tree_view.
- public List<unowned TreeViewColumn> get_columns ()
Returns a `GList` of all the `GtkTreeViewColumn`s currently in
this.
- public void get_cursor (out TreePath? path, out unowned TreeViewColumn? focus_column)
Fills in path and focus_column with the
current path and focus column.
- public bool get_dest_row_at_pos (int drag_x, int drag_y, out TreePath? path, out TreeViewDropPosition pos)
Determines the destination row for a given position.
- public void get_drag_dest_row (out TreePath? path, out TreeViewDropPosition pos)
Gets information about the row that is highlighted for feedback.
- public bool get_enable_search ()
Returns whether or not the tree allows to start interactive searching
by typing in text.
- public bool get_enable_tree_lines ()
Returns whether or not tree lines are drawn in
this.
- public unowned TreeViewColumn? get_expander_column ()
Returns the column that is the current expander column, or
null if none has been set.
- public bool get_fixed_height_mode ()
Returns whether fixed height mode is turned on for
this.
- public TreeViewGridLines get_grid_lines ()
Returns which grid lines are enabled in
this.
- public bool get_headers_clickable ()
Returns whether all header columns are clickable.
- public bool get_headers_visible ()
Returns true if the headers on the
this are visible.
- public bool get_hover_expand ()
Returns whether hover expansion mode is turned on for
this.
- public bool get_hover_selection ()
Returns whether hover selection mode is turned on for
this.
- public int get_level_indentation ()
Returns the amount, in pixels, of extra indentation for child levels
in this.
- public unowned TreeModel? get_model ()
Returns the model the `GtkTreeView` is based on.
- public uint get_n_columns ()
Queries the number of columns in the given
this.
- public bool get_path_at_pos (int x, int y, out TreePath? path, out unowned TreeViewColumn? column, out int cell_x, out int cell_y)
Finds the path at the point (x, y), relative
to bin_window coordinates.
- public bool get_reorderable ()
Retrieves whether the user can reorder the tree via drag-and-drop.
- public unowned TreeViewRowSeparatorFunc get_row_separator_func ()
Returns the current row separator function.
- public bool get_rubber_banding ()
Returns whether rubber banding is turned on for
this.
- public int get_search_column ()
Gets the column searched on by the interactive search code.
- public unowned Editable? get_search_entry ()
Returns the `GtkEntry` which is currently in use as interactive search
entry for this.
- public unowned TreeViewSearchEqualFunc get_search_equal_func ()
Returns the compare function currently in use.
- public unowned TreeSelection get_selection ()
Gets the `GtkTreeSelection` associated with
this.
- public bool get_show_expanders ()
Returns whether or not expanders are drawn in
this.
- public int get_tooltip_column ()
Returns the column of this’s model
which is being used for displaying tooltips on this’s rows.
- public bool get_tooltip_context (int x, int y, bool keyboard_tip, out unowned TreeModel? model, out TreePath path, out TreeIter iter)
This function is supposed to be used in a
query_tooltip signal handler for `GtkTreeView`.
- public bool get_visible_range (out TreePath start_path, out TreePath end_path)
Sets start_path and end_path to be the first
and last visible path.
- public void get_visible_rect (out Rectangle visible_rect)
Fills visible_rect with the currently-visible region of
the buffer, in tree coordinates.
- public int insert_column (TreeViewColumn column, int position)
This inserts the column into the
this at position.
- public int insert_column_with_attributes (int position, string? title, CellRenderer cell, ...)
Creates a new `GtkTreeViewColumn` and inserts it into the
this at position.
- public int insert_column_with_data_func (int position, string title, CellRenderer cell, owned TreeCellDataFunc func)
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).
- public bool is_blank_at_pos (int x, int y, out TreePath? path, out unowned TreeViewColumn? column, out int cell_x, out int cell_y)
Determine whether the point (x, y) in
this is blank, that is no cell content nor an expander arrow is drawn at the location.
- public bool is_row_expanded (TreePath path)
- public bool is_rubber_banding_active ()
Returns whether a rubber banding operation is currently being done in
this.
- public void map_expanded_rows (TreeViewMappingFunc func)
Calls func on all expanded rows.
- public void move_column_after (TreeViewColumn column, TreeViewColumn? base_column)
Moves column to be after to base_column.
- public int remove_column (TreeViewColumn column)
Removes column from this
.
- public void scroll_to_cell (TreePath? path, TreeViewColumn? column, bool use_align, float row_align, float col_align)
Moves the alignments of this to the
position specified by column and path.
- public void scroll_to_point (int tree_x, int tree_y)
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.
- public void set_activate_on_single_click (bool single)
Cause the `GtkTreeView`
row_activated signal to be emitted on a single click instead of a double
click.
- public void set_column_drag_function (owned TreeViewColumnDropFunc? func)
Sets a user function for determining where a column may be dropped
when dragged.
- public void set_cursor (TreePath path, TreeViewColumn? focus_column, bool start_editing)
Sets the current keyboard focus to be at path, and
selects it.
- public void set_cursor_on_cell (TreePath path, TreeViewColumn? focus_column, CellRenderer? focus_cell, bool start_editing)
Sets the current keyboard focus to be at path, and
selects it.
- public void set_drag_dest_row (TreePath? path, TreeViewDropPosition pos)
Sets the row that is highlighted for feedback.
- public void set_enable_search (bool enable_search)
If enable_search is set, then the user can type in text
to search through the tree interactively (this is sometimes called "typeahead find").
- public void set_enable_tree_lines (bool enabled)
Sets whether to draw lines interconnecting the expanders in
this.
- public void set_expander_column (TreeViewColumn? column)
Sets the column to draw the expander arrow at.
- public void set_fixed_height_mode (bool enable)
Enables or disables the fixed height mode of
this.
- public void set_grid_lines (TreeViewGridLines grid_lines)
Sets which grid lines to draw in this
.
- public void set_headers_clickable (bool setting)
Allow the column title buttons to be clicked.
- public void set_headers_visible (bool headers_visible)
Sets the visibility state of the headers.
- public void set_hover_expand (bool expand)
Enables or disables the hover expansion mode of
this.
- public void set_hover_selection (bool hover)
Enables or disables the hover selection mode of
this.
- public void set_level_indentation (int indentation)
Sets the amount of extra indentation for child levels to use in
this in addition to the default indentation.
- public void set_model (TreeModel? model)
Sets the model for a `GtkTreeView`.
- public void set_reorderable (bool reorderable)
This function is a convenience function to allow you to reorder models
that support the `GtkTreeDragSourceIface` and the `GtkTreeDragDestIface`.
- public void set_row_separator_func (owned TreeViewRowSeparatorFunc? func)
Sets the row separator function, which is used to determine whether a
row should be drawn as a separator.
- public void set_rubber_banding (bool enable)
Enables or disables rubber banding in this
.
- public void set_search_column (int column)
Sets column as the column where the interactive search
code should search in for the current model.
- public void set_search_entry (Editable? entry)
Sets the entry which the interactive search code will use for this
this.
- public void set_search_equal_func (owned TreeViewSearchEqualFunc search_equal_func)
Sets the compare function for the interactive search capabilities;
note that somewhat like strcmp returning 0 for equality `GtkTreeView`SearchEqualFunc returns
false on matches.
- public void set_show_expanders (bool enabled)
Sets whether to draw and enable expanders and indent child rows in
this.
- public void set_tooltip_cell (Tooltip tooltip, TreePath? path, TreeViewColumn? column, CellRenderer? cell)
Sets the tip area of tooltip to the area path
, column and cell have in common.
- public void set_tooltip_column (int column)
If you only plan to have simple (text-only) tooltips on full rows, you
can use this function to have `GtkTreeView` handle these automatically for you.
- public void set_tooltip_row (Tooltip tooltip, TreePath path)
Sets the tip area of tooltip to be the area covered by
the row at path.
- public void unset_rows_drag_dest ()
- public void unset_rows_drag_source ()