Documentation fixes.

[~andy/gtk] / docs / reference / gtk / tmpl / gtktreeselection.sgml

<!-- ##### SECTION Title ##### -->
GtkTreeSelection

<!-- ##### SECTION Short_Description ##### -->
The selection object for #GtkTreeView

<!-- ##### SECTION Long_Description ##### -->
<para>
The #GtkTreeSelection object is a helper object to manage the selection
for a #GtkTreeView widget.  The #GtkTreeSelection object is
automatically created when a new #GtkTreeView widget is created, and
cannot exist independentally of this widget.  The primary reason the
#GtkTreeSelection objects exists is for cleanliness of code and API.
That is, there is no conceptual reason all these functions could not be
methods on the #GtkTreeView widget instead of a separate function.
</para>

<para>
The #GtkTreeSelection object is gotten from a #GtkTreeView by calling
gtk_tree_view_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.
</para>

<para>
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).
</para>

<!-- ##### SECTION See_Also ##### -->
<para>
#GtkTreeView, #GtkTreeViewColumn, #GtkTreeDnd, #GtkTreeMode, #GtkTreeSortable, #GtkTreeModelSort, #GtkListStore, #GtkTreeStore, #GtkCellRenderer, #GtkCellEditable, #GtkCellRendererPixbuf, #GtkCellRendererText, #GtkCellRendererToggle
</para>

<!-- ##### STRUCT GtkTreeSelection ##### -->
<para>

</para>


<!-- ##### USER_FUNCTION GtkTreeSelectionFunc ##### -->
<para>
A function used by gtk_tree_selection_set_select_function() to filter
whether or not a row may be selected.  It is called whenever a row's
state might change.  A return value of %TRUE indicates to @selection
that it is okay to change the selection.
</para>

@selection: A #GtkTreeSelection
@model: A #GtkTreeModel being viewed
@path: The #GtkTreePath of the row in question
@path_currently_selected: %TRUE, if the path is currently selected
@data: user data
@Returns: %TRUE, if the selection state of the row can be toggled


<!-- ##### USER_FUNCTION GtkTreeSelectionForeachFunc ##### -->
<para>
A function used by gtk_tree_selection_selected_foreach() to map all
selected rows.  It will be called on every selected row in the view.
</para>

@model: The #GtkTreeModel being viewed
@path: The #GtkTreePath of a selected row
@iter: A #GtkTreeIter pointing to a selected row
@data: user data


<!-- ##### FUNCTION gtk_tree_selection_set_mode ##### -->
<para>

</para>

@selection: 
@type: 


<!-- ##### FUNCTION gtk_tree_selection_get_mode ##### -->
<para>

</para>

@selection: 
@Returns: 


<!-- ##### FUNCTION gtk_tree_selection_set_select_function ##### -->
<para>

</para>

@selection: 
@func: 
@data: 
@destroy: 


<!-- ##### FUNCTION gtk_tree_selection_get_user_data ##### -->
<para>

</para>

@selection: 
@Returns: 


<!-- ##### FUNCTION gtk_tree_selection_get_tree_view ##### -->
<para>

</para>

@selection: 
@Returns: 


<!-- ##### FUNCTION gtk_tree_selection_get_selected ##### -->
<para>

</para>

@selection: 
@model: 
@iter: 
@Returns: 


<!-- ##### FUNCTION gtk_tree_selection_selected_foreach ##### -->
<para>

</para>

@selection: 
@func: 
@data: 


<!-- ##### FUNCTION gtk_tree_selection_get_selected_rows ##### -->
<para>

</para>

@selection: 
@model: 
@Returns: 


<!-- ##### FUNCTION gtk_tree_selection_count_selected_rows ##### -->
<para>

</para>

@selection: 
@Returns: 


<!-- ##### FUNCTION gtk_tree_selection_select_path ##### -->
<para>

</para>

@selection: 
@path: 


<!-- ##### FUNCTION gtk_tree_selection_unselect_path ##### -->
<para>

</para>

@selection: 
@path: 


<!-- ##### FUNCTION gtk_tree_selection_path_is_selected ##### -->
<para>

</para>

@selection: 
@path: 
@Returns: 


<!-- ##### FUNCTION gtk_tree_selection_select_iter ##### -->
<para>

</para>

@selection: 
@iter: 


<!-- ##### FUNCTION gtk_tree_selection_unselect_iter ##### -->
<para>

</para>

@selection: 
@iter: 


<!-- ##### FUNCTION gtk_tree_selection_iter_is_selected ##### -->
<para>

</para>

@selection: 
@iter: 
@Returns: 


<!-- ##### FUNCTION gtk_tree_selection_select_all ##### -->
<para>

</para>

@selection: 


<!-- ##### FUNCTION gtk_tree_selection_unselect_all ##### -->
<para>

</para>

@selection: 


<!-- ##### FUNCTION gtk_tree_selection_select_range ##### -->
<para>

</para>

@selection: 
@start_path: 
@end_path: 


<!-- ##### FUNCTION gtk_tree_selection_unselect_range ##### -->
<para>

</para>

@selection: 
@start_path: 
@end_path: 


<!-- ##### SIGNAL GtkTreeSelection::changed ##### -->
<para>
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.
</para>

@treeselection: the object which received the signal.