Notes on adding icon theme support

[Owen Taylor <otaylor redhat com>]

A plan for incorporating named icon themes into GTK+
====================================================

What is an icon theme?

 Icon themes are a semi-standardized Linux/Unix desktop feature,
 as described in:

  http://www.freedesktop.org/standards/icon-theme-spec.html

 They are currently supported by both GNOME and KDE and
 used in standards such as the Desktop Entry standard,
 and presumably the new mime-type standard.

Why support them in GTK+?

 - They are useful in themselves - apps often need various
   custom icons that can change with the current icon theme.

 - They are useful when implementing desktop standards;
   in particular the file selector needs them to show the 
   right icons for document types.

 - They provide a way of fixing problems we have with the
   current stock icon theming system where substitute
   images are provided for logical sizes rather than 
   for pixel sizes, which gives a complex ugly 
   interaction between changing the logical sizes via
   XSETTINGS and changing the stock icons as part
   of the widget theme.

Difference between named icons and a stock icons:

 - Named icons are looked up by a pair of name/pixel size.
 - Stock icons are looked up by name/symbolic size/direction/state
   with automatic insensitization/prelighting based on
   the state if particular variants aren't provided.
 - Stock icons sizes can be defined with both width/height
   while themed icons are always square

Adding named icon support to GTK+

 - Move GnomeIconTheme into GTK+ as a low level way
   of accessing icons.

  (http://cvs.gnome.org/lxr/source/libgnomeui/libgnomeui/gnome-icon-theme.h)x

   GtkIconTheme is screen-specific since the icon
   theme will be done as a XSETTING, so is screen-specific. 

   Have a singleton icon theme object for each screen, retrieved
   by: gtk_icon_theme_get_for_display()
   
   Add a signal on GtkIconTheme for changes to the theme 
   (add fam hooks that interested apps could hook up?) or 
   to the icon theme through xsettings.

 - Add gtk_icon_source_set_icon_name() to set an icon source that 
   backends off the icon theme.

   Add syntax to gtkrc parser:

    stock["stock-id"] = { FILENAME, DIRECTION, STATE, SIZE }

   Is extended to allow @"icon-name" to replace FILENAME.

   The default setup for all stock icons is:

    stock["stock-id"] = { @"stock-id", *, *, * }

   Except for icons that need rtl variants, where
   we do:   

    stock["stock-id"] = { @"stock-id-ltr", LTR, *, * }
    stock["stock-id"] = { @"stock-id-rtl", RTL, *, * }

   Fake a theme changes on GtkIconThem::changed so everything
   recreates/redraws its stock icons.

 - Add gtk_image_set_icon_name (image, icon, pixel_size); this
   automatically tracks icon theme changes.

 - Maybe also add:
   gtk_drag_source_set_icon_name(), gtk_drag_set_icon_name()
   Most other places that take a stock ID are for a stock
   *item* not a stock *icon*, so shouldn't need icon-name
   equivalents.

Issues:

 - How do we deal with built in stock icons and avoiding
   a dependency on a tree of icon files? One possibility
   is to make all the icon files implicitely part of the
   default theme, though that causes problems with the
   possiblity that a desktop file (say) might reference
   one of the stock icons, which would then work under
   GNOME but not under non-GTK+-based desktop environments.

 - If the allocation of a GtkImage with an icon is
   bigger than the the requisiton, should we use the
   biggest theme icon that fits in the larger allocated
   size?