Docs for the gtk-style-context branch changes

[Carlos Garnacho <carlosg gnome org>]

Hey all,

I've taken my time to write the API and miscellaneous docs for the
gtk-style-context branch:

  http://www.lanedo.com/~carlos/gtk3-docs/theming.html

At the moment there are some render functions missing, such as the one
to paint the resize handle (could be merged together with
gtk_render_handle()?) and spinners (I'm actually thinking towards having
a common gtk_render_progress() method that works for progressbars and
spinners, since the requirements wrt animations are roughly the same),
but the core is pretty much complete.

Currently there are some small warts in the API:

* There is a GtkStyleSet object, used to transfer style information from
the GtkStyleProviders to the widgets' GtkStyleContext, this naming leads
to "interesting" API like gtk_style_set_set_property() and
gtk_style_set_set(), I've thought of other names such as
GtkStyleCollection or GtkStyleStore, but I'm still undecided on this

* GtkStateFlags is used in the theming layer, living side by side with
GtkStateType (the latter is even used in the API i.e. when checking
whether there is a running animation for a specific state).
GtkStateFlags is potentially really useful, but practically isn't that
much due to the higher layers having a single state set. Pushing
GtkStateFlags to GtkWidget could do wonders in having implicit
animations whenever a widget changes state.

* There is no intuitive replacement for gtk_widget_modify_*(). If we are
to drop GtkStyle, I think that 3rd party libraries and apps implementing
widgets could define regions and attach a GtkStyleProvider with the
fallback priority to theme these, this way themes and users' CSS have an
oportunity to theme these differently if they want, although others I've
talked with think gtk_widget_modify_*() is handy API that shouldn't go
away.

* As mentioned earlier in this ML, there's still fg/bg/text/base, these
could definitely be reduced to fg/bg if we're deciding to drop GtkStyle.

About GtkStyle and backwards compatibility, there is already basic
compat support, but a few decisions were taking just for the sake of
keeping it, so I see 3 possibilities:

1) Keep GtkStyle in 3.0, encourage people verbally to use
GtkStyleContext instead.

2) Keep GtkStyle, but not include in gtk.h, force people to take a
decision between being lazy and using the brand new stuff.

3) Remove GtkStyle, port all GTK+ widgets, force people to move forward.

I'll be of course discussing all of this during the hackfest, but any
comments here will be welcome.

  Carlos