stock icon themes

[Havoc Pennington <hp redhat com>]

Hi,

This mail is just about the RC file format. So far I've changed () to
{} since Owen/Tim seemed to agree on that, and swapped the order of
state/size (see below), otherwise it's the same.

The goal in an RC file is to associate a set of GtkIconSource with 
a stock ID. I'll post another mail with the icon factory/source/set
patch and the ChangeLog for that, to understand what that means.

Briefly though, what you want to do is tell GTK+ what file to load an
icon from, given a triplet of direction, size, and state specifying
the desired icon.

In the simplest case, you use the same icon for all text directions,
all icon sizes, and all states. In this case, GTK+ is going to scale
the icon to various standard sizes, and also do some simple
fading/brightening to make it look insensitive or prelighted. The icon
will be the same in left-to-right and right-to-left languages.

The simple case might look like this:

    style "myicons"
    {
      stock["gtk-dialog-warning"] = 
        { 
          { "stock-icons/dialog_error.png", *, *, *} 
        }
    }

    class "GtkImage" style "myicons"

Here, the direction, state, and size are all wildcarded, indicating
that "stock-icons/dialog_error.png" is to be used as the source image
for all variants of this icon.

(I just noticed that we have to address the issue of the pixmap search
path, or else we have to require an absolute path in these files; 
suggestions on that welcome. Note that pixmaps will typically come
with the theme. But, back to the point.)

You might also want to specify _different_ source images for different
icon specifications. Two common cases are that you want to hand-draw
icons at a given size, instead of scaling; or you want to reverse an
image for LTR or RTL languages. In those cases, you specify more than
one icon source:

    style "myicons"
    {
      stock["gtk-dialog-warning"] = 
        { 
          { "stock-icons/dialog_error_ltr.png", LTR, *, *},
          { "stock-icons/dialog_error_rtl.png", RTL, *, *}  
        }
    }

or:

    style "myicons"
    {
      stock["gtk-dialog-warning"] = 
        { 
          { "stock-icons/dialog_error_menu_size.png", *, *, MENU},
          { "stock-icons/dialog_error_dialog_size.png", *, *, DIALOG}, 
          /* fall back */
          { "stock-icons/dialog_error_fallback.png", *, *, *}  
        }
    }

So, that's the general idea.

The order of appearance of the icon sources is not significant; the
"best match" source is the one that gets used. For determining the
best match, direction has priority over state has priority over
size. The idea there is that they are in order of semantic importance,
rather than aesthetic importance; you need to get arrows pointing the
right way, then get things properly sensitive-looking or not, then you
can worry about whether scaling causes jaggies. Note that the order of
specification in the rc file matches the priority (direction, state,
size). (I just changed that BTW, it wasn't true in the original
patch.)

RTL, LTR correspond to GTK_TEXT_DIR_LTR and GTK_TEXT_DIR_RTL.

MENU, DIALOG, etc. correspond to this enum:

    typedef enum
    {
      GTK_ICON_MENU,
      GTK_ICON_BUTTON,
      GTK_ICON_SMALL_TOOLBAR,
      GTK_ICON_LARGE_TOOLBAR,
      GTK_ICON_DIALOG
    } GtkIconSizeType;

gtkrc.c already knew about the GtkStateType tokens, so those didn't
need to be added.

That's all the info on this I can think to write down, so if you have
other questions just ask.

Havoc