The changes in the themes have been communicated well in advance by the GTK+ team, and other applications shipping custom CSS updated themselves well before the 3.20 release.

If some application developers decide to ship additional CSS it's actually up to them to keep it up to date. Until 3.20 we never guaranteed any stability for the CSS; starting from 3.20 we do.

It would be good, in order to identify the style issue, to check with the GTK inspector which part of the widget is not being rendered correctly:

  https://wiki.gnome.org/Projects/GTK%2B/Inspector

When was css disclosed as experimental or subject to change?  A quick
search in the NEWS file seems to say about 3.19.

(In reply to Emmanuele Bassi (:ebassi) from comment #1)
> Until 3.20 we never guaranteed any
> stability for the CSS; starting from 3.20 we do.

I'm curious to know where that API instability was documented in <= 3.18. I don't see any warnings at:
https://developer.gnome.org/gtk3/3.18/GtkStyleContext.html
https://developer.gnome.org/gtk3/3.18/GtkCssProvider.html

Those would have been obvious places where to put big warnings…

(In reply to Morten Welinder from comment #2)
> When was css disclosed as experimental or subject to change?

Since we released GTK. It's been communicated multiple times that the CSS style is not part of the API *or* ABI.

> A quick search in the NEWS file seems to say about 3.19.

For GTK+ 3.20 we started guaranteeing that the CSS is going to be stable.

(In reply to Sébastien Wilmet from comment #3)
> (In reply to Emmanuele Bassi (:ebassi) from comment #1)
> > Until 3.20 we never guaranteed any
> > stability for the CSS; starting from 3.20 we do.
> 
> I'm curious to know where that API instability was documented in <= 3.18.

CSS has never been declared as part of the ABI.

> I don't see any warnings at:
> https://developer.gnome.org/gtk3/3.18/GtkStyleContext.html
> https://developer.gnome.org/gtk3/3.18/GtkCssProvider.html
> 
> Those would have been obvious places where to put big warnings…

We don't explicitly say that the API is stable in the GTK API reference either.

> GDK_AVAILABLE_IN_ALL
> gboolean         gtk_css_provider_load_from_data (GtkCssProvider  *css_provider,
>                                                   const gchar     *data,
>                                                  gssize           length,
>                                                  GError         **error);

That looks to me as it being declared part of the ABI.  That is the
point of GDK_AVAILABLE_IN_ALL.


> It's been communicated multiple times that the CSS style is not part of
> the API *or* ABI.

Where and to whom?  Evidently not in the obvious places like NEWS and
the links provided by Sébastien.  On the inside of your office door wouldn't
really count, would it?

(In reply to Morten Welinder from comment #6)
> > GDK_AVAILABLE_IN_ALL
> > gboolean         gtk_css_provider_load_from_data (GtkCssProvider  *css_provider,
> >                                                   const gchar     *data,
> >                                                  gssize           length,
> >                                                  GError         **error);
> 
> That looks to me as it being declared part of the ABI.  That is the
> point of GDK_AVAILABLE_IN_ALL.

You're (purposefully?) confusing the issue. The C ABI hasn't changed. The CSS ABI, i.e. what you use to write theme, is not subject to any ABI stability guarantee when it comes to class names. A CSS class or identifier exposed by a widget could be remove between minor releases, i.e. going from 3.x to 3.x+1. It's not even a functional change: assuming that the CSS is valid, the function does not fail; the issue is that widgets may not match the selectors used.

This is also not entirely a new concept: GTK2 themes where not inherently stable either, only the C ABI was; we just never really changed them because changing them required writing a bunch of C code that could crash your application.

> > It's been communicated multiple times that the CSS style is not part of
> > the API *or* ABI.
> 
> Where and to whom?  Evidently not in the obvious places like NEWS and
> the links provided by Sébastien.  On the inside of your office door wouldn't
> really count, would it?

We communicated this:

 * on Planet GNOME
 * on various GTK-related mailing lists
 * at various GTK and GNOME related conferences
 * on various websites
 * on IRC

pretty much the same venues we use to say that the GTK C API is stable across minor releases of the same major version. We've been saying that for so long, and to so many people, that it seems weird to me that somebody that has been using GTK+ 3.x for so long could come up now, five years later, and be surprised about it — though I'm entirely willing to believe that.

We cannot go back in time and write it on the old API reference, sadly; for that, we'd need a time machine.

(In reply to Emmanuele Bassi (:ebassi) from comment #7)
> We communicated this:
> 
>  * on Planet GNOME
>  * on various GTK-related mailing lists
>  * at various GTK and GNOME related conferences
>  * on various websites
>  * on IRC

What about the people who just RTFM?

(In reply to Sébastien Wilmet from comment #8)
> What about the people who just RTFM?

The FM did not mention any CSS classes/names for widgets prior to 3.20 ...

> * on Planet GNOME

Not searchable.

> * on various GTK-related mailing lists

Partially searchable.  The proper place would appear to be gtk-app-devel-list.
I am unable to find anything.  Application developers are not supposed to
use gtk-devel-list, but even so nothing really stands out.

> * at various GTK and GNOME related conferences

If you say so.  Not searchable.

> * on various websites

Without specifics, not searchable.

> * on IRC

Not searchable.


You may think you have communicated the instability, but the evidence doesn't
support that.  The media you list are basically ephemeral -- the equivalent
of having written the decision on the blackboard.

Douglas Adams was surprisingly on point:

“There’s no point in acting surprised about it. All the planning charts and demolition orders have been on display at your local planning department in Alpha Centauri for 50 of your Earth years, so you’ve had plenty of time to lodge any formal complaint and it’s far too late to start making a fuss about it now. … What do you mean you’ve never been to Alpha Centauri? Oh, for heaven’s sake, mankind, it’s only four light years away, you know. I’m sorry, but if you can’t be bothered to take an interest in local affairs, that’s your own lookout. Energize the demolition beams.”

So why didn't you just ask? Why would you assume that something was part of the API if you weren't sure?

(In reply to Florian Müllner from comment #9)
> (In reply to Sébastien Wilmet from comment #8)
> > What about the people who just RTFM?
> 
> The FM did not mention any CSS classes/names for widgets prior to 3.20 ...

See the section 'Selectors' at:
https://developer.gnome.org/gtk3/3.18/GtkCssProvider.html#GtkCssProvider.description

> Selectors work very similar to the way they do in CSS, with widget class names taking the role of element names

With examples like this:
> GtkWindow GtkLabel {
>     background-color: #898989
> }

With that documentation, it was possible to write CSS in 3.18. And now a widget class name as a selector no longer works, the above example must be adapted to:

> window label {
>     background-color: #898989
> }

That's an API break. (but, side note, it's not an ABI break). And there was no warnings in the 3.18 documentation that the API was not considered stable.

(In reply to Emmanuele Bassi (:ebassi) from comment #7)
> We cannot go back in time and write it on the old API reference, sadly; for
> that, we'd need a time machine.

A more practical solution is to release new micro versions for those branches, at least for 3.18 since it's used in the latest Ubuntu LTS.

(In reply to Adam Williamson from comment #11)
> So why didn't you just ask? Why would you assume that something was part of
> the API if you weren't sure?

By looking at the 3.18 reference manual, there is nothing special about the CSS documentation, it looks like any other page. Why would someone have a doubt about API stability for CSS specifically, and not for e.g. GtkWindow?

Besides, if each app developer needs to ask questions, it doesn't scale.

Does the problem exist using default GTK+ theme?

It only exists using a dark theme that makes all the Gnumeric bars dark. Default themes are not dark, so they work. Many dark themes don't make the bars (toolbar, status bar etc) dark, and they work fine as well. It's only those themes that make everything dark that suffer this bug.

The dark theme was never meant as a free choice for users, but rather as an explicit developer choice for media applications. It is not too surprising that some applications don't work perfectly with it.

We seem to have lost the ability to look up css resources not associated
with widgets.  This is a sample css sniplet:

/* The whole column/row selected. */
GnmItemBar:active {
  color: red;
  font-weight: bold;
}

We have been using a GtkStyleContext with a widget path whose last item
was the GType of "GnmItemBar".

Looks like we can use GnmItemBar but not when it is associated to a specific state or class.
Any call to gtk_style_context_add_class() or gtk_style_context_set_style() seems to have unwanted consequences.

Created attachment 326980 [details]
Test program

With 3.10 I get the expected output:

Color: rgb(255,0,0)
Color: rgb(0,255,0)
Color: rgb(255,0,0)
Color: rgb(0,255,0)
Color: rgb(255,0,0)
Color: rgb(0,255,0)


With 3.20 I get this output:
Color: rgb(255,0,0)
Color: rgb(0,255,0)
Color: rgb(255,0,0)
Color: rgb(0,255,0)
Color: rgb(255,0,0)
Color: rgb(255,0,0)


The calls to gtk_style_context_set_state seem to put something into a funny
state.

See:
https://blogs.gnome.org/mclasen/2015/11/20/a-gtk-update/
https://feaneron.com/2016/01/04/quick-guide-to-port-an-app-for-gtk-3-20/

A better place for such porting guide would be in the reference manual…

I was aware of these two posts, just they don't help.

Please forge my previous comment. The first link does help even if it does not fully solve the issue.

I don't see anything in comment 20's links that says my example in comment 19
should not work.  At least not anything that relating to the final colour, ie.,
the part that does not work.

/* ... */

      GdkDisplay:active { color : #00ff00; }

/* ... */

  gtk_widget_path_append_type (path, GDK_TYPE_DISPLAY);


This is pretty bizarre. What did you expect to happen, your entire screen turns green ? GtkWidgetPath is an api to access styles that are associated with widgets. The fact that you can pass in a random type into gtk_widget_path_append_type and it happened to work in the past does not mean that that is supported use of the API. The documentation even says: Appends a widget type...

But, you are correct in so far as using widget type names for css matching does not work anymore in 3.20. Here is how to make your example work in 3.20:

Replace the css with:

     "test { color : #ff0000; }\n\
      test:active { color : #00ff00; }",

Instead of appending GDK_TYPE_DISPLAY, do

  gtk_widget_path_append_type (path, G_TYPE_NONE);
  gtk_widget_path_iter_set_object_name (path, -1, "test");

I don't expect anything in Gtk to act on css settings for GdkDisplay.
GdkDisplay was chosen as a random, non-widget gobject for the purpose of
the test program

In Gnumeric, it is a canvas item we are discussing.  Things it makes perfect
sense to apply css styling to.

> The fact that you can pass in a random type into gtk_widget_path_append_type
> and it happened to work in the past does not mean that that is supported use
> of the API.

It is pretty much documented to be supported.  Here's what the docs for
GtkWidgetPath say:

 * If you are using GTK+ widgets, you probably will not need to use
 * this API directly, as there is gtk_widget_get_path(), and the style
 * context returned by gtk_widget_get_style_context() will be automatically
 * updated on widget hierarchy changes.

It very clearly considers the possibility of using this for non-widgets.

We're moving to gitlab! As part of this move, we are moving bugs to NEEDINFO if they haven't seen activity in more than a year. If this issue is still important to you and still relevant with GTK+ 3.22 or master, please reopen it and we will migrate it to gitlab.

As announced a while ago, we are migrating to gitlab, and bugs that haven't seen activity in the last year or so will be not be migrated, but closed out in bugzilla.

If this bug is still relevant to you, you can open a new issue describing the symptoms and how to reproduce it with gtk 3.22.x or master in gitlab:

https://gitlab.gnome.org/GNOME/gtk/issues/new