Xfce Foundation Classes
Main Page | Index | Namespace List | Alphabetical List | Class List | File List

# Xfc::Gtk::TreeSelection Class Reference

A GtkTreeSelection C++ wrapper class. More...

`#include <xfc/gtk/treeselection.hh>`

Inheritance diagram for Xfc::Gtk::TreeSelection:

List of all members.

## Signal Prototypes

- const ChangedSignalType changed_signal
    Changed signal (see signal_changed()).

## Public Types

- typedef sigc::slot< bool,
  TreeModel &, const TreePath &,
  bool > SelectSlot
    Signature of the callback slot used by set_select_function() to filter whether or not a row may be selected.
- typedef sigc::slot< void,
  TreeModel &, const TreePath &,
  const TreeIter & > ForeachSlot
    Signature of the callback slot used by selected_foreach() to map all selected rows.

## Public Member Functions

Constructors

- virtual ~TreeSelection ()
    Desrtuctor.

Accessors

- GtkTreeSelection * gtk_tree_selection () const
    Get a pointer to the GtkTreeSelection structure.
- operator GtkTreeSelection * () const
    Conversion operator; safely converts a TreeSelection to a GtkTreeSelection pointer.
- SelectionMode get_mode () const
    Gets the selection mode for selection (see set_mode()).
- TreeView * get_tree_view () const
    Returns the tree view associated with the selection.
- bool any_selected () const
    Returns true if there are any selected nodes.
- bool get_selected (TreeIter *iter, TreeModel **model=0) const
    Sets iter to the currently selected node if selection is set to SELECTION_SINGLE or SELECTION_BROWSE.
- bool get_selected_rows (std::vector< TreePath > &rows, TreeModel **model=0)
    Creates a list of TreePath of all selected rows.
- int count_selected_rows () const
    Returns the number of rows that have been selected in the tree.
- bool path_is_selected (const TreePath &path) const
    Returns true if the row pointed to by path is currently selected.
- bool iter_is_selected (const TreeIter &iter) const
    Returns true if the row at iter is currently selected.

Methods

- void set_mode (SelectionMode type)
    Sets the selection mode of the selection.
- void set_select_function (const SelectSlot &select)
    Sets the selection callback slot.
- void selected_foreach (const ForeachSlot &each)
    Calls each for each selected node.
- void select_path (const TreePath &path)
    Select the row at path.
- void unselect_path (const TreePath &path)
    Unselects the row at path.
- void select_iter (const TreeIter &iter)
    Selects the specified iterator.
- void unselect_iter (const TreeIter &iter)
    Unselects the specified iterator.
- void select_all ()
    Selects all the nodes. The selection mode is must be set to SELECTION_MULTIPLE.
- void unselect_all ()
    Unselects all the nodes.
- void select_range (const TreePath &start_path, const TreePath &end_path)
    Selects a range of nodes, determined by start_path and end_path inclusive.
- void unselect_range (const TreePath &start_path, const TreePath &end_path)
    Unselects a range of nodes, determined by start_path and end_path inclusive.

Signal Proxies

- const ChangedSignalProxy signal_changed ()
    Connect to the changed_signal; emitted whenever the selection has (possibly) changed.

## Protected Member Functions

Constructors

- TreeSelection (GtkTreeSelection *tree_selection, bool owns_reference=true)
    Construct a new TreeSelection from an existing GtkTreeSelection.

## Detailed Description

A GtkTreeSelection C++ wrapper class.

TreeSelection is a helper object that manages the selection for a TreeView widget. The TreeSelection object is automatically created when a new TreeView widget is created, and cannot exist independentally of this widget. The primary reason the TreeSelection object exists is for cleanliness of code and API. That is, there is no conceptual reason why all its methods could not be methods on the TreeView widget.

The TreeSelection object is gotten from a TreeView by calling Gtk::TreeView::get_selection(). It can be manipulated to check the selection status of the tree, as well as select and deselect individual rows. Selection is done completely 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 select_row on an already selected row).

## Member Typedef Documentation

typedef sigc::slot<void, TreeModel&, const TreePath&, const TreeIter&> Xfc::Gtk::TreeSelection::ForeachSlot

Signature of the callback slot used by selected_foreach() to map all selected rows.

Example: Method signature for ForeachSlot.

                 void method(TreeModel& model, const TreePath& path, const TreeIter& iter);

                 // model: The TreeModel being viewed.
                 // path: The TreePath of a selected row.
                 // iter: A TreeIter pointing to a selected row.

This slot will be called on every selected row in the tree view.

typedef sigc::slot<bool, TreeModel&, const TreePath&, bool> Xfc::Gtk::TreeSelection::SelectSlot

Signature of the callback slot used by set_select_function() to filter whether or not a row may be selected.

Example: Method signature for SelectSlot.

                 bool method(TreeModel& model, const TreePath& path, bool path_currently_selected);

                 // model: The TreeModel being viewed.
                 // path: The TreePath of the row in question.
                 // path_currently_selected: true if the path is currently selected.
                 // return: true if the selection state of the row can be toggled.

This slot is called whenever a row's state might change. A return value of true indicates to the TreeSelection that it is okay to change the selection.

