gtkmm: Gtk::TreeSelection Class Reference

gtkmm 3.24.1

Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Related Functions | List of all members
Gtk::TreeSelection Class Reference
TreeView Classes

Typedefed as Gtk::TreeView::Selection. More...

`#include <gtkmm/treeselection.h>`

Inheritance diagram for Gtk::TreeSelection:
[legend]

## Public Types
typedef sigc::slot< bool, const Glib::RefPtr< TreeModel >&, const TreeModel::Path&, bool > | SlotSelect
| For instance, bool on_select_function(const Glib::RefPtr<TreeModel>& model, const TreeModel::Path& path, bool path_currently_selected) The select 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. More...
typedef sigc::slot< void, const TreeModel::iterator& > | SlotForeachIter
| For example, void on_foreach(const Gtk::TreeModel::iterator& iter);. More...
typedef sigc::slot< void, const TreeModel::Path& > | SlotForeachPath
| For example, void on_foreach(const Gtk::TreeModel::Path& path);. More...
typedef sigc::slot< void, const TreeModel::Path&, const TreeModel::iterator& > | SlotForeachPathAndIter
| For example, void on_foreach(const Gtk::TreeModel::Path& path, const Gtk::TreeModel::iterator& iter);. More...
Public Types inherited from Glib::Object
typedef void(*)(gpointer data | DestroyNotify)
Public Types inherited from sigc::trackable
typedef internal::func_destroy_notify | func_destroy_notify

## Public Member Functions
| TreeSelection (TreeSelection&& src) noexcept
TreeSelection& | operator= (TreeSelection&& src) noexcept
| ~TreeSelection () noexcept override
GtkTreeSelection* | gobj ()
| Provides access to the underlying C GObject. More...
const GtkTreeSelection* | gobj () const
| Provides access to the underlying C GObject. More...
GtkTreeSelection* | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. More...
void | set_mode (SelectionMode type)
| Sets the selection mode of the selection. More...
SelectionMode | get_mode () const
| Gets the selection mode for selection. More...
void | set_select_function (const SlotSelect& slot)
| Sets the selection callback slot. More...
TreeView* | get_tree_view ()
| Returns the tree view associated with selection. More...
const TreeView* | get_tree_view () const
| Returns the tree view associated with selection. More...
Glib::RefPtr< TreeModel > | get_model ()
| Shortcut for get_tree_view()->get_model(). More...
Glib::RefPtr< const TreeModel > | get_model () const
TreeModel::iterator | get_selected ()
| Get the currently selected row. More...
TreeModel::iterator | get_selected (Glib::RefPtr< TreeModel >& model)
| Get the currently selected row. More...
std::vector< TreeModel::Path > | get_selected_rows () const
| Creates a list of paths of all selected rows. More...
std::vector< TreeModel::Path > | get_selected_rows (Glib::RefPtr< TreeModel >& model)
| Creates a list of paths of all selected rows. More...
int | count_selected_rows () const
| Returns the number of rows that have been selected in tree. More...
void | selected_foreach_iter (const SlotForeachIter& slot) const
| Calls a callback slot for each selected node. More...
void | selected_foreach_path (const SlotForeachPath& slot) const
| Calls a callback slot for each selected node. More...
void | selected_foreach (const SlotForeachPathAndIter& slot) const
| Calls a callback slot for each selected node. More...
void | select (const TreeModel::Path& path)
| Select the row at path. More...
void | select (const TreeModel::iterator& iter)
| Selects the specified iterator. More...
void | select (const TreeModel::Row& row)
| Selects the specified iterator. More...
void | select (const TreeModel::Path& start_path, const TreeModel::Path& end_path)
| Selects a range of nodes, determined by start_path and end_path inclusive. More...
void | unselect (const TreeModel::Path& path)
| Unselects the row at path. More...
void | unselect (const TreeModel::Path& start_path, const TreeModel::Path& end_path)
| Unselects a range of nodes, determined by start_path and end_path inclusive. More...
void | unselect (const TreeModel::iterator& iter)
| Unselects the specified iterator. More...
bool | is_selected (const TreeModel::Path& path) const
| Returns `true` if the row pointed to by path is currently selected. More...
bool | is_selected (const TreeModel::iterator& iter) const
| Returns `true` if the row at iter is currently selected. More...
void | select_all ()
| Selects all the nodes. More...
void | unselect_all ()
| Unselects all the nodes. More...
Glib::PropertyProxy< SelectionMode > | property_mode ()
| Selection mode. More...
Glib::PropertyProxy_ReadOnly< SelectionMode > | property_mode () const
| Selection mode. More...
Glib::SignalProxy< void > | signal_changed ()
Public Member Functions inherited from Glib::Object
| Object (const Object &)=delete
Object & | operator= (const Object &)=delete
| Object (Object &&src) noexcept
Object & | operator= (Object &&src) noexcept
void * | get_data (const QueryQuark &key)
void | set_data (const Quark &key, void *data)
void | set_data (const Quark &key, void *data, DestroyNotify notify)
void | remove_data (const QueryQuark &quark)
void * | steal_data (const QueryQuark &quark)
Glib::RefPtr< Glib::Object > | wrap (GObject *object, bool take_copy=false)
Public Member Functions inherited from Glib::ObjectBase
| ObjectBase (const ObjectBase &)=delete
ObjectBase & | operator= (const ObjectBase &)=delete
void | set_property_value (const Glib::ustring &property_name, const Glib::ValueBase &value)
void | get_property_value (const Glib::ustring &property_name, Glib::ValueBase &value) const
void | set_property (const Glib::ustring &property_name, const PropertyType &value)
void | get_property (const Glib::ustring &property_name, PropertyType &value) const
void | connect_property_changed (const Glib::ustring &property_name, const sigc::slot< void > &slot)
void | connect_property_changed (const Glib::ustring &property_name, sigc::slot< void > &&slot)
sigc::connection | connect_property_changed_with_return (const Glib::ustring &property_name, const sigc::slot< void > &slot)
sigc::connection | connect_property_changed_with_return (const Glib::ustring &property_name, sigc::slot< void > &&slot)
void | freeze_notify ()
void | thaw_notify ()
virtual void | reference () const
virtual void | unreference () const
GObject * | gobj ()
const GObject * | gobj () const
GObject * | gobj_copy () const
Public Member Functions inherited from sigc::trackable
| trackable () noexcept
| trackable (const trackable &src) noexcept
| trackable (trackable &&src)
| ~trackable ()
void | add_destroy_notify_callback (void *data, func_destroy_notify func) const
void | notify_callbacks ()
trackable & | operator= (const trackable &src)
trackable & | operator= (trackable &&src)
void | remove_destroy_notify_callback (void *data) const

