mirror of
https://gitlab.gnome.org/GNOME/gtk.git
synced 2024-11-05 16:20:10 +00:00
Move documentation to inline comments: GtkListStore
This commit is contained in:
parent
0dd93537b3
commit
c5a760ad2b
1
docs/reference/gtk/tmpl/.gitignore
vendored
1
docs/reference/gtk/tmpl/.gitignore
vendored
@ -63,6 +63,7 @@ gtkinvisible.sgml
|
||||
gtkitemfactory.sgml
|
||||
gtklayout.sgml
|
||||
gtklinkbutton.sgml
|
||||
gtkliststore.sgml
|
||||
gtkmain.sgml
|
||||
gtkmenu.sgml
|
||||
gtkmenubar.sgml
|
||||
|
@ -1,389 +0,0 @@
|
||||
<!-- ##### SECTION Title ##### -->
|
||||
GtkListStore
|
||||
|
||||
<!-- ##### SECTION Short_Description ##### -->
|
||||
A list-like data structure that can be used with the GtkTreeView
|
||||
|
||||
<!-- ##### SECTION Long_Description ##### -->
|
||||
<para>
|
||||
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 <link linkend="gtktreednd">drag and
|
||||
drop</link> interfaces.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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 #GObject<!-- -->s 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
|
||||
#GdkPixbuf<!-- -->s stored.
|
||||
</para>
|
||||
|
||||
<example>
|
||||
<title>Creating a simple list store.</title>
|
||||
<programlisting>
|
||||
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);
|
||||
}
|
||||
</programlisting>
|
||||
</example>
|
||||
|
||||
<refsect2>
|
||||
<title>Performance Considerations</title>
|
||||
<para>
|
||||
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 #GtkTreeIter<!-- -->s 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.
|
||||
</para>
|
||||
<title>Atomic Operations</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2 id="GtkListStore-BUILDER-UI">
|
||||
<title>GtkListStore as GtkBuildable</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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,
|
||||
<emphasis>data</emphasis>, not <emphasis>presentation</emphasis>,
|
||||
and common wisdom is to separate the two, as far as possible.
|
||||
<!-- FIXME a bit inconclusive -->
|
||||
</para>
|
||||
<example>
|
||||
<title>A UI Definition fragment for a list store</title>
|
||||
<programlisting><![CDATA[
|
||||
<object class="GtkListStore">
|
||||
<columns>
|
||||
<column type="gchararray"/>
|
||||
<column type="gchararray"/>
|
||||
<column type="gint"/>
|
||||
</columns>
|
||||
<data>
|
||||
<row>
|
||||
<col id="0">John</col>
|
||||
<col id="1">Doe</col>
|
||||
<col id="2">25</col>
|
||||
</row>
|
||||
<row>
|
||||
<col id="0">Johan</col>
|
||||
<col id="1">Dahlin</col>
|
||||
<col id="2">50</col>
|
||||
</row>
|
||||
</data>
|
||||
</object>
|
||||
]]></programlisting>
|
||||
</example>
|
||||
</refsect2>
|
||||
|
||||
<!-- ##### SECTION See_Also ##### -->
|
||||
<para>
|
||||
#GtkTreeModel, #GtkTreeStore
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION Stability_Level ##### -->
|
||||
|
||||
|
||||
<!-- ##### SECTION Image ##### -->
|
||||
|
||||
|
||||
<!-- ##### STRUCT GtkListStore ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_list_store_new ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@n_columns:
|
||||
@Varargs:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_list_store_newv ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@n_columns:
|
||||
@types:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_list_store_set_column_types ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@list_store:
|
||||
@n_columns:
|
||||
@types:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_list_store_set ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@list_store:
|
||||
@iter:
|
||||
@Varargs:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_list_store_set_valist ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@list_store:
|
||||
@iter:
|
||||
@var_args:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_list_store_set_value ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@list_store:
|
||||
@iter:
|
||||
@column:
|
||||
@value:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_list_store_set_valuesv ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@list_store:
|
||||
@iter:
|
||||
@columns:
|
||||
@values:
|
||||
@n_values:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_list_store_remove ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@list_store:
|
||||
@iter:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_list_store_insert ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@list_store:
|
||||
@iter:
|
||||
@position:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_list_store_insert_before ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@list_store:
|
||||
@iter:
|
||||
@sibling:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_list_store_insert_after ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@list_store:
|
||||
@iter:
|
||||
@sibling:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_list_store_insert_with_values ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@list_store:
|
||||
@iter:
|
||||
@position:
|
||||
@Varargs:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_list_store_insert_with_valuesv ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@list_store:
|
||||
@iter:
|
||||
@position:
|
||||
@columns:
|
||||
@values:
|
||||
@n_values:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_list_store_prepend ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@list_store:
|
||||
@iter:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_list_store_append ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@list_store:
|
||||
@iter:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_list_store_clear ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@list_store:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_list_store_iter_is_valid ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@list_store:
|
||||
@iter:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_list_store_reorder ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@store:
|
||||
@new_order:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_list_store_swap ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@store:
|
||||
@a:
|
||||
@b:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_list_store_move_before ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@store:
|
||||
@iter:
|
||||
@position:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_list_store_move_after ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@store:
|
||||
@iter:
|
||||
@position:
|
||||
|
||||
|
@ -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 <link linkend="gtktreednd">drag and
|
||||
* drop</link> 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 #GObject<!-- -->s 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
|
||||
* #GdkPixbuf<!-- -->s stored.
|
||||
* <para>
|
||||
* <example>
|
||||
* <title>Creating a simple list store.</title>
|
||||
* <programlisting>
|
||||
* 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);
|
||||
* }
|
||||
* </programlisting>
|
||||
* </example>
|
||||
* </para>
|
||||
* <refsect2>
|
||||
* <title>Performance Considerations</title>
|
||||
* 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 #GtkTreeIter<!-- -->s 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.
|
||||
* </refsect2>
|
||||
* <refsect2>
|
||||
* <title>Atomic Operations</title>
|
||||
* 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.
|
||||
* </refsect2>
|
||||
* <refsect2 id="GtkListStore-BUILDER-UI">
|
||||
* <title>GtkListStore as GtkBuildable</title>
|
||||
* <para>
|
||||
* 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,
|
||||
* <emphasis>data</emphasis>, not <emphasis>presentation</emphasis>,
|
||||
* and common wisdom is to separate the two, as far as possible.
|
||||
* <!-- FIXME a bit inconclusive -->
|
||||
*
|
||||
* <example>
|
||||
* <title>A UI Definition fragment for a list store</title>
|
||||
* <programlisting><![CDATA[
|
||||
* <object class="GtkListStore">
|
||||
* <columns>
|
||||
* <column type="gchararray"/>
|
||||
* <column type="gchararray"/>
|
||||
* <column type="gint"/>
|
||||
* </columns>
|
||||
* <data>
|
||||
* <row>
|
||||
* <col id="0">John</col>
|
||||
* <col id="1">Doe</col>
|
||||
* <col id="2">25</col>
|
||||
* </row>
|
||||
* <row>
|
||||
* <col id="0">Johan</col>
|
||||
* <col id="1">Dahlin</col>
|
||||
* <col id="2">50</col>
|
||||
* </row>
|
||||
* </data>
|
||||
* </object>
|
||||
* ]]></programlisting>
|
||||
* </example>
|
||||
* </para>
|
||||
* </refsect2>
|
||||
*/
|
||||
|
||||
|
||||
struct _GtkListStorePrivate
|
||||
{
|
||||
GtkTreeIterCompareFunc default_sort_func;
|
||||
|
Loading…
Reference in New Issue
Block a user