gtk.TreeSelection
Prev | The gtk Class Reference | Next

## gtk.TreeSelection

gtk.TreeSelection — the selection object for `gtk.TreeView`

## Synopsis

    class gtk.TreeSelection(gtk.Object):
        def set_mode(type)
        def get_mode()
        def set_select_function(func, data=None, full=False)
        def get_tree_view()
        def get_selected()
        def get_selected_rows()
        def count_selected_rows()
        def selected_foreach(func, data=None)
        def select_path(path)
        def unselect_path(path)
        def select_iter(iter)
        def unselect_iter(iter)
        def path_is_selected(path)
        def iter_is_selected(iter)
        def select_all()
        def unselect_all()
        def select_range(start_path, end_path)
        def unselect_range(start_path, end_path)

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.TreeSelection

## gtk.TreeSelection Signal Prototypes

gobject.GObject Signal Prototypes

"changed" | `def callback(`treeselection`, `user_param1`, `...`)`

## Description

The `gtk.TreeSelection` object is a helper object to manage the selection for a `gtk.TreeView` widget. The `gtk.TreeSelection` object is automatically created when a new `gtk.TreeView` widget is created, and cannot exist independent of this widget. The primary reason the `gtk.TreeSelection` object exists is for cleanliness of code and API. That is, there is no conceptual reason all these functions could not be methods on the `gtk.TreeView` widget instead of a separate function. The `gtk.TreeSelection` object is retrieved from a `gtk.TreeView` by calling the `gtk.TreeView.get_selection`() method. It can be manipulated to check the selection status of the tree, as well as select and deselect individual rows. Selection is done completely on the view side. As a result, multiple views of the same model can have completely different selections. Additionally, you cannot change the selection of a row on the model that is not currently displayed by the view without expanding its parents first.

One of the important things to remember when monitoring the selection of a view is that the "changed" signal is mostly a hint. That is, it may only emit one signal when a range of rows is selected. Additionally, it may on occasion emit a "changed" signal when nothing has happened (mostly as a result of programmers calling the `select_path`() or `select_iter`() methods on an already selected row).

## Methods

### gtk.TreeSelection.set_mode

        def set_mode(type)

`type` : | the selection mode

The `set_mode`() method sets the selection mode of the treeselection to the mode specified by `type`. The value of `type` must be one of: `gtk.SELECTION_NONE`, `gtk.SELECTION_SINGLE`, `gtk.SELECTION_BROWSE` or `gtk.SELECTION_MULTIPLE`. See the GTK Selection Mode Constants description for more detail.

If the previous type was `gtk.SELECTION_MULTIPLE`, then the anchor is kept selected, if it was previously selected.

### gtk.TreeSelection.get_mode

        def get_mode()

Returns : | the current selection mode

The `get_mode`() method returns the selection mode for treeselection. See the `set_mode`() method for more information.

### gtk.TreeSelection.set_select_function

        def set_select_function(func, data=None, full=False)

`func` : | the selection function.
`data` : | the selection function's data.
`full` : | if `True` `func` will be passed a full set of args

The `set_selection_function`() method sets the selection function to `func` (a function or method). If the selection function is set, it is called before any node is selected or unselected, giving some control over which nodes are selected. The selection function should return `True` if the state of the node may be toggled, and `False` if the state of the node should be left unchanged. The signature of the selection function callback is:

          def selectfunction(info)

          def selectmethod(self, info)

where `info` is a tuple containing a path or a path and `data` if `data` was passed to the `set_select_function`() method.

In PyGTK 2.10 and above if the additional optional parameter `full` is `True` the signature of `func` should be:

        def selectfunction(selection, model, path, path_currently_selected, user_data)

        def selectmethod(self, selection, model, path, is_selected, user_data)

where `selection` is the `gtk.TreeSelection`, `model` is the `gtk.TreeModel` used by the `gtk.TreeView` associated with selection, `path` is the path of the selected row, `is_selected` is `True` if the row is currently selected and `user_data` is `data` if any (may not be present if `data` was `None`). If `func` is a method then `self` is the object that the method is called upon.

### gtk.TreeSelection.get_tree_view

        def get_tree_view()

Returns : | a `gtk.TreeView`

The `get_tree_iter`() method returns the tree view associated with the treeselection.

### gtk.TreeSelection.get_selected

        def get_selected()

Returns : | a 2-tuple containing a reference to the `gtk.TreeModel` and a `gtk.TreeIter` pointing to the currently selected node.

