Re: stock system

[Havoc Pennington <hp redhat com>]

Tim Janik <timj@gtk.org> writes: 
> s/used/are used/ ?
> 

Yep.

> > +	the "same" icon (e.g. an OK button icon), and cache 
> > +	for rendered icons
> 
> rendered? i.e. scaling?

By "rendered" I mean the result of the render_icon virtual function in
GtkStyleClass.

render_icon converts a GtkIconSource, plus a direction/size/state
triplet, into a GdkPixbuf.

Remember that a GtkIconSource is based on one of the lines from the RC file:
 { "filename.png", LTR, PRELIGHT, MENU }

The struct is:

struct _GtkIconSource
{
  /* Either filename or pixbuf can be NULL. If both are non-NULL,
   * the filename gets ignored.
   */
  const char *filename;
  GdkPixbuf *pixbuf;

  GtkTextDirection direction;
  GtkStateType state;
  GtkIconSizeType size;

  /* If TRUE, then the parameter is wildcarded, and the above
   * fields should be ignored. If FALSE, the parameter is
   * specified, and the above fields should be valid.
   */
  guint any_direction : 1;
  guint any_state : 1;
  guint any_size : 1;
};

By the time it's passed to render_icon, the pixbuf field of
GtkIconSource will have been filled in from the filename. (The pixbuf
is lazily loaded as required, so you only load files for
direction/size/state triplets that get used).

render_icon takes a GtkIconSource instead of a GdkPixbuf because you
might want to change how rendering works depending on how the source
was specified. For example if the RC file specified a particular
filename for a particular state, then probably you want to just use
that image as-is instead of fading or prelighting it. 

The current _gtk_default_render_icon() isn't very sophisticated about
this; we need to think about what behavior is correct.

> is the caching behaviour exposed, i mean can we change that to
> use adequat pixbuf caching API in the future?
> 

It's not exposed. Right now it's just that GtkIconSet keeps a list of
pixbufs it's recently rendered, which is pretty lame. There are
various schemes we could consider.

If we allow users to specify arbitrary icon sizes, that's going to
have a big effect on how we want to do this.

> > +	(GtkIconFactory): Hash from stock ID to GtkIconSet; used to look
> 
> what exactly is a stock ID?
>

#define GTK_STOCK_BUTTON_OK "gtk-button-ok"

for example, it's just a string.
 
You use this in gtkrc:
 stock["gtk-button-ok"] = { { "filename.png", *, *, * } }

and also to create your button:
 button = gtk_button_new_stock (GTK_STOCK_BUTTON_OK, accel_group);

> > +	up the icon set for a given stock ID.  GTK maintains a stack of
> > +	GtkIconFactory to search, and applications or libraries can add
> 
> s/GtkIconFactory/GtkIconFactory objects/ ?
>

Yes.
 
> > +	additional icon factories on top of the stack
> 
> how's the stack ordered? FIFO? if that's the case (the term "stack"
> indicates that), shouldn't we use something similar to the key binding
> priorities here to let users (or desktop distributors) override
> application factories?
>

You can override the factories via an RcStyle; the stack is just a
fallback if no icon is found in widget->style->icon_factories.

The idea is that GTK+, gnome-libs, Nautilus, etc. can install their
own sets of stock icons, and then the theme always overrides the
programmatically-installed default icons.

> > +	* gtk/gtkstyle.h, gtk/gtkstyle.c: Add a virtual function
> > +	render_icon used to derive a GdkPixbuf from a GtkIconSource.
> 
> "derive" ? now what's "render"ing exactly here? ;)
>

render_icon means to come up with a GdkPixbuf based on a
GtkIconSource. Theme engines can derive the pixbuf however they want -
they can turn all icons upside-down, or replace them all with purple
rectangles, whatever. I'm sure we can look forward to many truly awful
theme engines... ;-)
 
> > +	* gtk/gtkstock.h, gtk/gtkstock.c: Header with the GtkStockItem type
> > +	(contains information about a stock item), the built-in stock item
> > +	IDs, and functions to add/lookup stock items.
> 
> can you elaborate on what makes up a "stock item", conceptually?
> 

Conceptually a stock item is a way to display an action to the
user. Most typically, the action can be displayed as a button or menu
item. The components of a display are the stock image, if any, a
label, and a translation domain for the label (needed so that
gnome-libs or Nautilus can register stock items, but GTK can call
gettext on them). Actions also have accelerators associated with them,
that can automatically get associated with the button or menu item.

It's called "stock" because we predefine some standard action
displays, for certain common semantic actions. There aren't many of
these in GTK itself, but GNOME will add a bunch more, and apps can add
their own for convenience.

The stock_id is used to refer to a semantic action, such as "exit the
application". 

A GtkStockItem stores all the information about a stock item, except
the stock image. Stock images are stored separately in a
GtkIconFactory inside a GtkStyle so they can be themed via RC file.

This leaves GtkStockItem as follows:

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

The struct is meant to be used in a static array, partial example from
gtkstock.c:

static GtkStockItem builtin_items [] =
{
  /* KEEP IN SYNC with gtkiconfactory.c stock icons */ 
 
  { GTK_STOCK_DIALOG_INFO, N_("Information"), 0, 0, GTK_DOMAIN },
  { GTK_STOCK_DIALOG_WARNING, N_("Warning"), 0, 0, GTK_DOMAIN },
  { GTK_STOCK_DIALOG_ERROR, N_("Error"), 0, 0, GTK_DOMAIN },
  { GTK_STOCK_DIALOG_QUESTION, N_("Question"), 0, 0, GTK_DOMAIN },

... 

 { GTK_STOCK_CLOSE, N_("Close"), GDK_CONTROL_MASK, 'w', GTK_DOMAIN },
 { GTK_STOCK_QUIT, N_("Quit"), GDK_CONTROL_MASK, 'q', GTK_DOMAIN },

... etc.

Note that dialogs are crammed in to the stock framework. This is a
little bit questionable, since they don't have accelerators and don't
really represent an action. However GTK+ will happily use a dialog
stock ID to create a button called "Error" if you try to do that. ;-)

Accelerators for stock items get customized in the standard GTK way,
by customizing the menu items.

The stock label can be a uline string, GTK will parse this for the
accelerator when creating a stock widget. If you have a uline and also
specify an accelerator in the GtkStockItem struct, GTK just installs
both accelerators, I'm not sure what else to do there.

Havoc