GTK3

From GnuCash
Revision as of 17:53, 9 July 2018 by Fell (talk | contribs) (→‎Basics: GTK3 Tools)
Jump to: navigation, search

With version 3.0, GnuCash has upgraded to the GTK3 library from GTK2.

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

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

Basics

Unlike GTK2, as noted in bug 791823, the GTK theming tool is not being distributed with GTK3. Probably you can at least query your current GTK settings with 

gtk-query-settings [PATTERN]

It is usually in a package gtk3-tools.

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.

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:

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

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

Custom GnuCash Styles

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

*.register-primary {
  color: red;
}

where

*.register-primary => primary (dark-background) lines
*.register-secondary => secondary (light-background) 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

Themes

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:

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 candiate, 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.
  7. 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.
  • 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: 

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

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:

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

Font Size in Documents

There are two ways of setting a default font for GnuCash. The first sets an option in Gtk's settings.ini, the other uses css to accomplish the same. The examples below with both set the default font to Arial and font size to 14.

Via settings.ini

Add the following line to the Settings section in GTK_CONFIG_HOME/settings.ini: 

[Settings]
gtk-font-name=Arial 14

Note: In settings.ini, lines beginning with a '#' and blank lines are considered comments.

Via css

Use the following style in your GNC_CONFIG_HOME/gtk-3.0.css<tt> file: 

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

Behaviour

Certain aspects of widget behaviour can also be customized.

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

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. 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");

Scrollbars

The behaviour 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 scrollbars
gtk-primary-button-warps-slider=false

Additional Links

  • Windows page contains some instructions on customization of visual appearance.
Retrieved from "https://wiki.gnucash.org/wiki/index.php?title=GTK3&oldid=14242"