Re: stock system

[Tim Janik <timj gtk org>]

thanks for the writeup havoc, this
was very enlightening.

On 26 Jul 2000, Havoc Pennington wrote:

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

> > 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.

yes, and now i'm pretty sure we want user-definable size,
and even let them override aliases. e.g. MENU could default to 16x16,
but blind-eyed-joe might want to make MENU evaluate as 128x128 so
he actually sees the icon ;)
a better example is probably my PALETTE->LARGE_TOOLBAR->(default)48x48
case that'd i actually need ;)

> > > +	(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", *, *, * } }

this is a bit perl-ish ;)
i had probably made the syntax correspond to style syntax, i.e.

style "ugly-buttons" {
  stock "gtk-button-ok" { ... }
}

class "GtkButton" style "ugly-buttons"

but your's is pretty compact and not really worse ;)

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

this is the accel_group used for the stock accelerators, not ulines right?

> > > +	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.

ok i see. though i'm not sure yet, i think that does eliminate the
prioritizing then.

> > > +	* 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. ;-)

ok, so why do we need those dialog stock ids, if i'm not intended
to create buttons from it? ;)

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

hm, i haven't seen code for creating menu items yet, is that to come?
that of course has issues with accelerator propagation and persistence
and needs to be carefully thought out.

> 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.

that's quite simple, for menu items:
- uline accels get added without modifiers to the menu item's menu's
  internal accel group. if the menu item's parent is actually a menu bar,
  we use GDK_MOD1_MASK and add the accelerator to the menu bar's public
  accel group that has to be installed on the menu bar's window.
- accelerators get installed on the menu's public accel group and that
  has to be added to the window the menu is used in (in light of the
  recent default accel group bug triggered on gtk-list, i'm pondering
  about making this "adding to the window" non-explicit)

for buttons, you should do quite the same, treating them as menu items
in menu bars, i.e.:
- add uline accels to the button's window's default_accel_group with
  GDK_MOD1_MASK
- add the stock accelerator to the button's window's default_accel_group
  right away

> 
> Havoc
> 

---
ciaoTJ