From 5efde9d6d034e73d08ea19c3b795ff87a1d0c1ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Javier=20Jard=C3=B3n?= Date: Sat, 6 Nov 2010 03:04:27 +0100 Subject: [PATCH] docs: move documentation to inline comments: GtkTreeView --- docs/reference/gtk/tmpl/.gitignore | 1 + docs/reference/gtk/tmpl/gtktreeview.sgml | 1456 ---------------------- gtk/gtkenums.h | 9 + gtk/gtktreeview.c | 84 ++ gtk/gtktreeview.h | 70 +- 5 files changed, 162 insertions(+), 1458 deletions(-) delete mode 100644 docs/reference/gtk/tmpl/gtktreeview.sgml diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore index 4c4c615f90..83501438ff 100644 --- a/docs/reference/gtk/tmpl/.gitignore +++ b/docs/reference/gtk/tmpl/.gitignore @@ -58,6 +58,7 @@ gtktreemodelfilter.sgml gtktreeselection.sgml gtktreesortable.sgml gtktreestore.sgml +gtktreeview.sgml gtktreeviewcolumn.sgml gtktypeutils.sgml gtkwindow.sgml diff --git a/docs/reference/gtk/tmpl/gtktreeview.sgml b/docs/reference/gtk/tmpl/gtktreeview.sgml deleted file mode 100644 index dcd40dbd20..0000000000 --- a/docs/reference/gtk/tmpl/gtktreeview.sgml +++ /dev/null @@ -1,1456 +0,0 @@ - -GtkTreeView - - -A widget for displaying both trees and lists - - - -Widget that displays any object that implements the GtkTreeModel interface. - - - -Please refer to the tree widget conceptual -overview for an overview of all the objects and data types related -to the tree widget and how they work together. - - - -Several different coordinate systems are exposed in the GtkTreeView API. -These are: - - - - - Widget coordinates -- coordinates relative to the widget - (usually widget->window. - Bin window coordinates -- coordinates relative to the window - that GtkTreeView renders to. - Tree coordinates -- coordinates relative to the entire scrollable - area of GtkTreeView. These coordinates start at (0, 0) for row 0 of the - tree. - - - - -Several functions are available for converting between the different -coordinate systems. The most common translations are between widget and bin -window coordinates and between bin window and tree coordinates. For the -former you can use gtk_tree_view_convert_widget_to_bin_window_coords() -(and vice versa), for the latter gtk_tree_view_convert_bin_window_to_tree_coords() -(and vice versa). - - - -GtkTreeView as GtkBuildable - -The GtkTreeView implementation of the GtkBuildable interface accepts -GtkTreeViewColumn objects as <child> elements and exposes the -internal GtkTreeSelection in UI definitions. - - -A UI definition fragment with GtkTreeView - - liststore1 - - - Test - - - - 1 - - - - - - - - - - -]]> - - - - - -#GtkTreeViewColumn, #GtkTreeSelection, #GtkTreeDnd, #GtkTreeMode, #GtkTreeSortable, #GtkTreeModelSort, #GtkListStore, #GtkTreeStore, #GtkCellRenderer, #GtkCellEditable, #GtkCellRendererPixbuf, #GtkCellRendererText, #GtkCellRendererToggle - - - - - - - - - - - - - - - - - - - -@tree_view: the object which received the signal. - - - - - - -@tree_view: the object which received the signal. - - - - - - -@tree_view: the object which received the signal. -@arg1: -@arg2: -@arg3: -@Returns: - - - - - - -@tree_view: the object which received the signal. -@arg1: -@arg2: -@Returns: - - - - - - -@tree_view: the object which received the signal. -@arg1: -@arg2: - - - - - - -@tree_view: the object which received the signal. -@arg1: -@arg2: - - - - - - -@tree_view: the object which received the signal. -@arg1: -@arg2: - - - - - - -@tree_view: the object which received the signal. -@Returns: - - - - - - -@tree_view: the object which received the signal. -@Returns: - - - - - - -@tree_view: the object which received the signal. -@arg1: -@Returns: - - - - - - -@tree_view: the object which received the signal. -@arg1: -@arg2: - - - - - - -@tree_view: the object which received the signal. -@Returns: - - - - - - -@tree_view: the object which received the signal. -@arg1: -@arg2: -@Returns: - - - - - - -@tree_view: the object which received the signal. -@arg1: -@arg2: -@Returns: - - - - - - -@tree_view: the object which received the signal. -@Returns: - - - - - - -@tree_view: the object which received the signal. -@Returns: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -An enum for determining where a dropped row goes. - - -@GTK_TREE_VIEW_DROP_BEFORE: dropped row is inserted before -@GTK_TREE_VIEW_DROP_AFTER: dropped row is inserted after -@GTK_TREE_VIEW_DROP_INTO_OR_BEFORE: dropped row becomes a child or is inserted before -@GTK_TREE_VIEW_DROP_INTO_OR_AFTER: dropped row becomes a child or is inserted after - - - -A private struct for internal use only. The definition of this -structure is not publically available. - - - - - -Function type for determining whether @column can be dropped in a -particular spot (as determined by @prev_column and @next_column). In -left to right locales, @prev_column is on the left of the potential drop -spot, and @next_column is on the right. In right to left mode, this is -reversed. This function should return %TRUE if the spot is a valid drop -spot. Please note that returning %TRUE does not actually indicate that -the column drop was made, but is meant only to indicate a possible drop -spot to the user. - - -@tree_view: A #GtkTreeView -@column: The #GtkTreeViewColumn being dragged -@prev_column: A #GtkTreeViewColumn on one side of @column -@next_column: A #GtkTreeViewColumn on the other side of @column -@data: user data -@Returns: %TRUE, if #column can be dropped in this spot - - - - -Function used for #gtk_tree_view_map_expanded_rows. - - -@tree_view: A #GtkTreeView -@path: The path that's expanded -@user_data: user data - - - - -A function used for checking whether a row in @model matches -a search key string entered by the user. Note the return value -is reversed from what you would normally expect, though it -has some similarity to strcmp() returning 0 for equal strings. - - -@model: the #GtkTreeModel being searched -@column: the search column set by gtk_tree_view_set_search_column() -@key: the key string to compare with -@iter: a #GtkTreeIter pointing the row of @model that should be compared - with @key. -@search_data: user data from gtk_tree_view_set_search_equal_func() -@Returns: %FALSE if the row matches, %TRUE otherwise. - - - - - - - -@void: -@Returns: - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@indentation: - - - - - - - -@tree_view: -@enabled: - - - - - - - -@model: -@Returns: - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@model: - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@adjustment: - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@adjustment: - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@headers_visible: - - - - - - - -@tree_view: - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@setting: - - - - - - - -@tree_view: -@setting: - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@column: -@Returns: - - - - - - - -@tree_view: -@column: -@Returns: - - - - - - - -@tree_view: -@column: -@position: -@Returns: - - - - - - - -@tree_view: -@position: -@title: -@cell: -@Varargs: -@Returns: - - - - - - - -@tree_view: -@position: -@title: -@cell: -@func: -@data: -@dnotify: -@Returns: - - - - - - - -@tree_view: -@n: -@Returns: - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@column: -@base_column: - - - - - - - -@tree_view: -@column: - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@func: -@user_data: -@destroy: - - - - - - - -@tree_view: -@tree_x: -@tree_y: - - - - - - - -@tree_view: -@path: -@column: -@use_align: -@row_align: -@col_align: - - - - - - - -@tree_view: -@path: -@focus_column: -@start_editing: - - - - - - - -@tree_view: -@path: -@focus_column: -@focus_cell: -@start_editing: - - - - - - - -@tree_view: -@path: -@focus_column: - - - - - - - -@tree_view: -@path: -@column: - - - - - - - -@tree_view: - - - - - - - -@tree_view: - - - - - - - -@tree_view: -@path: - - - - - - - -@tree_view: -@path: -@open_all: -@Returns: - - - - - - - -@tree_view: -@path: -@Returns: - - - - - - - -@tree_view: -@func: -@data: - - - - - - - -@tree_view: -@path: -@Returns: - - - - - - - -@tree_view: -@reorderable: - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@x: -@y: -@path: -@column: -@cell_x: -@cell_y: -@Returns: - - - - - - - -@tree_view: -@path: -@column: -@rect: - - - - - - - -@tree_view: -@path: -@column: -@rect: - - - - - - - -@tree_view: -@visible_rect: - - - - - - - -@tree_view: -@start_path: -@end_path: -@Returns: - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@bx: -@by: -@tx: -@ty: - - - - - - - -@tree_view: -@bx: -@by: -@wx: -@wy: - - - - - - - -@tree_view: -@tx: -@ty: -@bx: -@by: - - - - - - - -@tree_view: -@tx: -@ty: -@wx: -@wy: - - - - - - - -@tree_view: -@wx: -@wy: -@bx: -@by: - - - - - - - -@tree_view: -@wx: -@wy: -@tx: -@ty: - - - - - - - -@tree_view: -@targets: -@n_targets: -@actions: - - - - - - - -@tree_view: -@start_button_mask: -@targets: -@n_targets: -@actions: - - - - - - - -@tree_view: - - - - - - - -@tree_view: - - - - - - - -@tree_view: -@path: -@pos: - - - - - - - -@tree_view: -@path: -@pos: - - - - - - - -@tree_view: -@drag_x: -@drag_y: -@path: -@pos: -@Returns: - - - - - - - -@tree_view: -@path: -@Returns: - - - - - - - -@tree_view: -@enable_search: - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@column: - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@search_equal_func: -@search_user_data: -@search_destroy: - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@entry: - - - - - - - -@tree_view: -@search_dialog: -@user_data: - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@func: -@data: -@destroy: - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@enable: - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@hover: - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@expand: - - - - - - - -@tree_view: -@path: -@children: -@user_data: - - - - - - - -@tree_view: -@func: -@data: -@destroy: - - - - -Function type for determining whether the row pointed to by @iter should -be rendered as a separator. A common way to implement this is to have a -boolean column in the model, whose values the #GtkTreeViewRowSeparatorFunc -returns. - - -@model: the #GtkTreeModel -@iter: a #GtkTreeIter pointing at a row in @model -@data: user data -@Returns: %TRUE if the row is a separator - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@func: -@data: -@destroy: - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@enable: - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@enabled: - - - - -Used to indicate which grid lines to draw in a tree view. - - -@GTK_TREE_VIEW_GRID_LINES_NONE: No grid lines. -@GTK_TREE_VIEW_GRID_LINES_HORIZONTAL: Horizontal grid lines. -@GTK_TREE_VIEW_GRID_LINES_VERTICAL: Vertical grid lines. -@GTK_TREE_VIEW_GRID_LINES_BOTH: Horizontal and vertical grid lines. - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@grid_lines: - - - - - - - -@tree_view: -@tooltip: -@path: - - - - - - - -@tree_view: -@tooltip: -@path: -@column: -@cell: - - - - - - - -@tree_view: -@x: -@y: -@keyboard_tip: -@model: -@path: -@iter: -@Returns: - - - - - - - -@tree_view: -@Returns: - - - - - - - -@tree_view: -@column: - - diff --git a/gtk/gtkenums.h b/gtk/gtkenums.h index 6075c266f0..73e1dce721 100644 --- a/gtk/gtkenums.h +++ b/gtk/gtkenums.h @@ -509,6 +509,15 @@ typedef enum GTK_UNIT_MM } GtkUnit; +/** + * GtkTreeViewGridLines: + * @GTK_TREE_VIEW_GRID_LINES_NONE: No grid lines. + * @GTK_TREE_VIEW_GRID_LINES_HORIZONTAL: Horizontal grid lines. + * @GTK_TREE_VIEW_GRID_LINES_VERTICAL: Vertical grid lines. + * @GTK_TREE_VIEW_GRID_LINES_BOTH: Horizontal and vertical grid lines. + * + * Used to indicate which grid lines to draw in a tree view. + */ typedef enum { GTK_TREE_VIEW_GRID_LINES_NONE, diff --git a/gtk/gtktreeview.c b/gtk/gtktreeview.c index 7e50804e5c..efa9734cec 100644 --- a/gtk/gtktreeview.c +++ b/gtk/gtktreeview.c @@ -48,6 +48,90 @@ #include "gtkprivate.h" #include "gtkwidgetprivate.h" + +/** + * SECTION:gtktreeview + * @Short_description: A widget for displaying both trees and lists + * @Title: GtkTreeView + * @See_also: #GtkTreeViewColumn, #GtkTreeSelection, #GtkTreeDnd, #GtkTreeMode, + * #GtkTreeSortable, #GtkTreeModelSort, #GtkListStore, #GtkTreeStore, + * #GtkCellRenderer, #GtkCellEditable, #GtkCellRendererPixbuf, + * #GtkCellRendererText, #GtkCellRendererToggle + * + * Widget that displays any object that implements the #GtkTreeModel interface. + * + * Please refer to the tree widget conceptual + * overview for an overview of all the objects and data types related + * to the tree widget and how they work together. + * + * Several different coordinate systems are exposed in the GtkTreeView API. + * These are: + * + * + * Coordinate systems in GtkTreeView API + * Widget coordinates + * + * + * Coordinates relative to the widget (usually widget->window). + * + * + * + * Bin window coordinates + * + * + * Coordinates relative to the window that GtkTreeView renders to. + * + * + * + * Tree coordinates + * + * + * Coordinates relative to the entire scrollable area of GtkTreeView. These + * coordinates start at (0, 0) for row 0 of the tree. + * + * + * + * + * + * Several functions are available for converting between the different + * coordinate systems. The most common translations are between widget and bin + * window coordinates and between bin window and tree coordinates. For the + * former you can use gtk_tree_view_convert_widget_to_bin_window_coords() + * (and vice versa), for the latter gtk_tree_view_convert_bin_window_to_tree_coords() + * (and vice versa). + * + * GtkTreeView as GtkBuildable + * The GtkTreeView implementation of the GtkBuildable interface accepts + * #GtkTreeViewColumn objects as <child> elements and exposes the + * internal #GtkTreeSelection in UI definitions. + * + * A UI definition fragment with GtkTreeView + * + * liststore1 + * + * + * Test + * + * + * + * 1 + * + * + * + * + * + * + * + * + * + * + * ]]> + * + * + */ + + #define GTK_TREE_VIEW_PRIORITY_VALIDATE (GDK_PRIORITY_REDRAW + 5) #define GTK_TREE_VIEW_PRIORITY_SCROLL_SYNC (GTK_TREE_VIEW_PRIORITY_VALIDATE + 2) #define GTK_TREE_VIEW_TIME_MS_PER_IDLE 30 diff --git a/gtk/gtktreeview.h b/gtk/gtktreeview.h index 4c609d9d42..a828a40c1c 100644 --- a/gtk/gtktreeview.h +++ b/gtk/gtktreeview.h @@ -32,7 +32,15 @@ G_BEGIN_DECLS - +/** + * GtkTreeViewDropPosition: + * @GTK_TREE_VIEW_DROP_BEFORE: dropped row is inserted before + * @GTK_TREE_VIEW_DROP_AFTER: dropped row is inserted after + * @GTK_TREE_VIEW_DROP_INTO_OR_BEFORE: dropped row becomes a child or is inserted before + * @GTK_TREE_VIEW_DROP_INTO_OR_AFTER: dropped row becomes a child or is inserted after + * + * An enum for determining where a dropped row goes. + */ typedef enum { /* drop before/after this row */ @@ -115,20 +123,78 @@ struct _GtkTreeViewClass void (*_gtk_reserved8) (void); }; - +/** + * GtkTreeViewColumnDropFunc: + * @tree_view: A #GtkTreeView + * @column: The #GtkTreeViewColumn being dragged + * @prev_column: A #GtkTreeViewColumn on one side of @column + * @next_column: A #GtkTreeViewColumn on the other side of @column + * @data: user data + * + * Function type for determining whether @column can be dropped in a + * particular spot (as determined by @prev_column and @next_column). In + * left to right locales, @prev_column is on the left of the potential drop + * spot, and @next_column is on the right. In right to left mode, this is + * reversed. This function should return %TRUE if the spot is a valid drop + * spot. Please note that returning %TRUE does not actually indicate that + * the column drop was made, but is meant only to indicate a possible drop + * spot to the user. + * + * Returns: %TRUE, if @column can be dropped in this spot + */ typedef gboolean (* GtkTreeViewColumnDropFunc) (GtkTreeView *tree_view, GtkTreeViewColumn *column, GtkTreeViewColumn *prev_column, GtkTreeViewColumn *next_column, gpointer data); + +/** + * GtkTreeViewMappingFunc: + * @tree_view: A #GtkTreeView + * @path: The path that's expanded + * @user_data: user data + * + * Function used for gtk_tree_view_map_expanded_rows(). + */ typedef void (* GtkTreeViewMappingFunc) (GtkTreeView *tree_view, GtkTreePath *path, gpointer user_data); + +/** + * GtkTreeViewSearchEqualFunc: + * @model: the #GtkTreeModel being searched + * @column: the search column set by gtk_tree_view_set_search_column() + * @key: the key string to compare with + * @iter: a #GtkTreeIter pointing the row of @model that should be compared + * with @key. + * @search_data: user data from gtk_tree_view_set_search_equal_func() + * + * A function used for checking whether a row in @model matches + * a search key string entered by the user. Note the return value + * is reversed from what you would normally expect, though it + * has some similarity to strcmp() returning 0 for equal strings. + * + * Returns: %FALSE if the row matches, %TRUE otherwise. + */ typedef gboolean (*GtkTreeViewSearchEqualFunc) (GtkTreeModel *model, gint column, const gchar *key, GtkTreeIter *iter, gpointer search_data); + +/** + * GtkTreeViewRowSeparatorFunc: + * @model: the #GtkTreeModel + * @iter: a #GtkTreeIter pointing at a row in @model + * @data: user data + * + * Function type for determining whether the row pointed to by @iter should + * be rendered as a separator. A common way to implement this is to have a + * boolean column in the model, whose values the #GtkTreeViewRowSeparatorFunc + * returns. + * + * Returns: %TRUE if the row is a separator + */ typedef gboolean (*GtkTreeViewRowSeparatorFunc) (GtkTreeModel *model, GtkTreeIter *iter, gpointer data);