GTK3

Since GnuCash 3.0 the GTK3 library is used for the Graphical User Interface (GUI). Older versions were using GTK2.

Many parts of GnuCash's appearance—and in rare cases behaviour—depend on the theme selected in your desktop environment.

This page contains instructions on how to customize GTK3 appearance and behavior.

For more information about the location of the configuration files, see Configuration Locations.

Cascading Style Sheets (CSS)

GnuCash since version 3 uses a new version of the GTK framework with a completely new styling mechanism based on Cascading Style Sheets (CSS). For Windows users, this has unfortunately rendered the theming tool that we used to distribute useless and sadly there isn't a replacement available that works with GTK3.

Fortunately, GTK's CSS is fairly simple. This page will explain the basics and provide some examples for commonly-requested changes.

For reference, there is a sample GTK css file available at: GTK css example

See also

CSS

Tools for Managing GTK Settings

Query GSettings

Some theme information is kept in gsettings and can be queried with gtk-query-settings. For example

gtk-query-settings theme

will return all of the settings whose name includes the word "theme". It is usually in a package gtk3-tools.

Using the GTK Inspector

GTK has a built in Inspector that you can enable by setting environment varialbe GTK_DEBUG to interactive. There are several ways to do this. The most straight-forward on linux is launching GnuCash from the command line with

GTK_DEBUG=interactive path/to/gnucash

For flatpak the command is slightly different. See GTK Inspector on Flatpak.

What will work on all platforms is to create file named environment.local in directory gnucash of the system-wide configuration directory with this contents:

[Variables]
GTK_DEBUG=interactive

You will likely need administrator privileges on your system to do this though.

It's quite useful for poking and prodding various bits of GnuCash to see what styles apply to which controls and to allow you to change things and to see the results immediately.

Note: You must have GTK+3 installed to use the Inspector.

• On macOS, you can use Homebrew to install GTK+3. Install Homebrew and then issue the command

  brew install gtk+3
  

Linux Desktop Environments

They have often a tool in their System Settings to adjust the appearance of all GTK apps per user:

Gnome

Tweaks is a graphical interface for advanced GNOME 3 settings. It was previously known as Gnome Tweak Tool.

KDE

kde-gtk-config is a GTK2 and GTK3 Configurator for KDE.

Behavior

Certain aspects of widget behavior can also be customized.

Restoring Visible Mnenomics

GTK Mnemonics are underlined characters in a label, used for keyboard navigation. Examples of labels which may include a mnemonic are the text on a button, the label of a field, and the text in a menu line. The mnemonic is activated by pressing the mnenomic activator key (Alt for Linux and Windows, Command for macOS) at the same time as the underlined character.

Since GTK 3.10, the underlines of the mnenomics are only visible after pressing the mnenomic activator key.

Scrollbars

The behavior of the scrollbars can be customized. Compared to GTK2, if you now click above (or below) the current position bar in the scrollbar, it takes you to the place in the window which is proportional to where in the scroll bar you click, rather than up (or down) 1 screen full. This can be adjusted by using below instruction in the GTK settings file GTK_CONFIG_HOME/settings.ini:

[Settings]

# Use Windows style PgUp/PgDn scrollbars
gtk-primary-button-warps-slider=false

Menu Keyboard Shortcuts

Keyboard shortcuts can be assigned to actions in GnuCash application. A more detailed information is available on Keyboard Shortcuts.

To assign a custom shortcut, do the following:

With GnuCash *not running* open GNC_DATA_HOME/accelerator-map in any text editor and find the line with the desired command, i.e. for double-line in the register view use

 ;(gtk_accel_path "<Actions>/GncPluginPageRegisterActions/ViewStyleDoubleLineAction" "")

If, for some reason, the line is missing in the accelerator-map file, simply copy the line above into the file. Remove the ';' at the beginning and insert whatever shortcut you like between the last set of double quotes. Save the file.

The Ctrl key is referenced as <Primary>. For example, if you want to use Ctrl+2 for a shortcut, set the value to "<Primary>2".

The next time you open GnuCash, you will be able to use the shortcut key to trigger the desired functionality. The relevant menu item will reflect this fact by displaying the shortcut key next to the assigned action's name.

For full list of possible actions see source code on GitHub.

Key Bindings

Customizing key bindings is done by editing (or creating if needed) the file GNC_CONFIG_HOME/gtk-3.0.css in the GnuCash configuration directory.

For example, to add a new binding so that the F11 key is bound to the copy-clipboard action and the F12 key is bound to the paste-clipboard action and existing keybindings for these actions remain unchanged, add something like this to gtk-3.0.css:

/* Bind F11 to Copy, F12 to Paste */
@binding-set F11CopyF12Paste
{
  bind "F11" { "copy-clipboard" () };
  bind "F12" { "paste-clipboard" () };
}

entry
{
  -gtk-key-bindings: F11CopyF12Paste;
}

If you like Emacs-style keybindings you can add,

gtk-key-theme-name = Emacs

to your settings.ini.

macOS only

Unfortunately for macOS users that setting is hard-coded to the Mac keybindings theme for Quartz (macOS Native) screens. Fortunately, there's a fairly painless workaround (and this way you get both the emacs and the Mac bindings which is how most native apps actually work):

Copy GnuCash.app/Contents/share/themes/Emacs/gtk-3.0/gtk-keys.css to

~/Library/Application Support/Gnucash config gtk-3.0. If you have no other customizations, just name it gtk.css. If you already have a gtk.css there, add to it

@import url("gtk-keys.css");

Typefaces

There are two ways of setting a default font and size for GnuCash.

The first sets an option in GTK's settings.ini for all GTK applications (GIMP etc.),

the other uses css to accomplish the same for GnuCash only.

• If neither you nor a program changed the default values before, the files mentioned in this section will not exist. In this case just create them as pure text files and with normal file access rights.

The examples below with both set the default font to Arial and font size to 14.

Via settings.ini

Create if necessary and add the following line to GTK_CONFIG_HOME/settings.ini:

[Settings]
gtk-font-name=Arial 14

General notes

• In settings.ini, lines beginning with a # and blank lines are considered comments.
• If the file exists and has a [Settings] line just add the font line beneath it.
• Setting font family via settings.ini doesn't work on macOS and Microsoft Windows. Use CSS to set font family on those operating systems.

Via css

Create if necessary and add the following to GNC_CONFIG_HOME/gtk-3.0.css:

* {
  font: 14pt arial, sans-serif;
}

If you see some or all non-ASCII characters displayed as a missing-glyph character, often some variation of a white square, it means that those characters aren't supported by the font you've selected. You'll need to find a font family for your platform that better supports your language.

Note: Gtk on Microsoft Windows will not set the font family globally with the '*' css selector. Use #gnc-id-main-window instead.

For Simplified Chinese one user found

#gnc-id-main-window {
  font-family: Microsoft YaHei;
  font-size: 14pt;
}

worked well.

Visual Styling

As GTK3 uses Cascading Style Sheets (CSS) for themes this is fairly easy to resolve by styling the GTK applications manually or using one of myriad available graphical themes. This is easily done by placing a custom CSS file at the correct location, depending on your system, or downloading and using a custom-made theme. N.B. css files must be plain ascii text. Be sure to use a suitable editor; if you use a word processor be sure to save the file as plain text. Most Windows users can use Notepad, while macOS users can use TextEdit but must select File>Make Plain Text when first creating the file.

Register Appearance

The GnuCash registers use a yellow/green theme by default for register windows. Users must disable this default theme in order to change register appearance.

To override this, one first has to disable this custom theme by disabling "Use GnuCash built-in color theme" in the GnuCash Preferences.

Next, create or change the GTK css file for further styling tweaks. The location and name of the resource file is explained in Configuration Locations.

For adjusting register colors, you can override the relevant css style definitions in your own GTK3 resource file. See GTK css example for example settings.

Manual Styling using CSS file

The comprehensive GTK+ CSS Overview, as it relates to GTK, is available at Gnome Developer web site.

Configuration tools

Various Linux distributions provide custom tools for managing themes. There is a nice overview of graphical tools available, depending on the desktop environment at archlinux.

A sample GnuCash CSS file can be found below:

• GTK 3 CSS

For extra info, you can also check these low-level customizations:

gnucash 4 or more recent

gnucash.css

gnucash 3 with gtk 3.20 or more recent

gnucash-320

gnucash 3 with gtk older than 3.20

gnucash-310

Note that these contain the @ variables, as explained in the CSS customization overview, Colors section.

To precisely locate the UI elements for customization, you can use the GTK Inspector tool.

CSS rules to customize the GnuCash appearance should be stored in GNC_CONFIG_HOME/gtk-3.0.css.

Note that GnuCash will never create this file for you but you can to create it yourself as a plain text file. If you are on Linux(various), macOS(TextEdit.app) or Windows10(Notepad), your default text editor will work fine to create plain text files. If you are on an older version of Windows, you'll need to use something other than Notepad that can save files with Unix/Linux line endings. Do not use Rich Text Editors or formats, or any word processor that can't save as plain text.

You can write your own css rules or copy them from existing themes. The #Themes section below has a few links to websites where you can find sample themes.

Related wiki entries:

• FAQ#Q: How do I change the register colors?
• FAQ#Q: Where can I find the gtk resource file?

Custom GnuCash Styles

To style the register you can use css rules like below:

*.register-primary {
  color: red;
}

where

*.register-header => header bar at top of sheet

*.register-primary => primary (dark-background) lines

*.register-secondary => secondary (light-background) lines

*.register-split => split lines

cursor entry => the cell containing the cursor

*.register-foreground => setting the colour for this selector will paint all the register text in that colour.

*.register-cursor => the currently selected row in the register

If you want to apply a change to the entire register sheet:

sheet {
  font: 12px;
}

Sample GnuCash Selectors (CSS Nodes)

Chart of Accounts Tab:

This sheet has an ID of #account_tree which affects the entire sheet below the column headers.

Thus:

#account_tree {
  font-size: 1.2em;
}

will increase the font size by 20% for all of the account names and their related right-hand columns.

If you want to color the area behind and around the Totals Bar:

.GncAccountPage {
  background-color: lightgrey;
}

If you want to style the column headers, use the following selector for the full header bar:

#account_tree header button{
}

If you just want to apply font/text rules to the header labels themselves, use:

#account_tree header label {
}

Labels of Toolbar Buttons

Starting with GnuCash 3.3 the toolbar buttons will have their labels enabled. This will widen the buttons, so on some screens that means not all buttons will be visible any more. If you prefer to have no labels under the buttons, you can use the following css snippet to hide them:

toolbar toolbutton label
{
  font-size: 0;
}

which is bad style. Better use

gtk-toolbar-style=0

in your settings.ini.

Toolbar Button spacing

The toolbar buttons are visually very wide apart. This appears to be a conscious design choice in the Gtk default Adwaita theme. If you prefer to have them closer together to fit more buttons on the toolbar, you can use the following snippet to reduce the spacing. There are two css nodes that together make up for the total spacing. Both are set to 8px by default. The snippet below will reduce both of them to 4px. You can reduce them even further to your taste:

toolbar toolbutton button
{
    padding-left: 4px;
    padding-right: 4px;
}

toolbar toolbutton label
{
    padding-left: 4px;
    padding-right: 4px;
}

Scrollbar adjustments

Some sample settings to adjust the scrollbar:

scrollbar {
    /* Just in case another file disabled them */
    -GtkScrollbar-has-backward-stepper: 1;
    -GtkScrollbar-has-forward-stepper: 1;
}

scrollbar slider {
    /* Size of the slider */
    min-width: 12px;
    min-height: 12px;
    border-radius: 22px;

    /* Padding around the slider */
    border: 5px solid transparent;
}

Disable the overlay scrolling

GTK 3.0 has scrollbar overlap setting (default set to Boolean true) which may cause last entry in a list to show behind the scrollbars (specifically on horizontal ones) making it difficult to click on it when not disabled. It can be disabled by editing GTK_CONFIG_HOME/settings.ini file. Create it with a text editor if it does not exist.

[Settings]
gtk-overlay-scrolling = false

Dropdown List of Accounts Transparency Problem

There is a problem with some Linux themes, such as the Ubuntu yaru theme, where the account list dropdown in the register Transfer field has a transparent background in the line under the mouse pointer. This makes it hard to read. See Bug 797493.

The following should fix this:

/* GnuCash 4.x Fix transparent background in register Transfer dropdown Bug 797493 */
gnc-id-sheet-list {
  background-color: @theme_bg_color;
}

Or

/* GnuCash 3.x Fix transparent background in register Transfer dropdown Bug 797493 */
register sheet widget {
  background-color: @theme_bg_color;
}

KDE Register Input Field Black on Dark Background Problem

There is a problem with some Linux themes, such as the Ubuntu breeze-dark theme on the KDE Plasma desktop, where the current register field is black on a dark background. This makes it hard to read. See Bug 798202. This problem is fixed in GnuCash 4.6.

The following should fix this:

/* GnuCash 4.x Fix register black on dark background Bug 798202 */
.gnc-class-register-foreground.flat {                                                                                                                                                     
    background-color: white;                                                                        
}

Or

/* GnuCash 3.x Fix register black on dark background Bug 798202 */
.header-color {
  background-color: #363636;
  color: #c8c8c8;
}

.primary-color {
  background-color: #383838;
}

.primary-color:disabled {
  background-color: #383838;
}

.secondary-color {
  background-color: #323232;
}

.secondary-color:disabled {
  background-color: #323232;
}

.split-color {
  background-color: #474747;
}

.split-color:disabled {
  background-color: #53728e;
}

.cursor-color {
  background-color: #383838;
  color: #c8c8c8;
}

cursor entry {
  background-color: #383838;
  color: #c8c8c8;
}

Sample Style Properties

This is a list of the most likely desired properties you can change in GnuCash with Gtk+3 as of version 3.22. Note, not all properties apply to all selectors (nodes). Properties may also not apply as expected compared to web CSS and may or may not cascade to child nodes.

• background-blend-mode
• background-clip
• background-color
• background-image
• background-position
• background-repeat
• background-size

• border-bottom-color
• border-bottom-left-radius
• border-bottom-right-radius
• border-bottom-style
• border-bottom-width

• border-image-repeat
• border-image-slice
• border-image-source
• border-image-width

• border-left-color
• border-left-style
• border-left-width

• border-right-color
• border-right-style
• border-right-width

• border-top-color
• border-top-left-radius
• border-top-right-radius
• border-top-style
• border-top-width

• box-shadow

• color

• font-family
• font-size
• font-stretch
• font-style
• font-variant (does not seem to work)
• font-weight

• letter-spacing

• margin-bottom
• margin-left
• margin-right
• margin-top

• min-height
• min-width

• opacity

• outline-color
• outline-offset
• outline-style
• outline-width

• padding-bottom
• padding-left
• padding-right
• padding-top

• text-decoration-color
• text-decoration-line
• text-decoration-style

• text-shadow

Themes

At first a warning about theming: restyling apps at scale.

You can use a predefined GTK3 theme. Note that applying a custom theme will affect all the gtk3-based applications on your system!

Short summary:

1. download an appropriate GTK3 theme from www.gnome-look.org or other sites
2. copy the theme into a directory where GTK3 looks for themes (see below)
3. create or adjust a settings.ini file to instruct GTK3 to use this theme

Some sites which host custom GTK3 themes:

• Gnome Look
• Deviant Art

Below is a slightly longer explanation with platform dependent remarks:

1. Go to the gnome-look.org website.
2. Click the GTK3 Themes link, not the GTK2 one.
3. Select a theme you like. Alternatively you can search for keywords (like "dark") in the top right corner and then filter on "GTK3 Theme category".
4. If you have found a theme you like, download the proper file (in the files section of the theme page). Note depending on your operating system you may not be able to open all theme files. There are, for example, .deb archives which are specifically targeted at the Debian linux distribution and derivates such as Ubuntu. While Ubuntu and Debian users can install those themes via their package manager these themes are not useful for other platforms.
   Theme files ending with .zip, .tar.gz or tar.xz are likely installable on all platforms, although you may have to find a proper application to extract them.
   On Windows 7-Zip is a good candidate, linux users can probably extract the files directly from their file manager.
   Let's take the theme "Eye-friendly Dark RBC" as an example (it's not the best theme but it can serve as an example). The file to download is Eye-friendly-Dark-RBC.tar.gz.
