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:

Xfc::G::Object Xfc::G::TypeInstance Xfc::Trackable List of all members.

Signal Prototypes

Public Types

Public Member Functions

Constructors
Accessors
Methods
Signal Proxies

Protected Member Functions

Constructors

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: Xfce Foundation Classes
Copyright © 2004-2005 The XFC Development Team XFC 4.3