gtk.TreeView
Prev | The gtk Class Reference | Next

## gtk.TreeView

gtk.TreeView — a widget for displaying both trees and lists.

## Synopsis

    class gtk.TreeView(gtk.Container):
        gtk.TreeView(model=None)
        def get_model()
        def set_model(model=None)
        def get_selection()
        def get_hadjustment()
        def set_hadjustment(adjustment)
        def get_vadjustment()
        def set_vadjustment(adjustment)
        def get_headers_visible()
        def set_headers_visible(headers_visible)
        def columns_autosize()
        def set_headers_clickable(active)
        def set_rules_hint(setting)
        def get_rules_hint()
        def append_column(column)
        def remove_column(column)
        def insert_column(column, position)
        def insert_column_with_attributes(position, title, cell, ...)
        def insert_column_with_data_func(position, title, cell, func, data=None)
        def get_column(n)
        def get_columns()
        def move_column_after(column, base_column)
        def set_expander_column(column)
        def get_expander_column()
        def set_column_drag_function(func, user_data)
        def scroll_to_point(tree_x, tree_y)
        def scroll_to_cell(path, column, use_align, row_align, col_align)
        def row_activated(path, column)
        def expand_all()
        def collapse_all()
        def expand_to_path(path)
        def expand_row(path, open_all)
        def collapse_row(path)
        def map_expanded_rows(func, data)
        def row_expanded(path)
        def set_reorderable(reorderable)
        def get_reorderable()
        def set_cursor(path, focus_column=None, start_editing=False)
        def set_cursor_on_cell(path, focus_column=None, focus_cell=None, start_editing=False)
        def get_cursor()
        def get_bin_window()
        def get_path_at_pos(x, y)
        def get_cell_area(path, column)
        def get_background_area(path, column)
        def get_visible_rect()
        def widget_to_tree_coords(wx, wy)
        def tree_to_widget_coords(tx, ty)
        def enable_model_drag_source(start_button_mask, targets, actions)
        def enable_model_drag_dest(targets, actions)
        def unset_rows_drag_source()
        def unset_rows_drag_dest()
        def set_drag_dest_row(path, pos)
        def get_drag_dest_row()
        def get_dest_row_at_pos(x, y)
        def create_row_drag_icon(path)
        def set_enable_search(enable_search)
        def get_enable_search()
        def get_search_column()
        def set_search_column(column)
        def set_search_equal_func(func=None, user_data=None)
        def get_fixed_height_mode()
        def set_fixed_height_mode(enable)
        def get_hover_selection()
        def set_hover_selection(hover)
        def get_hover_expand()
        def set_hover_expand(expand)
        def set_row_separator_func(func=None, user_data=None)
        def get_visible_range()
        def get_headers_clickable()
        def get_search_entry()
        def set_search_entry(entry=None)
        def set_search_position_func(func, data=None)
        def set_rubber_banding(enable)
        def get_rubber_banding()
        def get_grid_lines()
        def set_grid_lines(grid_lines)
        def get_enable_tree_lines()
        def set_enable_tree_lines(enabled)

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.Widget
          +-- gtk.Container
            +-- gtk.TreeView

## gtk.TreeView Properties

gtk.Object Properties

gtk.Widget Properties

gtk.Container Properties

"enable-grid-lines" | Read-Write | If `True` grid lines should be drawn in the tree view
"enable-search" | Read-Write | If `True`, the user can search through columns interactively. Default value: `True`
"enable-tree-lines" | Read-Write | If `True` tree lines should be drawn in the tree view
"expander-column" | Read-Write | The column for the expander
"fixed-height-mode" | Read-Write | If `True`, assume all rows have the same height thereby speeding up display. Default value: `False`. Available in GTK+ 2.4 and above.
"hadjustment" | Read-Write | The horizontal Adjustment for the widget
"headers-clickable" | Write | If `True`, the column headers respond to click events. Default value: `False`
"headers-visible" | Read-Write | If `True`, show the column header buttons. Default value: `True`
"hover-expand" | Read-Write | If `True`, rows expand or collapse if the pointer moves over them. This mode is primarily intended for treeviews in popups, e.g. in `gtk.ComboBox` or `gtk.EntryCompletion`. Default value: `False`. Available in GTK+ 2.6 and above.
"hover-selection" | Read-Write | If `True`, the selected row follows the pointer. Currently, this works only for the selection modes `gtk.SELECTION_SINGLE` and `gtk.SELECTION_BROWSE`. This mode is primarily intended for treeviews in popups, e.g. in `gtk.ComboBox` or `gtk.EntryCompletion`. Default value: `False`. Available in GTK+ 2.6 and above.
"level-indentation" | Read-Write | Extra indentation for each level
"model" | Read-Write | The model for the tree view
"reorderable" | Read-Write | If `True`, the view is reorderable. Default value: `False`.
"rubber-banding" | Read-Write | If `True` enable selection of multiple items by dragging the mouse pointer
"rules-hint" | Read-Write | If `True`, hint to the theme engine to draw rows in alternating colors. Default value: `False`.
"search-column" | Read-Write | The model column to search when searching through code. Allowed values: >= -1. Default value: -1
"show-expanders" | Read-Write | View has expanders
"vadjustment" | Read-Write | The vertical Adjustment for the widget

## gtk.TreeView Style Properties

"allow-rules" | Read | If `True`, allow drawing of alternating color rows. Default value: `True`
"even-row-color" | Read | The `gtk.gdk.Color` to use for even rows. Available in GTK+ 2.2 and above.
"expander-size" | Read | The size of the expander arrow. Allowed values: >= 0. Default value: 12
"grid-line-pattern" | Read | Dash pattern used to draw the tree view grid lines
"grid-line-width" | Read | Width, in pixels, of the tree view grid lines
"horizontal-separator" | Read | The horizontal space between cells. Must be an even number. Allowed values: >= 0. Default value: 2
"indent-expanders" | Read | If `True`, the expanders are indented.
"odd-row-color" | Read | The `gtk.gdk.Color` to use for odd rows. Available in GTK+ 2.2 and above.
"row-ending-details" | Read | Enable extended row background theming
"tree-line-pattern" | Read | Dash pattern used to draw the tree view lines
"tree-line-width" | Read | Width, in pixels, of the tree view lines
"vertical-separator" | Read | The vertical space between cells. Must be an even number. Allowed values: >= 0. Default value: 2

## gtk.TreeView Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

gtk.Widget Signal Prototypes

gtk.Container Signal Prototypes

"columns-changed" | `def callback(`treeview`, `user_param1`, `...`)`
"cursor-changed" | `def callback(`treeview`, `user_param1`, `...`)`
"expand-collapse-cursor-row" | `def callback(`treeview`, `logical`, `expand`, `open_all`, `user_param1`, `...`)`
"move-cursor" | `def callback(`treeview`, `step`, `count`, `user_param1`, `...`)`
"row-activated" | `def callback(`treeview`, `path`, `view_column`, `user_param1`, `...`)`
"row-collapsed" | `def callback(`treeview`, `iter`, `path`, `user_param1`, `...`)`
"row-expanded" | `def callback(`treeview`, `iter`, `path`, `user_param1`, `...`)`
"select-all" | `def callback(`treeview`, `user_param1`, `...`)`
"select-cursor-parent" | `def callback(`treeview`, `user_param1`, `...`)`
"select-cursor-row" | `def callback(`treeview`, `start_editing`, `user_param1`, `...`)`
"set-scroll-adjustments" | `def callback(`treeview`, `hadjustment`, `vadjustment`, `user_param1`, `...`)`
"start-interactive-search" | `def callback(`treeview`, `user_param1`, `...`)`
"test-collapse-row" | `def callback(`treeview`, `iter`, `path`, `user_param1`, `...`)`
"test-expand-row" | `def callback(`treeview`, `iter`, `path`, `user_param1`, `...`)`
"toggle-cursor-row" | `def callback(`treeview`, `user_param1`, `...`)`
"unselect-all" | `def callback(`treeview`, `user_param1`, `...`)`

## Description

A `gtk.TreeView` widget is used to display the contents of any model implementing the `gtk.TreeModel` interface. The tree models provided standard with `GTK+` and `PyGTK` are:

- `gtk.ListStore`
- `gtk.TreeStore`
- `gtk.TreeModelSort`

In addition, `PyGTK` provides `gtk.GenericTreeModel` that allows you to create your own tree model entirely in Python.

The `gtk.TreeView` uses columns and cell renderers to actually display the model information. `GTK+` and `PyGTK` provides the `gtk.TreeViewColumn` to manage the display of a column and the following cell renderers:

- `gtk.CellRendererPixbuf`
- `gtk.CellRendererText`
- `gtk.CellRendererToggle`

In addition, `PyGTK` provides the `gtk.GenericCellRenderer` that allows you to create your own cell renderers entirely in Python.

## Constructor

        gtk.TreeView(model=None)

`model` : | the tree model to display
Returns : | A new `gtk.TreeView` widget.

Creates a new `gtk.TreeView` widget displaying the model specified by `model`.

## Methods

### gtk.TreeView.get_model

        def get_model()

Returns : | the current `gtk.TreeModel`, or `None` if none is currently being used.

The `get_model`() method returns the value of the "model" property containing the model the `gtk.TreeView` is displaying or `None` there is no the model.

### gtk.TreeView.set_model

        def set_model(model=None)

`model` : | the new tree model to use with the treeview

The `set_model`() method sets the "model" property for the treeview to the value of `model`. If the treeview already has a model set, this method will remove it before setting the new model. If `model` is `None`, it will unset the old model.

### gtk.TreeView.get_selection

        def get_selection()

Returns : | A `gtk.TreeSelection` object.

The `get_selection`() method returns the current `gtk.TreeSelection` associated with the treeview.

### gtk.TreeView.get_hadjustment

        def get_hadjustment()

Returns : | a `gtk.Adjustment` object, or `None` if none is currently being used.

The `get_hadjustment`() method returns the value of the "hadjustment" property that contains the current horizontal `gtk.Adjustment` object or `None` (if no horizontal adjustment is being used).

### gtk.TreeView.set_hadjustment

        def set_hadjustment(adjustment)

`adjustment` : | the `gtk.Adjustment` to set

The `set_hadjustment`() method sets the "hadjustment" property to the value of `adjustment` that must be a `gtk.Adjustment` object.

### gtk.TreeView.get_vadjustment

        def get_vadjustment()

Returns : | a `gtk.Adjustment` object, or `None` if none is currently being used.

The `get_vadjustment`() method returns the value of the "vadjustment" property that contains the horizontal `gtk.Adjustment` or None if there is no vertical adjustment.

### gtk.TreeView.set_vadjustment

        def set_vadjustment(adjustment)

`adjustment` : | the `gtk.Adjustment` to set

The `set_vadjustment`() method sets the "vadjustment" property to the value of `adjustment`. The new `gtk.Adjustment` replaces the current vertical adjustment.

### gtk.TreeView.get_headers_visible

        def get_headers_visible()

Returns : | `True` if the headers are visible.

The `get_headers_visible`() method returns the value of the "headers-visible" property. If "headers-visible" is `True` the headers on the treeview are visible.

### gtk.TreeView.set_headers_visible

        def set_headers_visible(headers_visible)