## Constructor & Destructor Documentation

Xfc::Gtk::TreeSelection::TreeSelection | ( | GtkTreeSelection * | tree_selection,
|  | bool | owns_reference = `true`
| ) | `[explicit, protected]`

Construct a new TreeSelection from an existing GtkTreeSelection.

Parameters:

  | tree_selection | A pointer to a GtkTreeSelection.
  | owns_reference | Set false if the initial reference count is floating, set true if it's not.

The tree_selection can be a newly created GtkTreeSelection or an existing GtkTreeSelection (see G::Object::Object).

## Member Function Documentation

SelectionMode Xfc::Gtk::TreeSelection::get_mode | ( |  | ) | const

Gets the selection mode for selection (see set_mode()).

Returns:
  The current selection mode.

bool Xfc::Gtk::TreeSelection::get_selected | ( | TreeIter * | iter,
|  | TreeModel ** | model = `0`
| ) | const

Sets iter to the currently selected node if selection is set to SELECTION_SINGLE or SELECTION_BROWSE.

Parameters:

  | iter | The TreeIter, or null.
  | model | A pointer to set to the TreeModel, or null.

Returns:
  true if there is a selected node.

iter may be null if you just want to test if selection has any selected nodes. model is filled with the current model as a convenience. This method will not work if you use the selection mode SELECTION_MULTIPLE.

bool Xfc::Gtk::TreeSelection::get_selected_rows | ( | std::vector< TreePath > & | rows,
|  | TreeModel ** | model = `0`
| ) |

Creates a list of TreePath of all selected rows.

Parameters:

  | rows | A reference to a vector of TreePath to hold the list of selected rows.
  | model | A pointer to set to the TreeModel, or null.

Returns:
  true if the vector is not empty.

Additionally, if you are planning on modifying the model after calling this function, you may want to convert the returned list into a list of TreeRowReferences. To do this, you can use the constructor TreeRowReference(G::Object&, TreeModel&, const TreePath&).

bool Xfc::Gtk::TreeSelection::iter_is_selected | ( | const TreeIter & | iter | ) | const

Returns true if the row at iter is currently selected.

Parameters:

  | iter | A valid TreeIter.

bool Xfc::Gtk::TreeSelection::path_is_selected | ( | const TreePath & | path | ) | const

Returns true if the row pointed to by path is currently selected.

Parameters:

  | path | A TreePath to check selection on.

Returns:
  true if path is selected.

If path does not point to a valid location, false is returned.

void Xfc::Gtk::TreeSelection::select_iter | ( | const TreeIter & | iter | ) |

Selects the specified iterator.

Parameters:

  | iter | The TreeIter to be selected.

void Xfc::Gtk::TreeSelection::select_path | ( | const TreePath & | path | ) |

Select the row at path.

Parameters:

  | path | The TreePath to be selected.

void Xfc::Gtk::TreeSelection::select_range | ( | const TreePath & | start_path,
|  | const TreePath & | end_path
| ) |

Selects a range of nodes, determined by start_path and end_path inclusive.

Parameters:

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

void Xfc::Gtk::TreeSelection::selected_foreach | ( | const ForeachSlot & | each | ) |

Calls each for each selected node.

Parameters:

  | each | The slot to call for each selected node.

Note that you cannot modify the tree or selection from within this method. As a result, get_selected_rows() might be more useful.

void Xfc::Gtk::TreeSelection::set_mode | ( | SelectionMode | type | ) |

Sets the selection mode of the selection.

Parameters:

  | type | The selection mode.

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

void Xfc::Gtk::TreeSelection::set_select_function | ( | const SelectSlot & | select | ) |

Sets the selection callback slot.

Parameters:

  | select | The selection slot to call.

If set, this method is called before any node is selected or unselected, giving some control over which nodes are selected. The selection slot should return true if the state of the node may be toggled, and false if the state of the node should be left unchanged.

const ChangedSignalProxy Xfc::Gtk::TreeSelection::signal_changed | ( |  | ) |

| Connect to the changed_signal; emitted whenever the selection has (possibly) changed. Please note that this signal is mostly a hint. It may only be emitted once when a range of rows are selected, and it may occasionally be emitted when nothing has happened.

void Xfc::Gtk::TreeSelection::unselect_iter | ( | const TreeIter & | iter | ) |

Unselects the specified iterator.

Parameters:

  | iter | The TreeIter to be unselected.

void Xfc::Gtk::TreeSelection::unselect_path | ( | const TreePath & | path | ) |

Unselects the row at path.

Parameters:

  | path | The TreePath to be unselected.

void Xfc::Gtk::TreeSelection::unselect_range | ( | const TreePath & | start_path,
|  | const TreePath & | end_path
| ) |

Unselects a range of nodes, determined by start_path and end_path inclusive.

Parameters:

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

## Member Data Documentation

const ChangedSignalType Xfc::Gtk::TreeSelection::changed_signal `[static, protected]`

Changed signal (see signal_changed()).

Calls a slot with the signature:

                 void function();

The documentation for this class was generated from the following file:

- treeselection.hh

Xfce Foundation Classes

Copyright © 2004-2005 The XFC Development Team | XFC 4.3