TreeSelections 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()

The TreeSelection supports the following selection modes:

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.

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.

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 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]
  ...