AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2024-11-10 19:00:08 +00:00
Code Issues Projects Releases Wiki Activity

Move documentation to inline comments: GtkListStore

Browse Source
This commit is contained in:
Javier Jardón 2011-04-14 22:25:08 +01:00
parent 0dd93537b3
commit c5a760ad2b
3 changed files with 155 additions and 389 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/gtk/tmpl/.gitignore vendored
View File

@ -63,6 +63,7 @@ gtkinvisible.sgml
gtkitemfactory.sgml
gtklayout.sgml
gtklinkbutton.sgml
gtkliststore.sgml
gtkmain.sgml
gtkmenu.sgml
gtkmenubar.sgml

389
docs/reference/gtk/tmpl/gtkliststore.sgml
View File

@ -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 &lt; 10; i++)
{
gchar *some_data;
some_data = get_some_data (i);
/* Add a new row to the model */
gtk_list_store_append (list_store, &amp;iter);
gtk_list_store_set (list_store, &amp;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),
&amp;iter,
path);
gtk_tree_path_free (path);
gtk_list_store_set (list_store, &amp;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 &lt;columns&gt; element that may
contain multiple &lt;column&gt; 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 &lt;data&gt; element. It can contain
multiple &lt;row&gt; elements, each specifying to content for one
row of the list model. Inside a &lt;row&gt;, the &lt;col&gt; 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:

154
gtk/gtkliststore.c
View File

@ -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 &lt;columns&gt; element that may
* contain multiple &lt;column&gt; 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 &lt;data&gt; element. It can contain
* multiple &lt;row&gt; elements, each specifying to content for one
* row of the list model. Inside a &lt;row&gt;, the &lt;col&gt; 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;