`headers_visible` : | if `True` the headers are visible

The `set_headers_visible`() method sets the "headers-visible" property to the value of `headers_visible`. If `headers_visible` is `True` the headers will be displayed.

### gtk.TreeView.columns_autosize

        def columns_autosize()

The `columns_autosize`() method resizes all columns to their optimal width. Only works after the treeview has been realized.

### gtk.TreeView.set_headers_clickable

        def set_headers_clickable(active)

`active` : | if `True` the headers are clickable

The `set_headers_clickable`() method sets the "headers-clickable" property to the value of `active`. If `active` is `True` the column title buttons can be clicked.

### gtk.TreeView.set_rules_hint

        def set_rules_hint(setting)

`setting` : | if `True` the tree requires reading across rows

The `set_rules_hint`() method sets the "rules-hint" property to the value of `setting`. If `setting` is `True` it indicates that the user interface for your application requires users to read across tree rows and associate cells with one another. By default, the tree will be rendered 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 method 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).

### gtk.TreeView.get_rules_hint

        def get_rules_hint()

Returns : | `True` if rules are useful for the user of this tree

The `get_rules_hint`() returns the value of the "rules-hint" property. See the `set_rules_hint`() method for more information on the use of "rules-hint".

### gtk.TreeView.append_column

        def append_column(column)

`column` : | the `gtk.TreeViewColumn` to add.
Returns : | the number of columns in `tree_view` after appending.

The `append_column`() method appends the specified `column` to the list of columns and returns the new number of columns in the treeview.

### gtk.TreeView.remove_column

        def remove_column(column)

`column` : | the `gtk.TreeViewColumn` to remove.
Returns : | the number of columns in the treeview after the column removal.

The `remove_column`() method removes the specified `column` from the treeview.

### gtk.TreeView.insert_column

        def insert_column(column, position)

`column` : | the `gtk.TreeViewColumn` to be inserted.
`position` : | the position to insert `column`.
Returns : | the number of columns in the treeview after the insertion.

The `insert_column`() method inserts the specified `column` into the treeview at the location specified by `position`. If `position` is -1, then the column is inserted at the end.

### gtk.TreeView.insert_column_with_attributes

        def insert_column_with_attributes(position, title, cell, ...)

`position` : | the position to insert the new column in.
`title` : | the title to set the header to.
`cell` : | the `gtk.CellRenderer`.
`...` : | optional keyword-value arguments
Returns : | the `gtk.TreeViewColumn` that was inserted.

The `insert_column_with_attributes`() method creates a new `gtk.TreeViewColumn` and inserts it into the treeview at the location specified by `position` with the column title specified by `title` and using the `gtk.CellRenderer` specified by `cell`. If `position` is -1, then the newly created column is inserted at the end. The column is initialized with the optional attributes passed as keyword-value pairs (e.g. text=0, foreground=2). See the `gtk.TreeViewColumn.add_attribute`() method for more information.

### gtk.TreeView.insert_column_with_data_func

        def insert_column_with_data_func(position, title, cell, func, data=None)

`position` : | the position to insert, -1 for append
`title` : | the column title
`cell` : | a cell renderer for the column
`func` : | the function or method to set attributes of the cell renderer
`data` : | the data to pass with `func`
Returns : | the number of columns in the treeview after the insertion

The `insert_column_with_data_func`() method is a convenience function that inserts a new column into the treeview at the location specified by `position` with the specified `title` and the cell renderer specified by `cell` and using the function or method specified by `func` to set cell renderer attributes (normally using data from the model). The signature of func is:

        def celldatafunction(column, cell, model, iter, user_data)

        def celldatamethod(self, column, cell, model, iter, user_data)

where `column` is the `gtk.TreeViewColumn` in the treeview, `cell` is the `gtk.CellRenderer` for `column`, `model` is the `gtk.TreeModel` for the treeview and `iter` is the `gtk.TreeIter` pointing at the row. See the `gtk.TreeViewColumn.set_cell_data_func`() and `gtk.TreeViewColumn.pack_start`() methods for more detail.

### gtk.TreeView.get_column

        def get_column(n)

`n` : | the position of the column, counting from 0.
Returns : | the `gtk.TreeViewColumn`, or `None` if the position is outside the range of columns.

The `get_column`() method returns the `gtk.TreeViewColumn` at the specified `position` in the treeview.

### gtk.TreeView.get_columns

        def get_columns()

Returns : | a list of `gtk.TreeViewColumn` s

The `get_columns`() method returns a list of all the `gtk.TreeViewColumn` objects currently in the treeview.

### gtk.TreeView.move_column_after

        def move_column_after(column, base_column)

`column` : | the `gtk.TreeViewColumn` to be moved.
`base_column` : | the `gtk.TreeViewColumn` `column` is to be after, or `None`.

The `move_column_after`() method moves the `gtk.TreeViewColumn` specified by `column` to be after the treeview column specified by `base_column`. If `base_column` is `None`, then `column` is placed in the first position.

### gtk.TreeView.set_expander_column

        def set_expander_column(column)

`column` : | the column to draw the expander arrow at or`None`.

The `set_expander_column`() method sets the "expander-column" property to the value of `column` which must be a `gtk.TreeViewColumn` in the treeview. If `column` is `None`, then the expander arrow is always at the first visible column.

### gtk.TreeView.get_expander_column

        def get_expander_column()

Returns : | the expander column.

The `get_expander_column`() method returns the value of the "expander-column" property that contains the current expander column i.e. the column that has the expander arrow drawn next to it.

### gtk.TreeView.set_column_drag_function

        def set_column_drag_function(func, user_data)

