1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153
|
<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
]>
<chapter id="gtk-migrating-GtkIconView">
<title>Migrating from GnomeIconList to GtkIconView</title>
<para>
Since version 2.6, GTK+ provides the #GtkIconView widget. It is similar in
functionality to the <structname>GnomeIconList</structname> widget in the
libgnomeui library, both widgets provide a way to lay out named icons in
a grid. The distinctive feature of the GTK+ widget is that it follows the
model-view pattern, allowing it to share the actual data (i.e. the names
and images of the icons) with other views.
</para>
<para>
#GtkIconView currently doesn't support some features found in
<structname>GnomeIconList</structname>. Icons can not be positioned freely,
the spacing is not customizable, and it is not possible to edit the names of
icons.
</para>
<para>
To convert an application that uses <structname>GnomeIconList</structname>
to #GtkIconView, the first step is to organize your data in a #GtkTreeModel.
<structname>GnomeIconList</structname> lets you directly insert data with
gnome_icon_list_insert() and gnome_icon_list_insert_pixbuf() and their
append variants. So, if you previously had a function to fill your icon
list similar to this one:
<informalexample><programlisting>
void
fill_icon_list (GnomeIconList *icon_list)
{
gnome_icon_list_append (icon_list, "file1.png", "Icon 1");
gnome_icon_list_append (icon_list, "file2.png", "Icon 2");
/* more icons ... */
}
</programlisting></informalexample>
you will have to create a tree model, attach your icon view to it, and
fill the model:
<informalexample><programlisting>
enum {
PIXBUF_COLUMN,
TEXT_COLUMN,
/* you can have more columns here, e.g */
DATA_COLUMN
};
void
fill_model (GtkListStore *store)
{
GtkTreeIter iter;
GdkPixbuf *pixbuf;
gtk_list_store_append (store, &iter);
pixbuf = gdk_pixbuf_new_from_file ("file1.png", NULL);
gtk_list_store_set (store, &iter, PIXBUF_COLUMN, pixbuf, TEXT_COLUMN, "Icon 1", -1);
g_object_unref (pixbuf);
gtk_list_store_append (store, &iter);
pixbuf = gdk_pixbuf_new_from_file ("file2.png", NULL);
gtk_list_store_set (store, &iter, PIXBUF_COLUMN, pixbuf, TEXT_COLUMN, "Icon 2", -1);
g_object_unref (pixbuf);
/* more icons ... */
}
int
main (int argc, char *argv[])
{
GtkWidget *icon_view;
GtkListStore *store;
gtk_init (&argc, &argv);
/* do other initialization... */
/* construct the GtkIconView */
icon_view = gtk_icon_view_new (<!-- -->);
store = gtk_list_store_new (3, GDK_TYPE_PIXBUF, G_TYPE_STRING, G_TYPE_POINTER);
gtk_icon_view_set_pixbuf_column (GTK_ICON_VIEW (icon_view), PIXBUF_COLUMN);
gtk_icon_view_set_text_column (GTK_ICON_VIEW (icon_view), TEXT_COLUMN);
gtk_icon_view_set_model (GTK_ICON_VIEW (icon_view), GTK_TREE_MODEL (store));
fill_model (store);
/* ... */
}
</programlisting></informalexample>
This example uses a #GtkListStore as model, but part of the elegance of the
model-view pattern is that you can easily use another tree model implementation,
or even write your own custom tree model.
</para>
<para>
Your application may make use of extra data attached to the icons in the
<structname>GnomeIconList</structname> via gnome_icon_list_set_icon_data() and
gnome_icon_list_get_icon_data(). With #GtkIconView such data is most
conveniently stored in an extra column in the tree model, so you would
call a function like
<informalexample><programlisting>
void
set_icon_data (GtkIconView *icon_view,
gint idx,
gpointer data)
{
GtkTreeModel *model;
GtkTreeIter iter;
model = gtk_icon_view_get_model (icon_view);
if (gtk_tree_model_iter_nth_child (model, &iter, NULL, idx))
gtk_list_store_set (GTK_LIST_STORE (model), &iter,
DATA_COLUMN, data, -1);
}
</programlisting></informalexample>
assuming that your tree model has a <literal>DATA_COLUMN</literal> of type
%G_TYPE_POINTER.
</para>
<para>
There is a number of minor API differences between
<structname>GnomeIconList</structname> and
<structname>GtkIconView</structname>:
<itemizedlist>
<listitem><para>
<type>GnomeIconListMode</type> is replaced by the
<link linkend="GtkIconView--orientation">orientation</link>
property of <structname>GtkIconView</structname>
</para></listitem>
<listitem><para>
<structname>GtkIconView</structname> can not be frozen in the same
way as <structname>GnomeIconList</structname> can with
gnome_icon_list_freeze() and gnome_icon_list_thaw(). Instead you can
replace the whole model of a <structname>GtkIconView</structname>,
instead of doing many small changes to the existing model.
</para></listitem>
</itemizedlist>
</para>
</chapter>
<!--
Local variables:
mode: sgml
sgml-parent-document: ("gtk-docs.sgml" "book" "part" "chapter")
End:
-->
|