From 8d3b36d534b6b60031166cbfe3aa15dfdd23e1e9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Javier=20Jard=C3=B3n?= Date: Fri, 22 Oct 2010 22:24:36 +0200 Subject: [PATCH] gtktreeselection: Move documentation to inline comments --- docs/reference/gtk/tmpl/.gitignore | 1 + docs/reference/gtk/tmpl/gtktreeselection.sgml | 280 ------------------ gtk/gtktreeselection.c | 44 +++ gtk/gtktreeselection.h | 26 ++ 4 files changed, 71 insertions(+), 280 deletions(-) delete mode 100644 docs/reference/gtk/tmpl/gtktreeselection.sgml diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore index 40585283d5..27b8d692bf 100644 --- a/docs/reference/gtk/tmpl/.gitignore +++ b/docs/reference/gtk/tmpl/.gitignore @@ -50,6 +50,7 @@ gtktoolbar.sgml gtktoolitem.sgml gtktooltip.sgml gtktreednd.sgml +gtktreeselection.sgml gtktreesortable.sgml gtktreestore.sgml gtktreeviewcolumn.sgml diff --git a/docs/reference/gtk/tmpl/gtktreeselection.sgml b/docs/reference/gtk/tmpl/gtktreeselection.sgml deleted file mode 100644 index 9407aaa11e..0000000000 --- a/docs/reference/gtk/tmpl/gtktreeselection.sgml +++ /dev/null @@ -1,280 +0,0 @@ - -GtkTreeSelection - - -The selection object for GtkTreeView - - - -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 ::changed signal when nothing has happened -(mostly as a result of programmers calling select_row on an already -selected row). - - - - -#GtkTreeView, #GtkTreeViewColumn, #GtkTreeDnd, #GtkTreeMode, #GtkTreeSortable, #GtkTreeModelSort, #GtkListStore, #GtkTreeStore, #GtkCellRenderer, #GtkCellEditable, #GtkCellRendererPixbuf, #GtkCellRendererText, #GtkCellRendererToggle - - - - - - - - - - - - - - - - -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. - - -@treeselection: the object which received the signal. - - - -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. - - -@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 - - - - -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. - - -@model: The #GtkTreeModel being viewed -@path: The #GtkTreePath of a selected row -@iter: A #GtkTreeIter pointing to a selected row -@data: user data - - - - - - - -@selection: -@type: - - - - - - - -@selection: -@Returns: - - - - - - - -@selection: -@func: -@data: -@destroy: - - - - - - - -@selection: -@Returns: - - - - - - - -@selection: -@Returns: - - - - - - - -@selection: -@Returns: - - - - - - - -@selection: -@model: -@iter: -@Returns: - - - - - - - -@selection: -@func: -@data: - - - - - - - -@selection: -@model: -@Returns: - - - - - - - -@selection: -@Returns: - - - - - - - -@selection: -@path: - - - - - - - -@selection: -@path: - - - - - - - -@selection: -@path: -@Returns: - - - - - - - -@selection: -@iter: - - - - - - - -@selection: -@iter: - - - - - - - -@selection: -@iter: -@Returns: - - - - - - - -@selection: - - - - - - - -@selection: - - - - - - - -@selection: -@start_path: -@end_path: - - - - - - - -@selection: -@start_path: -@end_path: - - diff --git a/gtk/gtktreeselection.c b/gtk/gtktreeselection.c index 000f71ea22..5ae0866146 100644 --- a/gtk/gtktreeselection.c +++ b/gtk/gtktreeselection.c @@ -26,6 +26,41 @@ #include "gtkintl.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); static gint gtk_tree_selection_real_unselect_all (GtkTreeSelection *selection); @@ -54,6 +89,15 @@ gtk_tree_selection_class_init (GtkTreeSelectionClass *class) 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), diff --git a/gtk/gtktreeselection.h b/gtk/gtktreeselection.h index 267a2af37e..38a1f702e3 100644 --- a/gtk/gtktreeselection.h +++ b/gtk/gtktreeselection.h @@ -36,11 +36,37 @@ G_BEGIN_DECLS #define GTK_IS_TREE_SELECTION_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GTK_TYPE_TREE_SELECTION)) #define GTK_TREE_SELECTION_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GTK_TYPE_TREE_SELECTION, GtkTreeSelectionClass)) +/** + * GtkTreeSelectionFunc: + * @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 + * + * 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. + * + * Returns: %TRUE, if the selection state of the row can be toggled + */ typedef gboolean (* GtkTreeSelectionFunc) (GtkTreeSelection *selection, GtkTreeModel *model, GtkTreePath *path, gboolean path_currently_selected, gpointer data); + +/** + * GtkTreeSelectionForeachFunc: + * @model: The #GtkTreeModel being viewed + * @path: The #GtkTreePath of a selected row + * @iter: A #GtkTreeIter pointing to a selected row + * @data: user data + * + * 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. + */ typedef void (* GtkTreeSelectionForeachFunc) (GtkTreeModel *model, GtkTreePath *path, GtkTreeIter *iter,