`func` : | A function to determine which columns are reorderable, or `None`.
`user_data` : | User data to be passed to `func`, or `None`

### Note

This method is available in PyGTK 2.4 and above.

The `set_column_drag_function`() method sets the user function specified by `func` for determining where a column may be dropped when dragged. The user 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 signature of `func` is:

      def func(tree_view, column, prev_column, next_column, data)

where `tree_view` is the `gtk.TreeView`, `column` is the `gtk.TreeViewColumn` being dragged, prev_column and next_column are the two `gtk.TreeViewColumn` objects bracketing the drop spot, and `data` is `user_data`. If `prev_column` or `next_column` is `None`, then the drop is at an edge. If `func` is `None`, the user drag function is removed and the `gtk.TreeView` reverts to the default behavior of allowing any reorderable column to be dropped anywhere.

### gtk.TreeView.scroll_to_point

        def scroll_to_point(tree_x, tree_y)

`tree_x` : | the X coordinate of new top-left pixel of visible area, or -1
`tree_y` : | the Y coordinate of new top-left pixel of visible area, or -1

The `scroll_to_point`() method scrolls the treeview so that the top-left corner of the visible area is at the location specified by `tree_x` and `tree_y`, where `tree_x` and `tree_y` are specified in tree window coordinates. The treeview must be realized before this method is called. If it isn't, you should use the `scroll_to_cell`() method instead. If either `tree_x` or `tree_y` are -1, there is no scrolling in that direction.

### gtk.TreeView.scroll_to_cell

        def scroll_to_cell(path, column=None, use_align=False, row_align=0.0, col_align=0.0)

`path` : | the path of the row to move to
`column` : | the `gtk.TreeViewColumn` to move horizontally to, or `None`.
`use_align` : | if `True` use the alignment arguments
`row_align` : | the vertical alignment of the row specified by `path`.
`col_align` : | the horizontal alignment of the column specified by `column`.

The `scroll_to_cell`() method scrolls the treeview display to the position specified by `column` and `path`. If `column` is `None`, no horizontal scrolling occurs. The alignment parameters specified by `row_align` and `col_align` determines where `column` is placed within the treeview. The values of `col_align` and `row_align` range from 0.0 to 1.0. The alignment values specify the fraction of display space that is to the left of or above the cell. If `use_align` is `False`, 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 it's current position. If the cell is currently visible on the screen, nothing is done. This method only works if the model is set, and `path` is a valid row in the model.

### gtk.TreeView.row_activated

        def row_activated(path, column)

`path` : | the tree path of the row of the cell to be activated.
`column` : | the `gtk.TreeViewColumn` of the cell to be activated.

The `row_activated`() method activates the cell determined by `path` and `column`.

### gtk.TreeView.expand_all

        def expand_all()

The `expand_all`() method recursively expands all nodes in the treeview.

### gtk.TreeView.collapse_all

        def collapse_all()

The `collapse_all`() method recursively collapses all visible, expanded nodes in the treeview.

### gtk.TreeView.expand_to_path

        def expand_to_path(path)

`path` : | a path to a row.

### Note

This method is available in PyGTK 2.2 and above.

The `expand_to_row`() method expands the row with the tree path specified by `path`. This will also expand all parent rows of `path` as necessary.

### gtk.TreeView.expand_row

        def expand_row(path, open_all)

`path` : | the path to a row
`open_all` : | if `True` recursively expand, otherwise just expand immediate children

The `expand_row`() method opens the row specified by `path` so its children are visible. If `open_all` is `True` all rows are expanded, otherwise only the immediate children of `path` are expanded.

### gtk.TreeView.collapse_row

        def collapse_row(path)

`path` : | the path to a row

The `collapse_row`() method collapses the row specified by `path` (hides its child rows, if they exist).

### gtk.TreeView.map_expanded_rows

        def map_expanded_rows(func, data)

`func` : | A function to be called
`data` : | User data to be passed to the function.

### Note

This method is available in PyGTK 2.2 and above.

The `map_expanded_rows`() method calls the function specified by `func` on all expanded rows passing `data` as an argument.

### gtk.TreeView.row_expanded

        def row_expanded(path)

`path` : | the path to a row to test the expansion state.
Returns : | `True` if `path` is expanded.

The `row_expanded`() method returns `True` if the node pointed to by `path` is expanded.

### gtk.TreeView.set_reorderable

        def set_reorderable(reorderable)

`reorderable` : | if `True`, the tree can be reordered.

The `set_reorderable`() method sets the "reorderable" property to the value of `reorderable`. This method is a convenience method to allow you to reorder models that support the `gtk.TreeDragSource` and the `gtk.TreeDragDest` interfaces. Both `gtk.TreeStore` and `gtk.ListStore` support these. If `reorderable` is `True`, then the user can reorder the model by dragging and dropping rows. The application can listen to these changes by connecting to the model's signals.

### Note

This function does not give you any degree of control over the order -- any reordering is allowed. If more control is needed, you should probably handle drag and drop manually.

### gtk.TreeView.get_reorderable

        def get_reorderable()

Returns : | `True` if the tree can be reordered.

The `get_reorderable`() method returns the value of the "reorderable" property that determines if the user can reorder the tree via drag-and-drop. See the `set_reorderable`() method for more information.

### gtk.TreeView.set_cursor

        def set_cursor(path, focus_column=None, start_editing=False)

`path` : | a tree path
`focus_column` : | a `gtk.TreeViewColumn`, or `None`
`start_editing` : | `if True` the specified cell should start being edited.

