* Boston, MA 02111-1307, USA.
*/
-#include <config.h>
+#include "config.h"
#include <string.h>
#include "gtktreeselection.h"
#include "gtktreeprivate.h"
#include "gtkrbtree.h"
#include "gtkmarshalers.h"
#include "gtkintl.h"
-#include "gtkalias.h"
+
+
+/**
+ * SECTION:gtktreeselection
+ * @Short_description: The selection object for GtkTreeView
+ * @Title: GtkTreeSelection
+ * @See_also: #GtkTreeView, #GtkTreeViewColumn, #GtkTreeDnd, #GtkTreeMode,
+ * #GtkTreeSortable, #GtkTreeModelSort, #GtkListStore, #GtkTreeStore,
+ * #GtkCellRenderer, #GtkCellEditable, #GtkCellRendererPixbuf,
+ * #GtkCellRendererText, #GtkCellRendererToggle
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * One of the important things to remember when monitoring the selection of
+ * a view is that the #GtkTreeSelection::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 #GtkTreeSelection::changed signal
+ * when nothing has happened (mostly as a result of programmers calling
+ * select_row on an already selected row).
+ */
+
static void gtk_tree_selection_finalize (GObject *object);
static gint gtk_tree_selection_real_select_all (GtkTreeSelection *selection);
object_class->finalize = gtk_tree_selection_finalize;
class->changed = NULL;
+ /**
+ * GtkTreeSelection::changed:
+ * @treeselection: the object which received the 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.
+ */
tree_selection_signals[CHANGED] =
g_signal_new (I_("changed"),
G_OBJECT_CLASS_TYPE (object_class),
GtkTreeSelection *selection = GTK_TREE_SELECTION (object);
if (selection->destroy)
- {
- GDestroyNotify d = selection->destroy;
-
- selection->destroy = NULL;
- d (selection->user_data);
- }
+ selection->destroy (selection->user_data);
/* chain parent_class' handler */
G_OBJECT_CLASS (gtk_tree_selection_parent_class)->finalize (object);
/**
* gtk_tree_selection_set_select_function:
* @selection: A #GtkTreeSelection.
- * @func: The selection function.
- * @data: The selection function's data.
- * @destroy: The destroy function for user data. May be NULL.
+ * @func: The selection function. May be %NULL
+ * @data: The selection function's data. May be %NULL
+ * @destroy: The destroy function for user data. May be %NULL
*
- * Sets the selection function. 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.
- **/
+ * Sets the selection function.
+ *
+ * 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.
+ */
void
gtk_tree_selection_set_select_function (GtkTreeSelection *selection,
GtkTreeSelectionFunc func,
GDestroyNotify destroy)
{
g_return_if_fail (GTK_IS_TREE_SELECTION (selection));
- g_return_if_fail (func != NULL);
if (selection->destroy)
- {
- GDestroyNotify d = selection->destroy;
-
- selection->destroy = NULL;
- d (selection->user_data);
- }
+ selection->destroy (selection->user_data);
selection->user_func = func;
selection->user_data = data;
}
/**
- * gtk_tree_selection_get_select_function:
+ * gtk_tree_selection_get_select_function: (skip)
* @selection: A #GtkTreeSelection.
*
* Returns the current selection function.
}
/**
- * gtk_tree_selection_get_user_data:
+ * gtk_tree_selection_get_user_data: (skip)
* @selection: A #GtkTreeSelection.
*
* Returns the user data for the selection function.
*
* Returns the tree view associated with @selection.
*
- * Return value: A #GtkTreeView
+ * Return value: (transfer none): A #GtkTreeView
**/
GtkTreeView *
gtk_tree_selection_get_tree_view (GtkTreeSelection *selection)
/**
* gtk_tree_selection_get_selected:
* @selection: A #GtkTreeSelection.
- * @model: A pointer to set to the #GtkTreeModel, or NULL.
- * @iter: The #GtkTreeIter, or NULL.
+ * @model: (out) (allow-none) (transfer none): A pointer to set to the #GtkTreeModel, or NULL.
+ * @iter: (out) (allow-none): The #GtkTreeIter, or NULL.
*
* Sets @iter to the currently selected node if @selection is set to
* #GTK_SELECTION_SINGLE or #GTK_SELECTION_BROWSE. @iter may be NULL if you
/**
* gtk_tree_selection_get_selected_rows:
* @selection: A #GtkTreeSelection.
- * @model: A pointer to set to the #GtkTreeModel, or NULL.
+ * @model: (out) (allow-none) (transfer none): A pointer to set to the #GtkTreeModel, or %NULL.
*
* Creates a list of path of all selected rows. Additionally, if you are
* planning on modifying the model after calling this function, you may
*
* To free the return value, use:
* |[
- * g_list_foreach (list, gtk_tree_path_free, NULL);
+ * g_list_foreach (list, (GFunc) gtk_tree_path_free, NULL);
* g_list_free (list);
* ]|
*
- * Return value: A #GList containing a #GtkTreePath for each selected row.
+ * Return value: (element-type GtkTreePath) (transfer full): A #GList containing a #GtkTreePath for each selected row.
*
* Since: 2.2
**/
/**
* gtk_tree_selection_selected_foreach:
* @selection: A #GtkTreeSelection.
- * @func: The function to call for each selected node.
+ * @func: (scope call): The function to call for each selected node.
* @data: user data to pass to the function.
*
* Calls a function for each selected node. Note that you cannot modify
g_object_ref (model);
/* connect to signals to monitor changes in treemodel */
- inserted_id = g_signal_connect_swapped (model, "row_inserted",
+ inserted_id = g_signal_connect_swapped (model, "row-inserted",
G_CALLBACK (model_changed),
&stop);
- deleted_id = g_signal_connect_swapped (model, "row_deleted",
+ deleted_id = g_signal_connect_swapped (model, "row-deleted",
G_CALLBACK (model_changed),
&stop);
- reordered_id = g_signal_connect_swapped (model, "rows_reordered",
+ reordered_id = g_signal_connect_swapped (model, "rows-reordered",
G_CALLBACK (model_changed),
&stop);
changed_id = g_signal_connect_swapped (selection->tree_view, "notify::model",
}
}
-static gint
+static gboolean
gtk_tree_selection_real_unselect_all (GtkTreeSelection *selection)
{
struct _TempTuple *tuple;
return FALSE;
}
-
-#define __GTK_TREE_SELECTION_C__
-#include "gtkaliasdef.c"
projects / ~andy / gtk / blobdiff