GIcon thoughts

[Matthias Clasen <mclasen redhat com>]

One of the items on http://live.gnome.org/GioTodo is "GIcon renderer",
so I started to think a bit about how that could look like. Alex'
pointed me at NautilusIconInfo for ideas. Looking at that, it is 
somewhat similar in spirit to GtkIconInfo, with some differences:

- supports lookup by GIcon in addition to lookup by name(s) 
- handles pixel sizes (ie ensures that you actually get the size 
  you asked for) 
- handles Nautilus' zoom levels
- provides some support for emblems
- has some logic to provide default icons if one is missing
- is an object, not a boxed type like GtkIconInfo
- has a cache (objects stay around for 5 seconds after the last use),
  implemented using toggle references


First of all, I don't think we want to have zoom levels in GTK+, and
the rudimentary emblem support seems not really worth keeping (a 
function to render a complete icon including emblems and overlays
might be more attractive, but also a lot more involved). The default
handling should probably stay in Nautilus, too.

This leaves GIcon support, pixel sizes and caching. Concrete API
additions could look as follows:

/* Creates a new GtkIconInfo for a fixed pixbuf - this is not
* really necessary as API, but it is used internally 
* for GFileIcons, and making it public doesn't cost us much
*/
GtkIconInfo *
gtk_icon_info_new_for_pixbuf (GtkIconTheme *theme,
                              GdkPixbuf    *pixbuf);

/* Looks up a GtkIconInfo for a GIcon and a given pixel size.
* Note that looking up by pixel size still doesn't guarantee
* that you actually get a pixbuf of that size; for that, see
* load_at_size().
*
* To look up by GtkIconSize, use gtk_icon_size_lookup_for_settings. 
*/
GtkIconInfo *
gtk_icon_theme_lookup_by_gicon (GtkIconTheme *theme,
                                GIcon        *icon,
                                gint          pixel_size);

/* Loads the icon, and scales it to the given size -
* some care should be taken to make load_at_size(); load() work
* correctly wrt. to sizes, while still getting some caching 
* benefits for repeated load_at_size() with the same size 
*/
GdkPixbuf *
gtk_icon_info_load_at_size (GtkIconInfo *info,
                            gint         pixel_size);


We can't implement the cache using toggle references for 2 reasons:
a) GtkIconSize is a boxed, not an object 
b) toggle references only work for a single user, thus they have
   to be reserved for bindings, at least bindable objects.
I propose to instead turn GtkIconInfo into a refcounted boxed object,
and then implement the caching logic for the case that the refcount
drops to one.

Beyond the icon theme code, we have a number of APIs based on 
icon names in GTK+:

GtkAction::icon-name
gtk_image_new_from_icon_name
gtk_window_set_icon_name
gtk_window_set_default_icon_name
gtk_status_icon_new_from_icon_name
gtk_icon_source_set_icon_name
gtk_about_dialog_set_logo_icon_name
gtk_drag_set_icon_name
gtk_drag_source_set_icon_name
gtk_file_system_volume_get_icon_name
gtk_file_info_set_icon_name
gtk_printer_set_icon_name
gtk_tool_button_set_icon_name
gtk_tooltip_set_icon_from_icon_name

At least a few of these should probably get a gicon counterpart.


Comments ?


Matthias