stock stuff

[Havoc Pennington <hp redhat com>]

Hi,

Here's a summary of design discussions we just had about adding stock
items to GTK.

A stock item is basically a tuple, it contains the following:
 - ID (a magic string, typically #define'd, e.g. GTK_STOCK_OK)
 - a label or name ("OK", "Exit", "Warning")
 - a keyboard accelerator (if it makes sense, absent e.g. for "Warning")
 - a translation domain for translating the label
 - a GtkIconSet

The interface for stock items might be:

struct _GtkStockItem
{
  const char *label;
  GdkModifierType modifier;
  guint keyval;
  const char * translation_domain;
};

void gtk_stock_add (const char *stock_id,
                    const GtkStockItem *item);

/* item is filled in with stuff that shouldn't be modified. */
void gtk_stock_lookup (const char * stock_id,
                       GtkStockItem *item);

Note that GtkStockItem doesn't contain a GtkIconSet. That's because
the mapping from stock ID to icon set depends on the GtkStyle of each
widget, since it comes from the theme.

A GtkIconSet contains an icon in all its states and sizes. 

In any case, the typical usage would be:

GtkIconSet * icon_set;

icon_set = gtk_style_get_icon_set (GTK_STOCK_OK);

GdkPixbuf *pixbuf = gtk_icon_set_get_icon (icon_set,
                                           GTK_STATE_NORMAL,
                                           GTK_ICON_SIZE_MENU,
                                           PANGO_DIRECTION_LTR);

Note that GtkStyle contains a mapping from stock ID to GtkIconSet. 
This would come from the gtkrc, as discussed in the previous
mail. Most likely there will be a GtkIconFactory object used in the
style to represent this mapping.

In gnome_init(), GNOME will call gtk_stock_add() a bunch of times to
add new stock items. Other libraries such as GtkExtra could also do 
this if they wanted to.

To add new icons, gnome_init() or nautilus_init() or whatever would do
this:

gtk_push_icon_factory (GtkIconFactory *factory);

This call adds an override icon factory to the list of default icon
factories each style will search. That is, if there's no override for
a stock ID in the gtkrc, GTK will search from the top to the bottom of
the icon factory stack.

This lets libgnomeui or libnautilus add icon sets to go with their
stock items.


GtkImage will become the uber-image-display widget, capable of
displaying a pixbuf, a pixmap, a GdkImage, a free-floating icon set,
or a stock icon. If it's displaying a stock icon, it will store the
stock icon name rather than the derived GtkIconSet, and if it gets the
style_set signal or otherwise decides that the stock icons may have
changed, it will re-lookup the icon set. This gives us on-the-fly
updates, if you switch themes.


Havoc