gtk2/docs/reference/gtk/tmpl/gtkliststore.sgml

284 lines
5.0 KiB
Plaintext
Raw Normal View History

<!-- ##### SECTION Title ##### -->
GtkListStore
<!-- ##### SECTION Short_Description ##### -->
A list-like data structure that can be used with the #GtkTreeView
<!-- ##### SECTION Long_Description ##### -->
<para>
start implementing Thu Mar 7 02:58:16 2002 Jonathan Blandford <jrb@redhat.com> * gtk/tmpl/gtkliststore.sgml: start implementing * gtk/question_index.sgml: "I can set with the tree, but not get???!?!" Wed Mar 6 23:20:51 2002 Jonathan Blandford <jrb@redhat.com> and Kristian Rietveld <kris@gtk.org> Finishing touch for 2.0.0 release, fixes #70782, #72729, the 'stealth' bug and other last-minute minor issues. * gtk/gtktreeview.c (gtk_tree_view_bin_expose): set dnd dest line drawing right. We can't draw the line at the position of the next row, because that one still has to be drawn. So draw everthing at a -1 offset. (validate_visible_area): add check for invalid descendants and NULL scroll_to_path path, get scrolling right. Also, fix the area_above value. Pretty amazing I got it wrong. (get_logical_dest_row): add gtk-tree-model-drop-append magic, so dragging a row to the end of the model works right. (gtk_tree_view_get_dest_row_at_pos): minor floating point fix (gtk_tree_view_start_editing): add call to validate_row (gtk_tree_view_tree_to_widget_coords): Never subtract HEADER_HEIGHT from y values anymore!!! (gtk_tree_view_widget_coords_to_tree): ditto. (gtk_tree_view_scroll_to_point): allow -1 as values for the scroll_to coords (gtk_tree_view_move_cursor_page_up_down): Don't need scroll_to_y as clamp_node_visible will make it work. * gtk/gtktreestore.c (gtk_tree_store_drag_data_received): also check path depth, as we can't get iters from empty paths * gtk/gtkliststore.c (gtk_list_store_drag_data_received): handle gtk-tree-model-drop-append * gtk/gtktreednd.c (gtk_tree_set_row_drag_data): free path_str * tests/testtreeflow.c (main): select path where we are scrolling to
2002-03-07 08:03:09 +00:00
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.
start implementing Thu Mar 7 02:58:16 2002 Jonathan Blandford <jrb@redhat.com> * gtk/tmpl/gtkliststore.sgml: start implementing * gtk/question_index.sgml: "I can set with the tree, but not get???!?!" Wed Mar 6 23:20:51 2002 Jonathan Blandford <jrb@redhat.com> and Kristian Rietveld <kris@gtk.org> Finishing touch for 2.0.0 release, fixes #70782, #72729, the 'stealth' bug and other last-minute minor issues. * gtk/gtktreeview.c (gtk_tree_view_bin_expose): set dnd dest line drawing right. We can't draw the line at the position of the next row, because that one still has to be drawn. So draw everthing at a -1 offset. (validate_visible_area): add check for invalid descendants and NULL scroll_to_path path, get scrolling right. Also, fix the area_above value. Pretty amazing I got it wrong. (get_logical_dest_row): add gtk-tree-model-drop-append magic, so dragging a row to the end of the model works right. (gtk_tree_view_get_dest_row_at_pos): minor floating point fix (gtk_tree_view_start_editing): add call to validate_row (gtk_tree_view_tree_to_widget_coords): Never subtract HEADER_HEIGHT from y values anymore!!! (gtk_tree_view_widget_coords_to_tree): ditto. (gtk_tree_view_scroll_to_point): allow -1 as values for the scroll_to coords (gtk_tree_view_move_cursor_page_up_down): Don't need scroll_to_y as clamp_node_visible will make it work. * gtk/gtktreestore.c (gtk_tree_store_drag_data_received): also check path depth, as we can't get iters from empty paths * gtk/gtkliststore.c (gtk_list_store_drag_data_received): handle gtk-tree-model-drop-append * gtk/gtktreednd.c (gtk_tree_set_row_drag_data): free path_str * tests/testtreeflow.c (main): select path where we are scrolling to
2002-03-07 08:03:09 +00:00
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 effects 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 is implemented with a linked list with a
tail pointer. As a result, it is fast at data insertion and deletion,
and not as 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, it is worth keeping the iter around.
</para>
</refsect>
<!-- ##### SECTION See_Also ##### -->
<para>
#GtkTreeModel, #GtkTreeStore
</para>
<!-- ##### 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_remove ##### -->
<para>
</para>
@list_store:
@iter:
@Returns:
<!-- # Unused Parameters # -->
@store:
<!-- ##### FUNCTION gtk_list_store_insert ##### -->
<para>
</para>
@list_store:
@iter:
@position:
<!-- # Unused Parameters # -->
@store:
<!-- ##### FUNCTION gtk_list_store_insert_before ##### -->
<para>
</para>
@list_store:
@iter:
@sibling:
<!-- # Unused Parameters # -->
@store:
<!-- ##### FUNCTION gtk_list_store_insert_after ##### -->
<para>
</para>
@list_store:
@iter:
@sibling:
<!-- # Unused Parameters # -->
@store:
<!-- ##### FUNCTION gtk_list_store_prepend ##### -->
<para>
</para>
@list_store:
@iter:
<!-- # Unused Parameters # -->
@store:
<!-- ##### FUNCTION gtk_list_store_append ##### -->
<para>
</para>
@list_store:
@iter:
<!-- # Unused Parameters # -->
@store:
<!-- ##### 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 ##### -->
<para>
</para>
@store:
@iter:
@position: