Gnucash and css (was: Gtk3)

[Geert Janssens]

Bob,

As hinted in my previous message in the Gtk3 thread, I'd like to zoom in a bit 
on using Css for gnucash.

Let me start with a basic context for this discussion:
* css in gtk (and hence gnucash) is used to define the visual representation 
of the graphical user interface (defined through a set of "widgets").
* for the best user experience the GUI should be consistent in style.
* for standard widgets, gtk defines a default style (the Adwaita theme). 
However users are free to configure a different style (or theme) for their 
environment. Optionally each property in a theme can be overridden at a user 
level by a user-defined css file.

So for standard widgets, gnucash usually doesn't have to do anything. This is 
different for our custom widgets, such as the register and the SX overview 
calendar (both based on a GtkLayout and doing custom drawing via cairo), or 
widgets that define their own functional colors (like the transaction matcher 
in the generic import code).

These widgets don't have a style by default, and hence we need to define it. 
At the same time though, themes should be able to override whatever default 
style we choose. This suggests our own styling should generally have a 
FALLBACK priority rather than APPLICATION priority.

For any style property that is defined in the theme set by the user, this will 
then be used. If we define gnucash-only properties, these will most likely not 
appear in any theme and hence the values from our fallback will be used 
instead.

The tricky part here is to define a fallback that goes well with whatever 
theme the user has set for his environment. Take for example the colors used 
in the SX overview calendar (white background/black text). These may not work 
well with all themes so we should avoid to hard-code properties as much as 
possible. I would instead propose to leverage the style classes as defined in 
GtkStyleContext as much as possible [1]. Again for the SX overview calendar, 
add a style class GTK_STYLE_CLASS_CALENDAR and then use whatever styling 
information that gets set because of this [2]. Perhaps it requires more than 
one style class to be added to get this to work completely. You can look for 
examples in the Gtk source, like the use of the RUBBERBAND class in 
gtktreeview.c [3]. I believe/hope when done carefully this can result in a 
much more consistent GUI for gnucash and may reduce the amount of css we have 
to maintain ourselves.

Then, specifically for the register we have an option that allows the user to 
switch between the system level theme or our yellow/green theme. Building on 
the above, the system level theme should be composed using the right style 
classes. The yellow/green theme on the other hand is the first example I have 
found that warrants a separate css definition. And this time with APPLICATION 
priority because it's supposed to override theme specific styles. I would 
define a new style class (something like "gnc-custom-colors"). And in css 
write a section like this:

.gnc-custom-colors
{
    color a: xyz;
    color b: abc;
    ...
}

What the exact properties should be will depend on the properties we combine 
from the built-in style classes. If the built-in style classes for example 
provide a property "separator-color", we should set this property also in the 
.gnc-custom-colors class.

With this css in place, switching from default theme colors to our gnucash 
yellow/green theme is a matter of adding/removing the gnc-custom-colors style 
class from all register related widgets.

This same technique could be used for the label colors (negative numbers in 
red). Only define an additional class ("negative-numbers-in-red" would do 
fine) in which you explicitly set the red color to use and then add or remove 
this class from all widgets that need to be able to display negative numbers 
in red based on the user preference.

The last thing I'd like to bring up is the choice of property names. I read in 
your initial conversion to css you have chosen names very close to the 
internally used variable names. While this is not wrong, I would prefer to use 
names that better describe the property's function.
Let me explain with an example: the rows in the import matcher can have 3 
colors (currently red, yellow or green). These colors support the state of 
each line (unmatched, partially/potentially matched, matched? This may not be 
the exact state meanings).
The name of the class you have chosen describes which property gets changed to 
what. That's 1) redundant, 2) little informative and 3) restrictive. The 
property itself already holds the information (hence redundant), it doesn't 
tell the user why this property is changed (little informative) and will make 
the user hesitate to change it to anything else than a red background 
(restrictive). What if a theme designer decided a better approach to making 
this distinction would be to use a different font ? So rather than making 
class names describing which property is changed to what ("background color 
should be red") the class names should describe its function. In this 
particular case the class names could have become: "no-match", "partial-
match", "full-match". Feel free to use even better names if my interpretation 
of their function is incorrect.

Those are my thoughts so far on css.

What do you think of this ?

Geert

[1] https://developer.gnome.org/gtk3/stable/GtkStyleContext.html
[2] This is just a random example. This class may not provide the right style 
at all.
[3] https://git.gnome.org/browse/gtk+/tree/gtk/gtktreeview.c?h=3.10.9#n4521