The `set_cursor`() method sets the current keyboard focus to be at the row specified by `path`, and selects it. This is useful when you want to focus the user's attention on a particular row. If `column` is not `None`, then focus is given to the specified column. Additionally, if `column` is specified, and `start_editing` is `True`, then editing should be started in the specified cell. This method is often followed by the `gtk.Widget.grab_focus`() method to give keyboard focus to the treeview. Please note that editing can only happen when the widget is realized.

### gtk.TreeView.set_cursor_on_cell

        def set_cursor_on_cell(path, focus_column=None, focus_cell=None, start_editing=False)

`path` : | a tree path
`focus_column` : | a `gtk.TreeViewColumn`, or `None`
`focus_cell` : | a `gtk.CellRenderer`, or `None`
`start_editing` : | `True` if the specified cell should start being edited.

### Note

This method is available in PyGTK 2.2 and above.

The `set_cursor_on_cell`() method sets the current keyboard focus to be at the node specified by `path`, and selects it. This is useful when you want to focus the user's attention on a particular row. If `focus_column` is specified, focus is given to that column. If `focus_column` and `focus_cell` are specified, 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`, editing should be started in the specified cell. This method is often followed by the `gtk.Widget.grab_focus`() method in order to give keyboard focus to the widget. Please note that editing can only happen when the widget is realized.

### gtk.TreeView.get_cursor

        def get_cursor()

Returns : | a tuple containing the current cursor path and focus column.

The `get_cursor`() method returns a tuple containing the current path and focus column. If the cursor isn't currently set, the current path will be `None`. If no column currently has focus, the current focus column will be `None`.

### gtk.TreeView.get_bin_window

        def get_bin_window()

Returns : | a `gtk.gdk.Window`, or `None`

The `get_bin_window`() method returns the window that the treeview renders to or `None` if the treeview is not realized yet. This is used primarily to compare to the `event.window` attribute to confirm that the event on the treeview is on the right window.

### gtk.TreeView.get_path_at_pos

        def get_path_at_pos(x, y)

`x` : | The x position to be identified.
`y` : | The y position to be identified.
Returns : | a tuple containing: a tree path; a `gtk.TreeViewColumn` object; the X coordinate relative to the cell; and, the Y coordinate relative to the cell. If there is no path at the position `None` is returned.

The `get_path_at_pos`() method returns a tuple containing:

- the path at the specified point (`x`, `y`), relative to widget coordinates
- the `gtk.TreeViewColumn` at that point
- the X coordinate relative to the cell background
- the Y coordinate relative to the cell background

`x` and `y` are relative to the coordinates of an event on the treeview only when `event.window==treeview.get_bin_window()`. It is primarily used for popup menus. This method is only meaningful if the treeview is realized. This method returns `None` if there is no path at the position.

### gtk.TreeView.get_cell_area

        def get_cell_area(path, column)

`path` : | a tree path for the row
`column` : | a `gtk.TreeViewColumn` for the column
Returns : | rectangle

The `get_cell_area`() method returns the bounding `gtk.gdk.Rectangle` in tree window coordinates for the cell at the row specified by `path` and the column specified by `column`. If `path` points to a path not currently displayed, the `y` and `height` attributes of the rectangle will be 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 the `gtk.CellRenderer.render`() method. This method is only valid if the treeview is realized.

### gtk.TreeView.get_background_area

        def get_background_area(path, column)

`path` : | a tree path for the row,
`column` : | a `gtk.TreeViewColumn` for the column
Returns : | a rectangle

The `get_background_area`() method returns the bounding `gtk.gdk.Rectangle` in tree window coordinates for the cell at the row specified by `path` and the column specified by `column`. If `path` points to a node not found in the tree, the `y` and `height` attributes of the rectangle will be 0. The returned rectangle is equivalent to the `background_area` passed to the `gtk.CellRenderer.render`(). These background areas tile to cover the entire tree window (except for the area used for header buttons). Contrast with the `cell_area`, returned by the `get_cell_area`() method, that returns only the cell itself, excluding the surrounding borders and the tree expander area.

### gtk.TreeView.get_visible_rect

        def get_visible_rect()

Returns : | a rectangle

The `get_visible_rect`() method returns the bounding `gtk.gdk.Rectangle` for the currently visible region of the treeview widget, in tree coordinates. Convert to widget coordinates with the `tree_to_widget_coords`(). Tree coordinates start at 0,0 for row 0 of the tree, and cover the entire scrollable area of the tree.

### gtk.TreeView.widget_to_tree_coords

        def widget_to_tree_coords(wx, wy)

`wx` : | the widget X coordinate
`wy` : | the widget Y coordinate
Returns : | a tuple containing the tree X and Y coordinates

The `widget_to_tree_coords`() method returns a tuple containing the tree X and Y coordinates for the widget coordinates specified by `wx` and `wy`. The tree coordinates cover the full scrollable area of the tree.

### gtk.TreeView.tree_to_widget_coords

        def tree_to_widget_coords(tx, ty)

`tx` : | tree X coordinate
`ty` : | tree Y coordinate
Returns : | a tuple containing the widget X and Y coordinates

The `tree_to_widget_coords`() method returns a tuple containing the widget coordinates for the tree coordinates specified by `tx` and `ty`.

### gtk.TreeView.enable_model_drag_source

        def enable_model_drag_source(start_button_mask, targets, actions)

`start_button_mask` : | the bitmask of buttons that can start the drag
`targets` : | a sequence of tuples containing target data
`actions` : | the possible actions for a drag

The `enable_model_drag_source`() method sets the treeview to start a drag operation when the user click and drags on a row. The value of `start_button_mask` is a combination of theGDK Modifier Constants.

`targets` is a sequence (list or tuple) of tuples that contain information about the targets. The target data contains a string representing the drag type, target flags (a combination of the GTK Target Flags Constants) and an application assigned integer ID used for identification purposes.

The value of `actions` is one of the GDK Drag Action Constants.

### gtk.TreeView.enable_model_drag_dest

        def enable_model_drag_dest(targets, actions)

`targets` : | a sequence of tuples containing target data
`actions` : | the possible actions for a drag

The `enable_model_drag_dest`() method sets the treeview to receive a drag drop.

`targets` is a sequence (list or tuple) of tuples that contain information about the targets. The target data contains a string representing the drag type, target flags (a combination of `gtk.TARGET_SAME_APP` and `gtk.TARGET_SAME_WIDGET` or neither) and an application assigned integer ID used for identification purposes.

The value of `actions` is one of the GDK Drag Action Constants.

### gtk.TreeView.unset_rows_drag_source

        def unset_rows_drag_source()

The `unset_rows_drag_source`() method unsets the drag source information.

### gtk.TreeView.unset_rows_drag_dest

        def unset_rows_drag_dest()

The `unset_rows_drag_dest`() method unsets the drag destination information.

### gtk.TreeView.set_drag_dest_row

        def set_drag_dest_row(path, pos)

`path` : | a tree path of the row to highlight, or `None`.
`pos` : | a drop position

The `set_drag_dest_row`() method sets the treeview drag destination row to the value specified by `path` with the drop position specified by `pos`. The value of `pos` must be one of: `gtk.TREE_VIEW_DROP_BEFORE`, `gtk.TREE_VIEW_DROP_AFTER`, `gtk.TREE_VIEW_DROP_INTO_OR_BEFORE` or `gtk.TREE_VIEW_DROP_INTO_OR_AFTER`.

In PyGTK 2.10 and above, `path` may be `None`.

### gtk.TreeView.get_drag_dest_row

        def get_drag_dest_row()

Returns : | a 2-tuple containing the tree path and the drop position relative to the tree path or `None`

The `get_drag_dest_row`() method returns a 2-tuple containing the path of the drag destination row and a drop position relative to the destination row. The drop position is one of: `gtk.TREE_VIEW_DROP_BEFORE`, `gtk.TREE_VIEW_DROP_AFTER`, `gtk.TREE_VIEW_DROP_INTO_OR_BEFORE` or `gtk.TREE_VIEW_DROP_INTO_OR_AFTER`. This method returns `None` if no drag destination row is set.

### gtk.TreeView.get_dest_row_at_pos

        def get_dest_row_at_pos(x, y)

`x` : | the x coordinate of the position
`y` : | the y coordinate of the position
Returns : | a 2-tuple containing the path of the row and the drop position at the position specified by `x` and `y` or `None`

The `get_dest_row_at_pos`() method returns a 2-tuple containing the path of the row and the drop position relative to the row of the position specified by `x` and `y`. The drop position is one of: `gtk.TREE_VIEW_DROP_BEFORE`, `gtk.TREE_VIEW_DROP_AFTER`, `gtk.TREE_VIEW_DROP_INTO_OR_BEFORE` or `gtk.TREE_VIEW_DROP_INTO_OR_AFTER`.

### gtk.TreeView.create_row_drag_icon

        def create_row_drag_icon(path)

`path` : | a tree path
Returns : | a new pixmap of the drag icon.

The `create_row_drag_icon`() method creates a `gtk.gdk.Pixmap` representation of the row specified by `path`. This image is used for a drag icon.

### gtk.TreeView.set_enable_search

        def set_enable_search(enable_search)

`enable_search` : | if `True`, the user can search interactively

The `set_enable_search`() method sets the "enable-search" property to the value of `enable_search`. If `enable_search` is `True` the user can type in text to search through the tree interactively.

### gtk.TreeView.get_enable_search

        def get_enable_search()

Returns : | `True` if the user can search interactively

The `get_enable_search`() method returns the value of the "enable-search" property. If "enable-search" is `True` the tree allows interactive searching.

### gtk.TreeView.get_search_column

        def get_search_column()

Returns : | the column the interactive search code searches.

The `get_search_column`() method returns the value of the "search-column" property that is the column searched by the interactive search code.

### gtk.TreeView.set_search_column

        def set_search_column(column)

`column` : | the column to search

The `set_search_column`() method sets the "search-column" property to the value of `column`. The value of `column` is the column where the interactive search code should search. Additionally, this method turns on interactive searching (see the `set_enable_search`() method).

### gtk.TreeView.set_search_equal_func

        def set_search_equal_func(func=None, user_data=None)

`func` : | the compare function to use during the search or `None`
`user_data` : | user data to pass to `func`, or `None`

### Note

This method is available in PyGTK 2.4 and above.

The `set_search_equal_func`() method sets the compare function for the interactive search capabilities to the function specified by `func`. If `user_data` is specified and not `None`, it is passed to `func`. If `func` is `None`, the default `gtk.TreeView` search equal function will be used. The signature of `func` is:

      def func(model, column, key, iter, data)

where `model` is the `gtk.TreeModel` of the `gtk.TreeView`, `column` is the number of the column being searched (see the `set_search_column`() method for more information), `key` is the string being searched for, `iter` is a `gtk.TreeIter` pointing to the current candidate row and `data` is the context data `user_data`. `func` should return `False` to indicate that the row matches the search criteria.

### gtk.TreeView.get_fixed_height_mode

        def get_fixed_height_mode()

Returns : | `True` if fixed height mode is enabled.

### Note

This method is available in PyGTK 2.6 and above.

The `get_fixed_height_mode`() method returns the value of the "fixed-height-mode" property. If the "fixed-height-mode" property is `True`, all rows are assumed to be the same height.

### gtk.TreeView.set_fixed_height_mode

        def set_fixed_height_mode(enable)

