stock items API

[Havoc Pennington <hp redhat com>]

Hi,

Someone is going to kill me shortly for all these interfaces. ;-)

Here is a suggestion for the stock items interface. It's very, very
simple for now; I think it would be good to start with a simple and
opaque interface like this, and add features if/when required.

The main design issue of interest is how the GtkStockFactory for a
given widget is obtained. We would like themes to be involved in the 
process, so they can override the stock items.

I propose that we create a gtk_widget_get_stock_factory() function
which for now could simply grab a the global default stock factory. We
also say that all widgets using stock items should reload the stock
factory on style_set. Then when we get around to reworking the themes
code (likely post-1.4, but maybe before), we can change
gtk_widget_get_stock_factory() to do the right thing.

For now we could just allow gtkrc to contain a stock_id<->imagefile 
mapping, to override the default GTK images. That gets you most of 
the themeability you're likely to want.

GNOME can add additional stock items to the default stock factory in
gnome_init(), GTK would probably have only a few items.

Header code appended... will implement as soon as the interface is
hashed out.

Havoc



/* gtkiconset.h */



/* The theme determines the actual pixel sizes these enum
   values correspond to. */
typedef enum
{
  GTK_ICON_MENU,
  GTK_ICON_BUTTON,
  GTK_ICON_SMALL_TOOLBAR,
  GTK_ICON_LARGE_TOOLBAR
} GtkIconSizeType;

/* Opaque type. Stores "the same" image in a variety of sizes and
   states. */
typedef struct _GtkIconSet GtkIconSet;

/*
 * Functions users might want to call
 */

/* Create a blank icon set, calling get_icon() on this will return NULL */
GtkIconSet* gtk_icon_set_ref             (GtkIconSet      *icon_set);
void        gtk_icon_set_unref           (GtkIconSet      *icon_set);
GtkIconSet* gtk_icon_set_copy            (GtkIconSet      *icon_set);

/* Get one of the icon variants in the set, creating the variant if
   necessary. */
GdkPixbuf*  gtk_icon_set_get_icon        (GtkIconSet      *icon_set,
                                          GtkStateType     state,
                                          GtkIconSizeType  size);

/* Functions mostly interesting to GTK internally,
   theme engines, or for users registering their own stock
   items */

GtkIconSet* gtk_icon_set_new             (void);

/* Scale this icon up and down to the icon set sizes, and
   automatically generate the states. States and sizes are of course
   generated lazily. The pixbuf should be large rather than
   small.
*/
GtkIconSet* gtk_icon_set_new_from_pixbuf (GdkPixbuf       *pixbuf);

void        gtk_icon_set_set_from_pixbuf (GtkIconSet      *icon_set,
                                          GdkPixbuf       *pixbuf);

/* FIXME need to be able to set the pixbuf sizes independently, because
   typically that will look a lot nicer. */


/* Clear icon set contents, drop references to all contained
   GdkPixbuf objects. */
void        gtk_icon_set_clear           (GtkIconSet      *icon_set);

/* create an image for a particular state/size, perhaps eventually
   using a function from the theme virtual table. */
GdkPixbuf*  gtk_create_icon              (GdkPixbuf       *source_image,
                                          GtkStateType     state,
                                          GtkIconSizeType  size);





/* gtkstock.h */





/* These are opaque types. A stock item contains information about
   the contents of a stock menu or toolbar item. Namely, right now
   it contains a label and/or an icon set. The stock factory
   is basically just a hash from stock ID strings to stock items.

   We could keep a pointer to the stock factory in GtkStyle, and on
   style_set widgets would have to reload their stock icons. This lets you
   have a different stock factory per-widget, which I think is sort of useless.

   Alternatively, could put a get_stock_factory() function in the theme
   virtual table.

   It would be nice to avoid having to stuff the hash table with all
   available stock items the first time someone calls lookup(), but
   I'm not sure how to do that.
*/
typedef struct _GtkStockItem GtkStockItem;
typedef struct _GtkStockFactory GtkStockFactory;

GtkStockFactory* gtk_stock_factory_new       (void);
GtkStockFactory* gtk_stock_factory_ref       (GtkStockFactory *factory);
void             gtk_stock_factory_unref     (GtkStockFactory *factory);
GtkStockFactory* gtk_stock_factory_copy      (GtkStockFactory *factory);

GtkStockItem*    gtk_stock_factory_lookup    (GtkStockFactory *factory,
                                              const gchar     *stock_id);

/* inserted stock item MUST have either a label or an icon set */
void             gtk_stock_factory_insert    (GtkStockFactory *factory,
                                              const gchar     *stock_id,
                                              GtkStockItem    *item);

GtkStockItem*    gtk_stock_item_new          (void);
GtkStockItem*    gtk_stock_item_ref          (GtkStockItem    *item);
void             gtk_stock_item_unref        (GtkStockItem    *item);
GtkStockItem*    gtk_stock_item_copy         (GtkStockItem    *item);

void             gtk_stock_item_set_label    (GtkStockItem    *item,
                                              const gchar     *label);
void             gtk_stock_item_set_icon_set (GtkStockItem    *item,
                                              GtkIconSet      *icon_set);
/* One but not both of these may return NULL */
gchar*           gtk_stock_item_get_label    (GtkStockItem    *item);
GtkIconSet*      gtk_stock_item_get_icon_set (GtkStockItem    *item);