A widget for displaying both trees and lists
Class GtkTreeView
Widget that displays any object that implements the GtkTreeModel 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.
[...]
| Methods | |
| append_column | Appends column to the list of columns. |
| collapse_all | Recursively collapses all visible, expanded nodes in tree_view. |
| collapse_row | Collapses a row (hides its child rows, if they exist). |
| columns_autosize | Resizes all columns to their optimal width. |
| expand_all | Recursively expands all nodes in the tree_view. |
| expand_row | Opens the row so its children are visible. |
| expand_to_path | Expands the row at path. |
| get_column | Gets the GtkTreeViewColumn at the given position in the tree_view. |
| get_columns | Returns an array of all the GtkTreeViewColumn currently in tree_view. |
| get_cursor | Fills in path and focus_column with the current path and focus column. |
| get_expander_column | Returns the column that is the current expander column. |
| get_hadjustment | Gets the GtkAdjustment currently being used for the horizontal aspect. |
| get_headers_clickable | Returns whether all header columns are clickable. |
| get_headers_visible | Returns TRUE if the headers on the tree_view are visible. |
| get_level_indentation | Returns the amount, in pixels, of extra indentation for child levels in tree_view. |
| get_model | Returns the model the GtkTreeView is based on. Returns NULL if the model is unset. |
| get_rules_hint | Gets the setting set by gtk_tree_view_set_rules_hint(). |
| get_show_expanders | Returns whether or not expanders are drawn in tree_view. |
| get_vadjustment | Gets the GtkAdjustment currently being used for the vertical aspect. |
| insert_column | This inserts the column into the tree_view at position. |
| insert_column_with_attributes | Creates a new GtkTreeViewColumn and inserts it into the tree_view at position. |
| insert_column_with_data_func | Convenience function that inserts a new column into the GtkTreeView with the given cell renderer and a GtkCellDataFunc to set cell renderer attributes (normally using data from the model). |
| move_column_after | Moves column to be after to base_column. |
| new_with_model | Creates a new GtkTreeView widget with the model initialized to model. |
| remove_column | Removes column from tree_view. |
| row_activated | Activates the cell determined by path and column. |
| scroll_to_cell | Moves the alignments of tree_view to the position specified by column and path. |
| scroll_to_point | 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. |
| set_column_drag_function | Sets a user function for determining where a column may be dropped when dragged. |
| set_cursor | Sets the current keyboard focus to be at path, and selects it. |
| set_cursor_on_cell | Sets the current keyboard focus to be at path, and selects it. |
| set_expander_column | Sets the column to draw the expander arrow at. |
| set_hadjustment | Sets the GtkAdjustment for the current horizontal aspect. |
| set_headers_clickable | Allow the column title buttons to be clicked. |
| set_headers_visible | Sets the visibility state of the headers. |
| set_level_indentation | Sets the amount of extra indentation for child levels to use in tree_view in addition to the default indentation. |
| set_model | Sets the model for a GtkTreeView. |
| set_rules_hint | This function tells GTK+ that the user interface for your application requires users to read across tree rows and associate cells with one another. |
| set_show_expanders | Sets whether to draw and enable expanders and indent child rows in tree_view. |
| set_vadjustment | Sets the GtkAdjustment for the current vertical aspect. |
| signal_columns_changed | The number of columns of the treeview has changed. |
| signal_cursor_changed | The position of the cursor (focused cell) has changed. |
| signal_expand_collapse_cursor_row | The "expand-collapse-cursor-row" signal is emitted when the row at the cursor needs to be expanded or collapsed. |
| signal_move_cursor | The "move-cursor" signal is emitted when the user moves the cursor using the Right, Left, Up or Down arrow keys or the Page Up, Page Down, Home and End keys. |
| signal_row_activated | The "row-activated" signal is emitted when the method gtk_tree_view_row_activated() is called or the user double clicks a treeview row. |
| signal_row_collapsed | The given row has been collapsed (child nodes are hidden). |
| signal_row_expanded | The given row has been expanded (child nodes are shown). |
| signal_select_all | The "select-all" signal is emitted when the user presses Control+a or Control+/. |
| signal_select_cursor_parent | The "select-cursor-parent" signal is emitted when the user presses Backspace while a row has the cursor. |
| signal_select_cursor_row | The "select-cursor-row" signal is emitted when a non-editable row is selected and one of the keys: Space, Shift+Space, Return or Enter is pressed. |
| signal_set_scroll_adjustments | Set Set the scroll adjustments for the tree view. |
| signal_start_interactive_search | The "start-interactive-search" signal is emitted when the user presses Control+f. |
| signal_test_collapse_row | The given row is about to be collapsed (hide its children nodes). |
| signal_test_expand_row | The given row is about to be expanded (show its children nodes). |
| signal_toggle_cursor_row | The "toggle-cursor-row" signal is emitted when the user presses Control+Space. |
| signal_unselect_all | The "unselect-all" signal is emitted when the user presses Shift+Control+a or Shift+Control+/. |
Appends column to the list of columns.
GtkTreeView.append_column( column )
| column | The GtkTreeViewColumn to add. |
| Return | The number of columns in tree_view after appending. |
If tree_view has "fixed_height" mode enabled, then column must have its "sizing" property set to be GTK_TREE_VIEW_COLUMN_FIXED.
Recursively collapses all visible, expanded nodes in tree_view.
GtkTreeView.collapse_all()
Collapses a row (hides its child rows, if they exist).
GtkTreeView.collapse_row( path )
| path | path to a row in the tree_view. |
| Return | TRUE if the row was collapsed. |
Resizes all columns to their optimal width.
GtkTreeView.columns_autosize()
Only works after the treeview has been realized.
Recursively expands all nodes in the tree_view.
GtkTreeView.expand_all()
Opens the row so its children are visible.
GtkTreeView.expand_row( path, open_all )
| path | GtkTreePath to a row |
| open_all | whether to recursively expand, or just expand immediate children |
| Return | TRUE if the row existed and had children |
Expands the row at path.
GtkTreeView.expand_to_path( path )
| path | GtkTreePath to a row. |
This will also expand all parent rows of path as necessary.
Gets the GtkTreeViewColumn at the given position in the tree_view.
GtkTreeView.get_column( n )
| n | The position of the column, counting from 0. |
| Return | The GtkTreeViewColumn, or NULL if the position is outside the range of columns. |
Returns an array of all the GtkTreeViewColumn currently in tree_view.
GtkTreeView.get_columns()
| Return | A list of GtkTreeViewColumn |
Fills in path and focus_column with the current path and focus column.
GtkTreeView.get_cursor()
| Return | An array [ current cursor path, current focus column ] |
If the cursor isn't currently set, then the returned path will be NULL. If no column currently has focus, then the returned focus_column will be NULL.
Returns the column that is the current expander column.
GtkTreeView.get_expander_column()
| Return | The expander column. |
This column has the expander arrow drawn next to it.
Gets the GtkAdjustment currently being used for the horizontal aspect.
GtkTreeView.get_hadjustment()
| Return | A GtkAdjustment object, or NULL if none is currently being used. |
Returns whether all header columns are clickable.
GtkTreeView.get_headers_clickable()
| Return | TRUE if all header columns are clickable, otherwise FALSE |
Returns TRUE if the headers on the tree_view are visible.
GtkTreeView.get_headers_visible()
| Return | Whether the headers are visible or not. |
Returns the amount, in pixels, of extra indentation for child levels in tree_view.
GtkTreeView.get_level_indentation()
| Return | the amount of extra indentation for child levels in tree_view. A return value of 0 means that this feature is disabled. |
Returns the model the GtkTreeView is based on. Returns NULL if the model is unset.
GtkTreeView.get_model()
| Return | A GtkTreeModel, or NULL if none is currently being used. |
Gets the setting set by gtk_tree_view_set_rules_hint().
GtkTreeView.get_rules_hint()
| Return | TRUE if rules are useful for the user of this tree |
Returns whether or not expanders are drawn in tree_view.
GtkTreeView.get_show_expanders()
| Return | TRUE if expanders are drawn in tree_view, FALSE otherwise. |
Gets the GtkAdjustment currently being used for the vertical aspect.
GtkTreeView.get_vadjustment()
| Return | A GtkAdjustment object, or NULL if none is currently being used. |
This inserts the column into the tree_view at position.
GtkTreeView.insert_column( column, position )
| column | The GtkTreeViewColumn to be inserted. |
| position | The position to insert column in. |
| Return | The number of columns in tree_view after insertion. |
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.
Creates a new GtkTreeViewColumn and inserts it into the tree_view at position.
GtkTreeView.insert_column_with_attributes( position, title, cell, attributes )
| position | The position to insert the new column in. |
| title | The title to set the header to. |
| cell | The GtkCellRenderer. |
| attributes | An array of pairs [ attribute, column, ... ] |
| Return | The number of columns in tree_view after insertion. |
If position is -1, then the newly created column is inserted at the end. The column is initialized with the attributes given. 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.
Convenience function that inserts a new column into the GtkTreeView with the given cell renderer and a GtkCellDataFunc to set cell renderer attributes (normally using data from the model).
GtkTreeView.insert_column_with_data_func( position, title, cell, func, data )
| position | Position to insert, -1 for append |
| title | column title |
| cell | cell renderer for column |
| func | function to set attributes of cell renderer, or nil |
| data | data for func, or nil |
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.
Moves column to be after to base_column.
GtkTreeView.move_column_after( column, base_column )
| column | The GtkTreeViewColumn to be moved. |
| base_column | The GtkTreeViewColumn to be moved relative to, or NULL. |
If base_column is NULL, then column is placed in the first position.
Creates a new GtkTreeView widget with the model initialized to model.
GtkTreeView.new_with_model( model )
| model | the GtkTreeModel |
| Return | A newly created GtkTreeView widget. |
Removes column from tree_view.
GtkTreeView.remove_column( column )
| column | The GtkTreeViewColumn to remove. |
| Return | The number of columns in tree_view after removing. |
Activates the cell determined by path and column.
GtkTreeView.row_activated( path, column )
| path | The GtkTreePath to be activated. |
| column | The GtkTreeViewColumn to be activated. |
Moves the alignments of tree_view to the position specified by column and path.
GtkTreeView.scroll_to_cell( path, column, use_align, row_align, col_align )
| path | The GtkTreePath of the row to move to, or NULL. |
| column | The GtkTreeViewColumn to move horizontally to, or NULL. |
| use_align | whether to use alignment arguments, or FALSE. |
| row_align | The vertical alignment (numeric) of the row specified by path. |
| col_align | The horizontal alignment (numeric) of the column specified by column. |
If column is NULL, then no horizontal scrolling occurs. Likewise, if path is NULL no vertical scrolling occurs. At a minimum, one of column or path need to be non-NULL. row_align determines where the row is placed, and col_align determines where column is placed. Both are expected to be between 0.0 and 1.0. 0.0 means left/top alignment, 1.0 means right/bottom alignment, 0.5 means center.
If use_align is FALSE, then the alignment arguments are ignored, and the tree does the minimum amount of work to scroll the cell onto the screen. This means that the cell will be scrolled to the edge closest to its current position. If the cell is currently visible on the screen, nothing is done.
This function only works if the model is set, and path is a valid row on the model. If the model changes before the tree_view is realized, the centered path will be modified to reflect this change.
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.
GtkTreeView.scroll_to_point( tree_x, tree_y )
| tree_x | X coordinate of new top-left pixel of visible area, or -1 |
| tree_y | Y coordinate of new top-left pixel of visible area, or -1 |
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().
If either tree_x or tree_y are -1, then that direction isn't scrolled.
Sets a user function for determining where a column may be dropped when dragged.
GtkTreeView.set_column_drag_function( func, user_data )
| func | A function to determine which columns are reorderable, or NULL. |
| user_data | User data to be passed to func, or NULL. |
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 GtkTreeViewColumn being dragged, the two GtkTreeViewColumn determining the drop spot, and user_data. If either of the GtkTreeViewColumn arguments for the drop spot are NULL, then they indicate an edge. If func is set to be NULL, then tree_view reverts to the default behavior of allowing all columns to be dropped everywhere.
Sets the current keyboard focus to be at path, and selects it.
GtkTreeView.set_cursor( path, focus_column, start_editing )
| path | A GtkTreePath |
| focus_column | A GtkTreeViewColumn, or NULL. |
| start_editing | TRUE if the specified cell should start being edited. |
This is useful when you want to focus the user's attention on a particular row. If focus_column is not NULL, then focus is given to the column specified by it. Additionally, if focus_column is specified, and start_editing is TRUE, then editing should be started in the specified cell. This function is often followed by gtk_widget_grab_focus (tree_view) in order to give keyboard focus to the widget. Please note that editing can only happen when the widget is realized.
If path is invalid for model, the current cursor (if any) will be unset and the function will return without failing.
Sets the current keyboard focus to be at path, and selects it.
GtkTreeView.set_cursor_on_cell( path, focus_column, focus_cell, start_editing )
| path | A GtkTreePath |
| focus_column | A GtkTreeViewColumn, or NULL. |
| focus_cell | A GtkCellRenderer, or NULL. |
| start_editing | TRUE if the specified cell should start being edited. |
This is useful when you want to focus the user's attention on a particular row. If focus_column is not NULL, then focus is given to the column specified by it. If focus_column and focus_cell are not NULL, and focus_column contains 2 or more editable or activatable cells, then focus is given to the cell specified by focus_cell. Additionally, if focus_column is specified, and start_editing is TRUE, then editing should be started in the specified cell. This function is often followed by gtk_widget_grab_focus (tree_view) in order to give keyboard focus to the widget. Please note that editing can only happen when the widget is realized.
If path is invalid for model, the current cursor (if any) will be unset and the function will return without failing.
Sets the column to draw the expander arrow at.
GtkTreeView.set_expander_column( column )
| column | NULL, or the GtkTreeViewColumn to draw the expander arrow at. |
It must be in tree_view. If column is NULL, then the expander arrow is always at the first visible column.
If you do not want expander arrow to appear in your tree, set the expander column to a hidden column.
Sets the GtkAdjustment for the current horizontal aspect.
GtkTreeView.set_hadjustment( adjustment )
| adjustment | The GtkAdjustment to set, or NULL. |
Allow the column title buttons to be clicked.
GtkTreeView.set_headers_clickable( setting )
| setting | TRUE if the columns are clickable. |
Sets the visibility state of the headers.
GtkTreeView.set_headers_visible( headers_visible )
| headers_visible | TRUE if the headers are visible |
Sets the amount of extra indentation for child levels to use in tree_view in addition to the default indentation.
GtkTreeView.set_level_indentation( indentation )
| indentation | the amount, in pixels, of extra indentation in tree_view. |
The value should be specified in pixels, a value of 0 disables this feature and in this case only the default indentation will be used. This does not have any visible effects for lists.
Sets the model for a GtkTreeView.
GtkTreeView.set_model( model )
| model | The model, or Nil. |
If the tree_view already has a model set, it will remove it before setting the new model. If model is NULL, then it will unset the old model.
This function tells GTK+ that the user interface for your application requires users to read across tree rows and associate cells with one another.
GtkTreeView.set_rules_hint( setting )
| setting | TRUE if the tree requires reading across rows |
By default, GTK+ will then render the tree with alternating row colors. Do not use it just because you prefer the appearance of the ruled tree; that's a question for the theme. Some themes will draw tree rows in alternating colors even when rules are turned off, and users who prefer that appearance all the time can choose those themes. You should call this function only as a semantic hint to the theme engine that your tree makes alternating colors useful from a functional standpoint (since it has lots of columns, generally).
Sets whether to draw and enable expanders and indent child rows in tree_view.
GtkTreeView.set_show_expanders( enabled )
| enabled | TRUE to enable expander drawing, FALSE otherwise. |
When disabled there will be no expanders visible in trees and there will be no way to expand and collapse rows by default. Also note that hiding the expanders will disable the default indentation. You can set a custom indentation in this case using gtk_tree_view_set_level_indentation(). This does not have any visible effects for lists.
Sets the GtkAdjustment for the current vertical aspect.
GtkTreeView.set_vadjustment( adjustment )
| adjustment | The GtkAdjustment to set, or NULL. |
The number of columns of the treeview has changed.
GtkTreeView.signal_columns_changed()
The position of the cursor (focused cell) has changed.
GtkTreeView.signal_cursor_changed()
The "expand-collapse-cursor-row" signal is emitted when the row at the cursor needs to be expanded or collapsed.
GtkTreeView.signal_expand_collapse_cursor_row()
The "move-cursor" signal is emitted when the user moves the cursor using the Right, Left, Up or Down arrow keys or the Page Up, Page Down, Home and End keys.
GtkTreeView.signal_move_cursor()
The "row-activated" signal is emitted when the method gtk_tree_view_row_activated() is called or the user double clicks a treeview row.
GtkTreeView.signal_row_activated()
It is also emitted when a non-editable row is selected and one of the keys: Space, Shift+Space, Return or Enter is pressed.
For selection handling refer to the tree widget conceptual overview as well as GtkTreeSelection.
The given row has been collapsed (child nodes are hidden).
GtkTreeView.signal_row_collapsed()
The given row has been expanded (child nodes are shown).
GtkTreeView.signal_row_expanded()
The "select-all" signal is emitted when the user presses Control+a or Control+/.
GtkTreeView.signal_select_all()
The "select-cursor-parent" signal is emitted when the user presses Backspace while a row has the cursor.
GtkTreeView.signal_select_cursor_parent()
The "select-cursor-row" signal is emitted when a non-editable row is selected and one of the keys: Space, Shift+Space, Return or Enter is pressed.
GtkTreeView.signal_select_cursor_row()
Set Set the scroll adjustments for the tree view.
GtkTreeView.signal_set_scroll_adjustments()
Usually scrolled containers like GtkScrolledWindow will emit this signal to connect two instances of GtkScrollbar to the scroll directions of the GtkTreeView the scroll adjustments for the tree view.
The "start-interactive-search" signal is emitted when the user presses Control+f.
GtkTreeView.signal_start_interactive_search()
The given row is about to be collapsed (hide its children nodes).
GtkTreeView.signal_test_collapse_row()
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).
GtkTreeView.signal_test_expand_row()
Use this signal if you need to control the expandability of individual rows.
The "toggle-cursor-row" signal is emitted when the user presses Control+Space.
GtkTreeView.signal_toggle_cursor_row()
The "unselect-all" signal is emitted when the user presses Shift+Control+a or Shift+Control+/.
GtkTreeView.signal_unselect_all()