The `get_selected`() method returns a 2-tuple containing the treemodel and a treeiter pointing to the selected node in the treemodel if the treeselection is set to `gtk.SELECTION_SINGLE` or `gtk.SELECTION_BROWSE`. The returned `gtk.TreeIter` will be `None` if there is no row selected. This method will not work if you use `selection` is `gtk.SELECTION_MULTIPLE`.

### gtk.TreeSelection.get_selected_rows

        def get_selected_rows()

Returns : | a 2-tuple containing the tree model and a list of the tree paths of all selected rows.

### Note

This method is available in PyGTK 2.2 and above.

The `get_selected_rows`() method returns a 2-tuple containing a `gtk.TreeModel` and a list of the tree paths of all selected rows. Additionally, if you are planning on modifying the tree model after calling this method, you may want to convert the returned list into a list of `gtk.TreeRowReference` objects. To do this, you can use the gtk.TreeRowReference() constructor.

### gtk.TreeSelection.count_selected_rows

        def count_selected_rows()

Returns : | The number of rows selected.

### Note

This method is available in PyGTK 2.2 and above.

The `count_selected_rows`() method returns the number of rows that have been selected.

### gtk.TreeSelection.selected_foreach

        def selected_foreach(func, data=None)

`func` : | the function or method to call for each selected node.
`data` : | the user data to pass to `func`.

The `selected_foreach`() method calls the function or method specified by `func` for each selected node passing the user data specified by `data`. The signature of `func` is:

        def foreachfunction(treemodel, path, iter, ...)

        def foreachmethod(self, treemodel, path, iter, ...)

where `treemodel` is the `gtk.TreeModel` being viewed, `path` is the path of the selected row, `iter` is a `gtk.TreeIter` pointing to the selected row and `...` is the user data if any (may not be present if `data` was `None`). If `func` is a method then `self` is the object that the method is called upon.

### Note

You cannot modify the tree or selection in the callback function.

### gtk.TreeSelection.select_path

        def select_path(path)

`path` : | the tree path to be selected.

The `select_path`() method selects the row at `path`.

### gtk.TreeSelection.unselect_path

        def unselect_path(path)

`path` : | the tree path to be unselected.

The `unselect_path`() method unselects the row at `path`.

### gtk.TreeSelection.select_iter

        def select_iter(iter)

`iter` : | the `gtk.TreeIter` to be selected.

The `select_iter`() method selects the row pointed to by the `gtk.TreeIter` specified by `iter`.

### gtk.TreeSelection.unselect_iter

        def unselect_iter(iter)

`iter` : | the `gtk.TreeIter` to be unselected.

The `unselect_iter`() method unselects the row pointed to by the `gtk.TreeIter` specified by `iter`.

### gtk.TreeSelection.path_is_selected

        def path_is_selected(path)

`path` : | A tree path to check if selected.
Returns : | `True` if `path` is selected.

The `path_is_selected`() method returns `True` if the row pointed to by `path` is currently selected. If `path` does not point to a valid location, `False` is returned.

### gtk.TreeSelection.iter_is_selected

        def iter_is_selected(iter)

`iter` : | a `gtk.TreeIter`
Returns : | `True`, if the row pointed to by `iter` is selected

The `iter_is_selected`() method returns `True` if the row pointed to by `iter` is currently selected.

### gtk.TreeSelection.select_all

        def select_all()

The `select_all`() method selects all the nodes. The treeselection is must be set to `gtk.SELECTION_MULTIPLE` mode.

### gtk.TreeSelection.unselect_all

        def unselect_all()

The `unselect_all`() method unselects all the nodes.

### gtk.TreeSelection.select_range

        def select_range(start_path, end_path)

`start_path` : | the initial node path of the range.
`end_path` : | the final node path of the range.

The `select_range`() method selects a range of nodes specified by the tree paths `start_path` and `end_path` inclusive.

### gtk.TreeSelection.unselect_range

        def unselect_range(start_path, end_path)

`start_path` : | The initial node of the range.
`end_path` : | The final node of the range.

### Note

This method is available in PyGTK 2.2 and above.

The `unselect_range`() method unselects the range of nodes specified by the tree paths `start_path` and `end_path` inclusive.

## Signals

### The "changed" gtk.TreeSelection Signal

        def callback(treeselection, user_param1, ...)

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

The "changed" signal is emitted when the selection has changed.

Prev | Up | Next
gtk.TreeRowReference | Home | gtk.TreeSortable