diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index cf4d3e9c4c..29b09bcc86 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,8 @@ +2004-11-03 Matthias Clasen + + * gtk/migrating-GtkIconView.sgml: Add a first version of + a GnomeIconList --> GtkIconView migration chapter. + 2004-11-02 Matthias Clasen * gtk/tmpl/gtkcellrenderercombo.sgml: diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index 81cdb87c10..4f9f60f0d0 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -191,6 +191,7 @@ + @@ -571,6 +572,7 @@ that is, GUI components such as GtkButton or >k-migrating-GtkFileChooser; >k-migrating-GtkAction; >k-migrating-GtkComboBox; + >k-migrating-GtkIconView; diff --git a/docs/reference/gtk/migrating-GtkIconView.sgml b/docs/reference/gtk/migrating-GtkIconView.sgml new file mode 100644 index 0000000000..5736fa8dea --- /dev/null +++ b/docs/reference/gtk/migrating-GtkIconView.sgml @@ -0,0 +1,140 @@ + + + Migrating from GnomeIconList to GtkIconView + + + Since version 2.6, GTK+ provides the GtkIconView + widget. It is similar in functionality to the GnomeIconList 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. + + + + GtkIconView currently doesn't support some features + found in GnomeIconList. Icons can not be positioned freely, the spacing is not customizable, + and it is not possible to edit the names of icons. + + + + To convert an application that uses GnomeIconList to + GtkIconView, the first step is to organize your data + in a GtkTreeModel. GnomeIconList 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: + + 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 ... */ + } + + you will have to create a tree model, attach your icon view to it, and fill the model: + + enum { + PIXBUF_COLUMN, + TEXT_COLUMN, + + /* you can have more columns here, e.g */ + + DATA_COLUMN + }; + + void + fill_model (GtkListStore *model) + { + GtkTreeIter iter; + GdkPixbuf *pixbuf; + + gtk_list_store_append (model, &iter); + pixbuf = gdk_pixbuf_new_from_file ("file1.png", NULL); + gtk_list_store_set (model, &iter, PIXBUF_COLUMN, pixbuf, TEXT_COLUMN, "Icon 1", -1); + g_object_unref (pixbuf); + + gtk_list_store_append (model, &iter); + pixbuf = gdk_pixbuf_new_from_file ("file2.png", NULL); + gnome_icon_list_append (icon_list, PIXBUF_COLUMN, pixbuf, TEXT_COLUMN, "Icon 2", -1); + g_object_unref (pixbuf); + + /* more icons ... */ + } + + int + main (int argc, char *argv[]) + { + GtkWidget *icon_view; + GtkTreeModel *model; + + gtk_init (&argc, &argv); + + /* do other initialization... */ + + /* construct the GtkIconView */ + icon_view = gtk_icon_view_new (); + model = 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), model); + + fill_model (model); + + /* ... */ + } + + 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. + + + + Your application may make use of extra data attached to the icons in the + GnomeIconList 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 + + 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); + } + + assuming that your tree model has a DATA_COLUMN of type G_TYPE_POINTER. + + + + There is a number of minor API differences between GnomeIconList and GtkIconView: + + + GnomeIconListMode is replaced by the orientation property of GtkIconView + + + GtkIconView can not be frozen in the same was as GnomeIconList with + gnome_icon_list_freeze() and gnome_icon_list_thaw(). Instead you can + replace the whole model of a GtkIconView, instead of doing many small + changes to the existing model. + + + + + +