gtk.TreeSelection

gtk.TreeSelection
Prev	The gtk Class Reference	Next

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

`func` :	the selection function.
`data` :	the selection function's data.

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.

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.