5. Extract this file using an appropriate tool. This should give you a directory named Eye-friendly-Dark-RBC.
6. Move this directory to USER_CONFIG_HOME/themes. Note on Windows you'll need to use the %LOCALAPPDATA% variant as we're adjusting

GTK3's configuration.

1. Next tell GTK to load this theme.

Linux users can probably most easily do this by install the "Gnome Tweak Tool" on their platform and select the new theme there. The manual method is this: Create a file named GTK_CONFIG_HOME/settings.ini.

The contents of this file should be

[Settings]
gtk-theme-name=Eye-friendly-Dark-RBC

And that's it. Note the name is the name of the directory as you put in the themes directory. The next time you start GnuCash it should pick up this theme.

A few extra notes:

• The default GTK3 theme is called "Adwaita".
• On linux there's a second default theme called "Adwaita-dark" which should also give you a dark themed GnuCash. Unfortunately, this doesn't work on Windows out-of-the-box but there is a workaround. See under #Dark Themes below.
• If you're adventurous you can probably also play with customized icon themes which you find on the gnome-look.org website. These themes should be installed in the icons directory next to the themes directory. And to activate them you can add gtk-icon-theme-name=<directory name> in settings.ini.
• A list of GTK settings that can be adjusted via settings.ini can be found at GTK Settings page.

Dark Themes

It may be possible to get the default dark theme on Windows using the following technique:

• Create/modify GTK_CONFIG_HOME/settings.ini.
• Add this contents:

[Settings]
gtk-application-prefer-dark-theme=true

If you then want to adjust highlighted text and negative numbers, insert

/* Negative number color */
.gnc-class-negative-numbers {
  color: shade(@negative-numbers, 1.9);
}
gnc-id-sheet .gnc-class-negative-numbers {
  color: @negative-numbers;
}
/* Highlight Text */
.gnc-class-highlight {
  color: shade(blue, 1.6);
}

into your gtk-3.0.css.

If this doesn't work an alternative option is to install a suitable theme as described above. A couple of suggestions for decent dark themes that may apply well to GnuCash:

• Leather-Dark theme,
• Eye-friendly Dark RBC Theme - fully-working pleasant dark theme.

The adventurous could of course also try and create such a theme from scratch. Below are a few pointers to get started:

• gtk-3.0.css Black Theme,
• gtk-3.0.css settings that go well with a dark theme (i.e. Leather Dark).

Ongoing work on a Dark Solarized theme for use with GnuCash 4.0+ can be found here:

• gtk-3.0.css Dark Solarized theme CSS
• screenshot Dark Solarized theme screenshot

Transparent Dropdown Backgrounds

Some themes attempt to make elements translucent and screw it up. We've had a number of reports of these efforts failing spectacularly, especially on Ubuntu. The symptom is that a drop-down list will have a transparent background either for the selected item or for the whole list box. As one might imagine this make finding the item one wants rather difficult.

The solution is to override the theme's background. The following snippets should be added to the GNC_CONFIG_HOME/gtk-3.0.css. The Gtk one in GTK_CONFIG_HOME/gtk.css is loaded before the theme and will be overridden by loading the theme.

For Ubunutu's

Yaru theme on GnuCash 3.x

register sheet widget {
   background-color: @theme_bg_color;
   }

Yaru on GnuCash 4.x

gnc-id-sheet-list {
   background-color: @theme_bg_color;
   }

KDE Breeze theme on 4.x

treeview.view:hover {
   background-color: @theme_selected_bg_color_breeze;
   }

On GnuCash 3.x you'd change the selector to register sheet widget like the Yaru example- Other themes may not have @theme_bg_color or @theme_selected_bg_color. You'll have to explore your themes css files to find its equivalent. If you can't find the right one you can pick a standard css color like white.

Additional Links

• Windows page contains some instructions on customization of visual appearance.

---