## Static Public Member Functions
static GType | get_type ()
| Get the GType for this class, for use with the underlying GObject type system. More...

## Protected Member Functions
virtual void | on_changed ()
| This is a default handler for the signal signal_changed(). More...
Protected Member Functions inherited from Glib::Object
| Object ()
| Object (const Glib::ConstructParams &construct_params)
| Object (GObject *castitem)
| ~Object () noexcept override
Protected Member Functions inherited from Glib::ObjectBase
| ObjectBase ()
| ObjectBase (const char *custom_type_name)
| ObjectBase (const std::type_info &custom_type_info)
| ObjectBase (ObjectBase &&src) noexcept
ObjectBase & | operator= (ObjectBase &&src) noexcept
virtual | ~ObjectBase () noexcept=0
void | initialize (GObject *castitem)
void | initialize_move (GObject *castitem, Glib::ObjectBase *previous_wrapper)

## Related Functions
(Note that these are not member functions.)
Glib::RefPtr< Gtk::TreeSelection > | wrap (GtkTreeSelection* object, bool take_copy=false)
| A Glib::wrap() method for this object. More...

## Detailed Description

Typedefed as Gtk::TreeView::Selection.

This is a helper object to manage the selection for a Gtk::TreeView widget.

It is automatically created when a new Gtk::TreeView widget is created, and cannot exist independently of this widget. The primary reason this class exists is for cleanliness of code and API. That is, there is no conceptual reason all these methods could not be methods on the Gtk::TreeView widget instead of a separate class.

The Gtk::TreeSelection object can be obtained from a Gtk::TreeView by calling Gtk::TreeView::get_selection(). It can be manipulated to check the selection status of the tree, as well as to 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.

When monitoring the selection of a view, it's important to remember 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.

## Member Typedef Documentation

## ◆ SlotForeachIter

typedef sigc::slot<void, const TreeModel::iterator&> Gtk::TreeSelection::SlotForeachIter

For example, void on_foreach(const Gtk::TreeModel::iterator& iter);.

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

## ◆ SlotForeachPath

typedef sigc::slot<void, const TreeModel::Path&> Gtk::TreeSelection::SlotForeachPath

For example, void on_foreach(const Gtk::TreeModel::Path& path);.

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

## ◆ SlotForeachPathAndIter

typedef sigc::slot<void, const TreeModel::Path&, const TreeModel::iterator&> Gtk::TreeSelection::SlotForeachPathAndIter