`enable` : | if `True` enable fixed height mode.

### Note

This method is available in PyGTK 2.6 and above.

The `set_fixed_height_mode`() method sets the "fixed-height-mode" property to the value of `enable`. If `enable` is `True` all rows are assumed to have the same height which speeds up `gtk.TreeView` displays. Only enable this option if all rows are the same height and all columns are of type `gtk.TREE_VIEW_COLUMN_FIXED` (see the GTK TreeViewColumn Sizing Constants).

### gtk.TreeView.get_hover_selection

        def get_hover_selection()

Returns : | `True` if hover selection mode is enabled.

### Note

This method is available in PyGTK 2.6 and above.

The `get_hover_selection`() method returns the value of the "hover-selection" property. If the "hover-selection" property is `True` the selected row follows the pointer. See the `set_hover_selection`() method for more detail.

### gtk.TreeView.set_hover_selection

        def set_hover_selection(hover)

`hover` : | if `True` enable hover selection mode.

### Note

This method is available in PyGTK 2.6 and above.

The ``() method sets the "hover-selection" property to the value of `hover`. If `hover` is `True` the hover selection mode is enables and the selected row follows the pointer. Currently, this works only for the selection modes `gtk.SELECTION_SINGLE` and `gtk.SELECTION_BROWSE` (see the GTK Selection Mode Constants).

### gtk.TreeView.get_hover_expand

        def get_hover_expand()

Returns : | `True` if hover expand mode is enabled

### Note

This method is available in PyGTK 2.6 and above.

The `get_hover_expand`() method returns the value of the "hover-expand" property. If the "hover-expand" property is `True` rows expand or collapse if the pointer moves over them.

### gtk.TreeView.set_hover_expand

        def set_hover_expand(expand)

`expand` : | if `True` enable hover expand mode.

### Note

This method is available in PyGTK 2.6 and above.

The `set_hover_expand`() method sets the "hover-expand" property to the value of `expand`. If `expand` is `True`, rows expand or collapse if the pointer moves over them.

### gtk.TreeView.set_row_separator_func

        def set_row_separator_func(func=None, user_data=None)

`func` : | the row separator function or `None`
`user_data` : | user data to pass to `func`, or `None`

### Note

This method is available in PyGTK 2.6 and above.

The `set_row_separator_func`() method sets the row separator function to the function specified by `func`. The row separator function is used to determine if a row should be displayed as a separator. If `user_data` is specified and not `None`, it is passed to `func`. If `func` is `None`, no separators will be drawn. The signature of `func` is:

      def func(model, iter, data)

where `model` is the `gtk.TreeModel` of the `gtk.TreeView`, `iter` is a `gtk.TreeIter` pointing to the current candidate row and `data` is the context data `user_data`. `func` should return `True` to indicate that the row is a separator.

A common way to implement this is to have a boolean column in `model`, whose values `func` returns.

### gtk.TreeView.get_visible_range

        def get_visible_range()

Returns : | a 2-tuple containing the start and end paths of the visible region or `None`.

### Note

This method is available in PyGTK 2.10 and above.

The `get_visible_range`() method returns a 2-tuple containing the start and end paths for the visible region in the treeview. If no valid paths are available this method returns `None`.

### gtk.TreeView.get_headers_clickable

        def get_headers_clickable()

Returns : | `True` if all header columns are clickable

### Note

This method is available in PyGTK 2.10 and above.

Returns `True` if all header columns are clickable.

### gtk.TreeView.get_search_entry

        def get_search_entry()

Returns : | the entry currently in use as the search entry.

### Note

This method is available in PyGTK 2.10 and above.

Returns the `gtk.Entry` which is currently in use as the interactive search entry for the treeview. In case the built-in entry is being used, `None` will be returned.

### gtk.TreeView.set_search_entry

        def set_search_entry(entry=None)

`entry` : | the entry the interactive search code of the treeview should use or `None`

### Note

This method is available in PyGTK 2.10 and above.

Sets the entry which the interactive search code will use for this treeview. This is useful when you want to provide a search entry in our interface at all time at a fixed position. Passing `None` for `entry` will make the interactive search code use the built-in popup entry again.

### gtk.TreeView.set_search_position_func

        def set_search_position_func(func, data=None)

`func` : | the function to use to position the search dialog, or `None` to use the default search position function
`data` : | user data to pass to `func`, or `None`

### Note

This method is available in PyGTK 2.10 and above.

Sets the function to use when positioning the search dialog. The signature of `func` is:

      def func(treeview, search_dialog, user_data):

where `search_dialog` is the dialog to be positioned and `user_data` is `data`.

### gtk.TreeView.set_rubber_banding

        def set_rubber_banding(enable)

`enable` : | if `True` enable rubber banding

### Note

This method is available in PyGTK 2.10 and above.

Enables or disables rubber banding. If the selection mode is `gtk.SELECTION_MULTIPLE`, rubber banding will allow the user to select multiple rows by dragging the mouse.

### gtk.TreeView.get_rubber_banding

        def get_rubber_banding()

Returns : | `True` if rubber banding is enabled.

### Note

This method is available in PyGTK 2.10 and above.

Returns whether rubber banding is enabled. If the selection mode is `gtk.SELECTION_MULTIPLE`, rubber banding will allow the user to select multiple rows by dragging the mouse.

### gtk.TreeView.get_grid_lines

        def get_grid_lines()

Returns : | one of the GTK TreeView Grid Lines Constants indicating which grid lines are enabled.

### Note

This method is available in PyGTK 2.10 and above.

Returns which grid lines are enabled.

### gtk.TreeView.set_grid_lines

        def set_grid_lines(grid_lines)

`grid_lines` : | one of the GTK TreeView Grid Lines Constants indicating which grid lines to enable.

### Note

This method is available in PyGTK 2.10 and above.

Sets which grid lines to draw.

### gtk.TreeView.get_enable_tree_lines

        def get_enable_tree_lines()

Returns : | `True` if tree lines are drawn.

### Note

This method is available in PyGTK 2.10 and above.

Returns `True` if tree lines are drawn.

### gtk.TreeView.set_enable_tree_lines

        def set_enable_tree_lines(enabled)

`enabled` : | if `True` enable tree line drawing.

### Note

This method is available in PyGTK 2.10 and above.

Sets whether to draw lines interconnecting the expanders. This does not have any visible effects for lists.

## Signals

### The "columns-changed" gtk.TreeView Signal

        def callback(treeview, user_param1, ...)

`treeview` : | the treeview that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "columns-changed" signal is emitted when a column has been added to, removed from or moved in `treeview`.

### The "cursor-changed" gtk.TreeView Signal

        def callback(treeview, user_param1, ...)

`treeview` : | the treeview that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "cursor-changed" signal is emitted when the cursor moves or is set.

### The "expand-collapse-cursor-row" gtk.TreeView Signal

        def callback(treeview, logical, expand, open_all, user_param1, ...)

`treeview` : | the treeview that received the signal
`logical` : | if `True`
`expand` : | if `True` the row should be expanded
`open_all` : | if `True` recursively expand all children
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if the signal was handled.

The "expand-collapse-cursor-row" signal is emitted when the row at the cursor needs to be expanded or collapsed.

### The "move-cursor" gtk.TreeView Signal

        def callback(treeview, step, count, user_param1, ...)

`treeview` : | the treeview that received the signal
`step` : | the movement step size
`count` : | the number of steps to take
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if the signal was handled.

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.

### The "row-activated" gtk.TreeView Signal

        def callback(treeview, path, view_column, user_param1, ...)

`treeview` : | the treeview that received the signal
`path` : | the path of the activated row
`view_column` : | the column in the activated row
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "row-activated" signal is emitted when the `row_activated`() method is called or the user double clicks a `treeview` row. "row-activated" is also emitted when a non-editable row is selected and one of the keys: Space, Shift+Space, Return or Enter is pressed.

### The "row-collapsed" gtk.TreeView Signal

        def callback(treeview, iter, path, user_param1, ...)

`treeview` : | the treeview that received the signal
`iter` : | a `gtk.TreeIter` pointing to the row that collapsed
`path` : | the path of the row that collapsed
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "row-collapsed" signal is emitted when a row is collapsed by user of programmatic action.

### The "row-expanded" gtk.TreeView Signal

        def callback(treeview, iter, path, user_param1, ...)

`treeview` : | the treeview that received the signal
`iter` : | a `gtk.TreeIter` pointing to the row that expanded
`path` : | the path of the row that expanded
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "row-expanded" signal is emitted when a row is expanded via user or programmatic action.

### The "select-all" gtk.TreeView Signal

        def callback(treeview, user_param1, ...)

`treeview` : | the treeview that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if the signal was handled.

The "select-all" signal is emitted when the user presses Control+a or Control+/.

### The "select-cursor-parent" gtk.TreeView Signal

        def callback(treeview, user_param1, ...)

`treeview` : | the treeview that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if the signal was handled.

The "select-cursor-parent" signal is emitted when the user presses Backspace while a row has the cursor.

### The "select-cursor-row" gtk.TreeView Signal

        def callback(treeview, start_editing, user_param1, ...)

`treeview` : | the treeview that received the signal
`start_editing` : | if `True` the cell editing is started
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if the signal was handled.

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.

### The "set-scroll-adjustments" gtk.TreeView Signal

        def callback(treeview, hadjustment, vadjustment, user_param1, ...)

`treeview` : | the treeview that received the signal
`hadjustment` : | a horizontal `gtk.Adjustment`
`vadjustment` : | a vertical `gtk.Adjustment`
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if the signal was handled.

The "set-scroll-adjustments" signal is emitted when new horizontal or vertical adjustments are set on the `treeview`.

### The "start-interactive-search" gtk.TreeView Signal

        def callback(treeview, user_param1, ...)

`treeview` : | the treeview that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if the signal was handled.

The "start-interactive-search" signal is emitted when the user presses Control+f.

### The "test-collapse-row" gtk.TreeView Signal

        def callback(treeview, iter, path, user_param1, ...)

`treeview` : | the treeview that received the signal
`iter` : | the `gtk.TreeIter` pointing at the row to test.
`path` : | the path of the row to be tested
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if the row should be collapsed.

The "test-collapse-row" signal is emitted when the row pointed to by `iter` and `path` is to be collapsed.

### The "test-expand-row" gtk.TreeView Signal

        def callback(treeview, iter, path, user_param1, ...)

`treeview` : | the treeview that received the signal
`iter` : | the `gtk.TreeIter` pointing at the row to test.
`path` : | the path of the row to test
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if the row should be expanded.

The "test-expand-row" signal is emitted when the row pointed to by `iter` and `path` is to be expanded.

### The "toggle-cursor-row" gtk.TreeView Signal

        def callback(treeview, user_param1, ...)

`treeview` : | the treeview that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if the signal was handled.

The "toggle-cursor-row" signal is emitted when the user presses Control+Space.

### The "unselect-all" gtk.TreeView Signal

        def callback(treeview, user_param1, ...)

`treeview` : | the treeview that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if the signal was handled.

The "unselect-all" signal is emitted when the user presses Shift+Control+a or Shift+Control+/.

Prev | Up | Next
gtk.TreeStore | Home | gtk.TreeViewColumn