diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore index 8c5ba90135..5417f735f0 100644 --- a/docs/reference/gtk/tmpl/.gitignore +++ b/docs/reference/gtk/tmpl/.gitignore @@ -63,6 +63,7 @@ gtkinvisible.sgml gtkitemfactory.sgml gtklayout.sgml gtklinkbutton.sgml +gtkliststore.sgml gtkmain.sgml gtkmenu.sgml gtkmenubar.sgml diff --git a/docs/reference/gtk/tmpl/gtkliststore.sgml b/docs/reference/gtk/tmpl/gtkliststore.sgml deleted file mode 100644 index 24f3a1c8b5..0000000000 --- a/docs/reference/gtk/tmpl/gtkliststore.sgml +++ /dev/null @@ -1,389 +0,0 @@ - -GtkListStore - - -A list-like data structure that can be used with the GtkTreeView - - - -The #GtkListStore object is a list model for use with a #GtkTreeView -widget. It implements the #GtkTreeModel interface, and consequentialy, -can use all of the methods available there. It also implements the -#GtkTreeSortable interface so it can be sorted by the view. -Finally, it also implements the tree drag and -drop interfaces. - - - -The #GtkListStore can accept most GObject types as a column type, though -it can't accept all custom types. Internally, it will keep a copy of -data passed in (such as a string or a boxed pointer). Columns that -accept #GObjects are handled a little differently. The -#GtkListStore will keep a reference to the object instead of copying the -value. As a result, if the object is modified, it is up to the -application writer to call @gtk_tree_model_row_changed to emit the -"row_changed" signal. This most commonly affects lists with -#GdkPixbufs stored. - - - -Creating a simple list store. - -enum { - COLUMN_STRING, - COLUMN_INT, - COLUMN_BOOLEAN, - N_COLUMNS -}; - -{ - GtkListStore *list_store; - GtkTreePath *path; - GtkTreeIter iter; - gint i; - - list_store = gtk_list_store_new (N_COLUMNS, - G_TYPE_STRING, - G_TYPE_INT, - G_TYPE_BOOLEAN); - - for (i = 0; i < 10; i++) - { - gchar *some_data; - - some_data = get_some_data (i); - - /* Add a new row to the model */ - gtk_list_store_append (list_store, &iter); - gtk_list_store_set (list_store, &iter, - COLUMN_STRING, some_data, - COLUMN_INT, i, - COLUMN_BOOLEAN, FALSE, - -1); - - /* As the store will keep a copy of the string internally, we - * free some_data. - */ - g_free (some_data); - } - - /* Modify a particular row */ - path = gtk_tree_path_new_from_string ("4"); - gtk_tree_model_get_iter (GTK_TREE_MODEL (list_store), - &iter, - path); - gtk_tree_path_free (path); - gtk_list_store_set (list_store, &iter, - COLUMN_BOOLEAN, TRUE, - -1); -} - - - - -Performance Considerations - -Internally, the #GtkListStore was implemented with a linked list with a -tail pointer prior to GTK+ 2.6. As a result, it was fast at data -insertion and deletion, and not fast at random data access. The -#GtkListStore sets the #GTK_TREE_MODEL_ITERS_PERSIST flag, which means -that #GtkTreeIters can be cached while the row exists. Thus, if -access to a particular row is needed often and your code is expected to -run on older versions of GTK+, it is worth keeping the iter around. - -Atomic Operations - -It is important to note that only the methods -gtk_list_store_insert_with_values() and gtk_list_store_insert_with_valuesv() -are atomic, in the sense that the row is being appended to the store and the -values filled in in a single operation with regard to #GtkTreeModel signaling. -In contrast, using e.g. gtk_list_store_append() and then gtk_list_store_set() -will first create a row, which triggers the #GtkTreeModel::row-inserted signal -on #GtkListStore. The row, however, is still empty, and any signal handler -connecting to "row-inserted" on this particular store should be prepared -for the situation that the row might be empty. This is especially important -if you are wrapping the #GtkListStore inside a #GtkTreeModelFilter and are -using a #GtkTreeModelFilterVisibleFunc. Using any of the non-atomic operations -to append rows to the #GtkListStore will cause the -#GtkTreeModelFilterVisibleFunc to be visited with an empty row first; the -function must be prepared for that. - - - -GtkListStore as GtkBuildable - -The GtkListStore implementation of the GtkBuildable interface allows -to specify the model columns with a <columns> element that may -contain multiple <column> elements, each specifying one model -column. The "type" attribute specifies the data type for the column. - - -Additionally, it is possible to specify content for the list store -in the UI definition, with the <data> element. It can contain -multiple <row> elements, each specifying to content for one -row of the list model. Inside a <row>, the <col> elements -specify the content for individual cells. - - -Note that it is probably more common to define your models -in the code, and one might consider it a layering violation -to specify the content of a list store in a UI definition, -data, not presentation, -and common wisdom is to separate the two, as far as possible. - - - -A UI Definition fragment for a list store - - - - - - - - - John - Doe - 25 - - - Johan - Dahlin - 50 - - - -]]> - - - - - -#GtkTreeModel, #GtkTreeStore - - - - - - - - - - - - - - - - - - - -@n_columns: -@Varargs: -@Returns: - - - - - - - -@n_columns: -@types: -@Returns: - - - - - - - -@list_store: -@n_columns: -@types: - - - - - - - -@list_store: -@iter: -@Varargs: - - - - - - - -@list_store: -@iter: -@var_args: - - - - - - - -@list_store: -@iter: -@column: -@value: - - - - - - - -@list_store: -@iter: -@columns: -@values: -@n_values: - - - - - - - -@list_store: -@iter: -@Returns: - - - - - - - -@list_store: -@iter: -@position: - - - - - - - -@list_store: -@iter: -@sibling: - - - - - - - -@list_store: -@iter: -@sibling: - - - - - - - -@list_store: -@iter: -@position: -@Varargs: - - - - - - - -@list_store: -@iter: -@position: -@columns: -@values: -@n_values: - - - - - - - -@list_store: -@iter: - - - - - - - -@list_store: -@iter: - - - - - - - -@list_store: - - - - - - - -@list_store: -@iter: -@Returns: - - - - - - - -@store: -@new_order: - - - - - - - -@store: -@a: -@b: - - - - - - - -@store: -@iter: -@position: - - - - - - - -@store: -@iter: -@position: - - diff --git a/gtk/gtkliststore.c b/gtk/gtkliststore.c index 93fbc9f8de..aabd3ec0fa 100644 --- a/gtk/gtkliststore.c +++ b/gtk/gtkliststore.c @@ -31,6 +31,160 @@ #include "gtkbuilderprivate.h" +/** + * SECTION:gtkliststore + * @Short_description: A list-like data structure that can be used with the GtkTreeView + * @Title: GtkListStore + * @See_also:#GtkTreeModel, #GtkTreeStore + * + * The #GtkListStore object is a list model for use with a #GtkTreeView + * widget. It implements the #GtkTreeModel interface, and consequentialy, + * can use all of the methods available there. It also implements the + * #GtkTreeSortable interface so it can be sorted by the view. + * Finally, it also implements the tree drag and + * drop interfaces. + * + * The #GtkListStore can accept most GObject types as a column type, though + * it can't accept all custom types. Internally, it will keep a copy of + * data passed in (such as a string or a boxed pointer). Columns that + * accept #GObjects are handled a little differently. The + * #GtkListStore will keep a reference to the object instead of copying the + * value. As a result, if the object is modified, it is up to the + * application writer to call gtk_tree_model_row_changed() to emit the + * #GtkTreeModel::row_changed signal. This most commonly affects lists with + * #GdkPixbufs stored. + * + * + * Creating a simple list store. + * + * enum { + * COLUMN_STRING, + * COLUMN_INT, + * COLUMN_BOOLEAN, + * N_COLUMNS + * }; + * + * { + * GtkListStore *list_store; + * GtkTreePath *path; + * GtkTreeIter iter; + * gint i; + * + * list_store = gtk_list_store_new (N_COLUMNS, + * G_TYPE_STRING, + * G_TYPE_INT, + * G_TYPE_BOOLEAN); + * + * for (i = 0; i < 10; i++) + * { + * gchar *some_data; + * + * some_data = get_some_data (i); + * + * // Add a new row to the model + * gtk_list_store_append (list_store, &iter); + * gtk_list_store_set (list_store, &iter, + * COLUMN_STRING, some_data, + * COLUMN_INT, i, + * COLUMN_BOOLEAN, FALSE, + * -1); + * + * /* As the store will keep a copy of the string internally, we + * * free some_data. + * */ + * g_free (some_data); + * } + * + * // Modify a particular row + * path = gtk_tree_path_new_from_string ("4"); + * gtk_tree_model_get_iter (GTK_TREE_MODEL (list_store), + * &iter, + * path); + * gtk_tree_path_free (path); + * gtk_list_store_set (list_store, &iter, + * COLUMN_BOOLEAN, TRUE, + * -1); + * } + * + * + * + * + * Performance Considerations + * Internally, the #GtkListStore was implemented with a linked list with a + * tail pointer prior to GTK+ 2.6. As a result, it was fast at data + * insertion and deletion, and not fast at random data access. The + * #GtkListStore sets the #GTK_TREE_MODEL_ITERS_PERSIST flag, which means + * that #GtkTreeIters can be cached while the row exists. Thus, if + * access to a particular row is needed often and your code is expected to + * run on older versions of GTK+, it is worth keeping the iter around. + * + * + * Atomic Operations + * It is important to note that only the methods + * gtk_list_store_insert_with_values() and gtk_list_store_insert_with_valuesv() + * are atomic, in the sense that the row is being appended to the store and the + * values filled in in a single operation with regard to #GtkTreeModel signaling. + * In contrast, using e.g. gtk_list_store_append() and then gtk_list_store_set() + * will first create a row, which triggers the #GtkTreeModel::row-inserted signal + * on #GtkListStore. The row, however, is still empty, and any signal handler + * connecting to #GtkTreeModel::row-inserted on this particular store should be prepared + * for the situation that the row might be empty. This is especially important + * if you are wrapping the #GtkListStore inside a #GtkTreeModelFilter and are + * using a #GtkTreeModelFilterVisibleFunc. Using any of the non-atomic operations + * to append rows to the #GtkListStore will cause the + * #GtkTreeModelFilterVisibleFunc to be visited with an empty row first; the + * function must be prepared for that. + * + * + * GtkListStore as GtkBuildable + * + * The GtkListStore implementation of the GtkBuildable interface allows + * to specify the model columns with a <columns> element that may + * contain multiple <column> elements, each specifying one model + * column. The "type" attribute specifies the data type for the column. + * + * Additionally, it is possible to specify content for the list store + * in the UI definition, with the <data> element. It can contain + * multiple <row> elements, each specifying to content for one + * row of the list model. Inside a <row>, the <col> elements + * specify the content for individual cells. + * + * Note that it is probably more common to define your models + * in the code, and one might consider it a layering violation + * to specify the content of a list store in a UI definition, + * data, not presentation, + * and common wisdom is to separate the two, as far as possible. + * + * + * + * A UI Definition fragment for a list store + * + * + * + * + * + * + * + * + * John + * Doe + * 25 + * + * + * Johan + * Dahlin + * 50 + * + * + * + * ]]> + * + * + * + */ + + struct _GtkListStorePrivate { GtkTreeIterCompareFunc default_sort_func;