14.8. TreeSelections
Prev | Chapter 14. Tree View Widget | Next

## 14.8. TreeSelections

### 14.8.1. Getting the TreeSelection

`TreeSelection`s are objects that manage selections in a `TreeView`. When a `TreeView` is created a `TreeSelection` is automatically created as well. The `TreeSelection` can be retrieved from the `TreeView` using the method:

      treeselection = treeview.get_selection()

You can retrieve the `TreeView` associated with a `TreeSelection` by calling the method:

      treeview = treeselection.get_treeview()

### 14.8.2. TreeSelection Modes

The `TreeSelection` supports the following selection modes:

`gtk.SELECTION_NONE` | No selection is allowed.
`gtk.SELECTION_SINGLE` | A single selection is allowed by clicking.
`gtk.SELECTION_BROWSE` | A single selection allowed by browsing with the pointer.
`gtk.SELECTION_MULTIPLE` | Multiple items can be selected at once.

You can retrieve the current selection mode by calling the method:

      mode = treeselection.get_mode()

The mode can be set using:

      treeselection.set_mode(mode)

where `mode` is one of the above selection modes.

### 14.8.3. Retrieving the Selection

The method to use to retrieve the selection depends on the current selection mode. If the selection mode is `gtk.SELECTION_SINGLE` or `gtk.SELECTION_BROWSE`, you should use the following method:

      (model, iter) = treeselection.get_selected()

that returns a 2-tuple containing `model`, the `TreeModel` used by the `TreeView` associated with `treeselection` and `iter`, a `TreeIter` pointing at the selected row. If no row is selected then `iter` is `None`. If the selection mode is `gtk.SELECTION_MULTIPLE` a TypeError exception is raised.

If you have a `TreeView` using the `gtk.SELECTION_MULTIPLE` selection mode then you should use the method:

      (model, pathlist) = treeselection.get_selected_rows()

that returns a 2-tuple containing the tree model and a list of the tree paths of the selected rows. This method is not available in PyGTK 2.0 so you'll have to use a helper function to retrieve the list by using:

      treeselection.selected_foreach(func, data=None)

where `func` is a function that is called on each selected row with `data`. The signature of `func` is:

      def func(model, path, iter, data)

where `model` is the `TreeModel`, `path` is the tree path of the selected row and `iter` is a `TreeIter` pointing at the selected row.

This method can be used to simulate the `get_selected_row`() method as follows:

      ...
      def foreach_cb(model, path, iter, pathlist):
          list.append(path)
      ...
      def my_get_selected_rows(treeselection):
          pathlist = []
          treeselection.selected_foreach(foreach_cb, pathlist)
          model = sel.get_treeview().get_model()
          return (model, pathlist)
      ...

The `selected_foreach`() method cannot be used to modify the tree model or the selection though you can change the data in the rows.

### 14.8.4. Using a TreeSelection Function

If you want ultimate control over row selection you can set a function to be called before a row is selected or unselected by using the method:

      treeselection.set_select_function(func, data)

where `func` is a callback function and `data` is user data to be passed to `func` when it is called. `func` has the signature:

      def func(selection, model, path, is_selected, user_data)

where `selection` is the `TreeSelection`, `model` is the `TreeModel` used with the `TreeView` associated with `selection`, `path` is the tree path of the selected row, `is_selected` is `TRUE` if the row is currently selected and `user_data` is `data`. `func` should return `TRUE` if the row's selection status should be toggled.

Setting a select function is useful if:

- you want to control the selection or unselection of a row based on some additional context information. You will need to indicate in some way that the selection change can't be made and perhaps why. For example, you can visually differentiate the row or pop up a `MessageDialog`.
- you need to maintain your own list of selected or unselected rows though this can also be done by connecting to the "changed" signal but with more effort.
- you want to do some additional processing before a row is selected or unselected. For example change the look of the row or modify the row data.

### 14.8.5. Selecting and Unselecting Rows

You can change the selection programmatically using the following methods:

      treeselection.select_path(path)
      treeselection.unselect_path(path)

      treeselection.select_iter(iter)
      treeselection.unselect_iter(iter)

These methods select or unselect a single row that is specified by either `path`, a tree path or `iter`, a `TreeIter` pointing at the row. The following methods select or unselect several rows at once:

      treeselection.select_all()
      treeselection.unselect_all()

      treeselection.select_range(start_path, end_path)
      treeselection.unselect_range(start_path, end_path)

The `select_all`() method requires that the selection mode be `gtk.SELECTION_MULTIPLE` as does the `select_range`() method. The `unselect_all`() and `unselect_range`() methods will function with any selection mode. Note that the `unselect_all`() method is not available in PyGTK 2.0

You can check if a row is selected by using one of the methods:

      result = treeselection.path_is_selected(path)
      result = treeselection.iter_is_selected(iter)

that return `TRUE` if the row specified by `path` or `iter` is currently selected. You can retrieve a count of the number of selected rows using the method:

      count = treeselection.count_selected_rows()

This method is not available in PyGTK 2.0 so you'll have to simulate it using the `selected_foreach`() method similar to the simulation of the `get_selected_rows`() method in Section 21.2, “Retrieving the Selection”. For example:

      ...
      def foreach_cb(model, path, iter, counter):
          counter[0] += 1
      ...
      def my_count_selected_rows(treeselection):
          counter = [0]
          treeselection.selected_foreach(foreach_cb, counter)
          return counter[0]
      ...

Prev | Up | Next
14.7. TreeView Signals | Home | 14.9. TreeView Drag and Drop