## 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:

    1
    2
    3
    4
    5
    6
    7
    8
    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:

    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
    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);

      /* ... */
    }

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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    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 way as GnomeIconList can 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.