For example, void on_foreach(const Gtk::TreeModel::Path& path, const Gtk::TreeModel::iterator& iter);.

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

## ◆ SlotSelect

typedef sigc::slot<bool, const Glib::RefPtr<TreeModel>&, const TreeModel::Path&, bool> Gtk::TreeSelection::SlotSelect

For instance, bool on_select_function(const Glib::RefPtr<TreeModel>& model, const TreeModel::Path& path, bool path_currently_selected) The select 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.

## Constructor & Destructor Documentation

## ◆ TreeSelection()

Gtk::TreeSelection::TreeSelection | ( | TreeSelection&& | src | ) |
| noexcept

## ◆ ~TreeSelection()

Gtk::TreeSelection::~TreeSelection | ( |  | ) |
| overridenoexcept

## Member Function Documentation

## ◆ count_selected_rows()

int Gtk::TreeSelection::count_selected_rows | ( |  | ) | const

Returns the number of rows that have been selected in tree.

Since gtkmm 2.2:

Returns
  The number of rows selected.

## ◆ get_mode()

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

Gets the selection mode for selection.

See set_mode().

Returns
  The current selection mode.

## ◆ get_model() [1/2]

Glib::RefPtr<TreeModel> Gtk::TreeSelection::get_model | ( |  | ) |

Shortcut for get_tree_view()->get_model().

Returns
  The TreeModel associated with this TreeSelection.

## ◆ get_model() [2/2]

Glib::RefPtr<const TreeModel> Gtk::TreeSelection::get_model | ( |  | ) | const

## ◆ get_selected() [1/2]

TreeModel::iterator Gtk::TreeSelection::get_selected | ( |  | ) |

Get the currently selected row.

Returns
  The currently selected row.

Note
  This method won't work if the selection mode is `Gtk::SELECTION_MULTIPLE`. Use get_selected_rows() for multiple selections.

## ◆ get_selected() [2/2]

TreeModel::iterator Gtk::TreeSelection::get_selected | ( | Glib::RefPtr< TreeModel >& | model | ) |

Get the currently selected row.

Returns
  The currently selected row. Or end() if no rows were selected.

Return values

  model | The current TreeModel.

Note
  This method won't work if the selection mode is `Gtk::SELECTION_MULTIPLE`. Use get_selected_rows() for multiple selections.

## ◆ get_selected_rows() [1/2]

std::vector<TreeModel::Path> Gtk::TreeSelection::get_selected_rows | ( |  | ) | const

Creates a list of paths of all selected rows.

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

Returns
  a standard container containing a Gtk::Model::Path for each selected row.

## ◆ get_selected_rows() [2/2]

std::vector<TreeModel::Path> Gtk::TreeSelection::get_selected_rows | ( | Glib::RefPtr< TreeModel >& | model | ) |

Creates a list of paths of all selected rows.

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

Return values

  model | The current TreeModel.

Returns
  a standard container containing a Gtk::Model::Path for each selected row.

## ◆ get_tree_view() [1/2]

TreeView* Gtk::TreeSelection::get_tree_view | ( |  | ) |

Returns the tree view associated with selection.

Returns
  A Gtk::TreeView.

## ◆ get_tree_view() [2/2]

const TreeView* Gtk::TreeSelection::get_tree_view | ( |  | ) | const

Returns the tree view associated with selection.

Returns
  A Gtk::TreeView.

## ◆ get_type()

static GType Gtk::TreeSelection::get_type | ( |  | ) |
| static

Get the GType for this class, for use with the underlying GObject type system.

## ◆ gobj() [1/2]

GtkTreeSelection* Gtk::TreeSelection::gobj | ( |  | ) |
| inline

Provides access to the underlying C GObject.

## ◆ gobj() [2/2]

const GtkTreeSelection* Gtk::TreeSelection::gobj | ( |  | ) | const
| inline

Provides access to the underlying C GObject.

## ◆ gobj_copy()

GtkTreeSelection* Gtk::TreeSelection::gobj_copy | ( |  | ) |

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

## ◆ is_selected() [1/2]

bool Gtk::TreeSelection::is_selected | ( | const TreeModel::Path& | path | ) | const

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

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

Parameters

  path | A Gtk::TreePath to check selection on.

Returns
  `true` if path is selected.

## ◆ is_selected() [2/2]

bool Gtk::TreeSelection::is_selected | ( | const TreeModel::iterator& | iter | ) | const

Returns `true` if the row at iter is currently selected.

Parameters

  iter | A valid Gtk::TreeIter.

Returns
  `true`, if iter is selected.

## ◆ on_changed()

virtual void Gtk::TreeSelection::on_changed | ( |  | ) |
| protectedvirtual

This is a default handler for the signal signal_changed().

## ◆ operator=()

TreeSelection& Gtk::TreeSelection::operator= | ( | TreeSelection&& | src | ) |
| noexcept

## ◆ property_mode() [1/2]

Glib::PropertyProxy< SelectionMode > Gtk::TreeSelection::property_mode | ( |  | ) |

Selection mode.

See Gtk::TreeSelection::set_mode() for more information on this property.

Since gtkmm 3.2:

Default value: Gtk::SELECTION_SINGLE

Returns
  A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.

## ◆ property_mode() [2/2]

Glib::PropertyProxy_ReadOnly< SelectionMode > Gtk::TreeSelection::property_mode | ( |  | ) | const

Selection mode.

See Gtk::TreeSelection::set_mode() for more information on this property.

Since gtkmm 3.2:

Default value: Gtk::SELECTION_SINGLE

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## ◆ select() [1/4]

void Gtk::TreeSelection::select | ( | const TreeModel::Path& | path | ) |

Select the row at path.

Parameters

  path | The Gtk::TreePath to be selected.

## ◆ select() [2/4]

void Gtk::TreeSelection::select | ( | const TreeModel::iterator& | iter | ) |

Selects the specified iterator.

Parameters

  iter | The Gtk::TreeIter to be selected.

## ◆ select() [3/4]

void Gtk::TreeSelection::select | ( | const TreeModel::Row& | row | ) |

Selects the specified iterator.

Parameters

  row | The Gtk::TreeIter to be selected.

## ◆ select() [4/4]

void Gtk::TreeSelection::select | ( | const TreeModel::Path& | start_path,
|  | const TreeModel::Path& | end_path
| ) |  |

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

selection must be set to Gtk::SELECTION_MULTIPLE mode.

Parameters

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

## ◆ select_all()

void Gtk::TreeSelection::select_all | ( |  | ) |

Selects all the nodes.

selection must be set to Gtk::SELECTION_MULTIPLE mode.

## ◆ selected_foreach()

void Gtk::TreeSelection::selected_foreach | ( | const SlotForeachPathAndIter& | slot | ) | const

Calls a callback slot for each selected node.

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

Parameters

  slot | The function to call for each selected node.

## ◆ selected_foreach_iter()

void Gtk::TreeSelection::selected_foreach_iter | ( | const SlotForeachIter& | slot | ) | const

Calls a callback slot for each selected node.

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

Parameters

  slot | The function to call for each selected node.

## ◆ selected_foreach_path()

void Gtk::TreeSelection::selected_foreach_path | ( | const SlotForeachPath& | slot | ) | const

Calls a callback slot for each selected node.

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

Parameters

  slot | The function to call for each selected node.

## ◆ set_mode()

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

Sets the selection mode of the selection.

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

Parameters

  type | The selection mode.

## ◆ set_select_function()

void Gtk::TreeSelection::set_select_function | ( | const SlotSelect& | slot | ) |

Sets the selection callback slot.

If set, this function is called before any node is selected or unselected, giving some control over which nodes are selected.

The select 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.

Parameters

  slot | The selection function.

## ◆ signal_changed()

Glib::SignalProxy< void > Gtk::TreeSelection::signal_changed | ( |  | ) |

Slot Prototype:
  `void on_my_changed()`

Flags: Run First

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.

## ◆ unselect() [1/3]

void Gtk::TreeSelection::unselect | ( | const TreeModel::Path& | path | ) |

Unselects the row at path.

Parameters

  path | The Gtk::TreePath to be unselected.

## ◆ unselect() [2/3]

void Gtk::TreeSelection::unselect | ( | const TreeModel::Path& | start_path,
|  | const TreeModel::Path& | end_path
| ) |  |

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

Since gtkmm 2.2:

Parameters

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

## ◆ unselect() [3/3]

void Gtk::TreeSelection::unselect | ( | const TreeModel::iterator& | iter | ) |

Unselects the specified iterator.

Parameters

  iter | The Gtk::TreeIter to be unselected.

## ◆ unselect_all()

void Gtk::TreeSelection::unselect_all | ( |  | ) |

Unselects all the nodes.

## Friends And Related Function Documentation

## ◆ wrap()

Glib::RefPtr< Gtk::TreeSelection > wrap | ( | GtkTreeSelection * | object,
|  | bool | take_copy = `false`
| ) |  |
| related

A Glib::wrap() method for this object.

Parameters

  object | The C instance.
  take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns
  A C++ instance that wraps this C instance.