GTK+ - ArchWiki

# GTK+

Related articles

- Uniform Look for Qt and GTK Applications
- Qt
- GNU Project
- GTK+/Development

From the GTK+ website:

  GTK+, or the GIMP Toolkit, is a multi-platform toolkit for creating graphical user interfaces. Offering a complete set of widgets, GTK+ is suitable for projects ranging from small one-off tools to complete application suites.

GTK+, The GIMP Toolkit, was initially made by the GNU Project for the GIMP but is now a very popular toolkit with bindings for many languages. This article will explore the tools used to configure the GTK+ theme, style, icon, font and font size, and also detail manual configuration.

## Configuration programs

These GUI programs allow theme selection and at least customising of a font. They generally overwrite the `~/.gtkrc-2.0` file.

- LXAppearance — A configuration tool from the LXDE project, which requires no other parts from LXDE or other desktop environment. More flexible customisation than the other programs.

  http://wiki.lxde.org/en/LXAppearance || lxappearance

- gtk-chtheme — Originally derived from GTK+ Theme Switch

  http://plasmasturm.org/code/gtk-chtheme/ || gtk-chtheme

- GTK Theme Switch —

  http://muhri.net/nav.php3?node=gts || gtk-theme-switch2

- GTK Preference Tool —

  http://gtk-win.sourceforge.net/home/index.php/Main/GTKPreferenceTool || gtk2_prefs

See also Uniform Look for Qt and GTK Applications#Changing styles in each toolkit.

## Themes

Note: As `~/.gtkrc-2.0` and other user theme files are not read by other accounts, the custom theme will not apply to X applications run as root. Possible solutions include:

- Create symlinks, e.g

    # ln -s /home/USER/.gtkrc-2.0 /root/.gtkrc-2.0

- Adjust the theme as root

    # gksu lxappearance

- Use a settings daemon (this is what most desktop environments do). A desktop-agnostic variant using XSETTINGS is available in the AUR under xsettingsd-git.

### GTK+ 1.x

There are a number of GTK+ 1.x themes in the AUR: search for gtk-theme. A good start is gtk-smooth-engine.

Most major desktop environments provide tools to configure the GTK+ theme, icons, font and font size.

Alternatively, use gtk-theme-switch2. Run it with the `switch` command.

### GTK+ 2.x

There are a number of GTK+ 2.x themes in the AUR: search for gtk2-theme. A good start is gtk-engines which includes the popular Clearlooks theme.

Most major desktop environments provide tools to configure the GTK+ theme, icons, font and font size.

Alternatively, GTK+ settings can be configured manually by editing `~/.gtkrc-2.0`. A list of GTK+ settings can be found in the GNOME library. To manually change the GTK+ theme, icons, font and font size, add the following to `~/.gtkrc-2.0`:

    ~/.gtkrc-2.0

    gtk-icon-theme-name = "[name-of-icon-theme]"
    gtk-theme-name = "[name-of-theme]"
    gtk-font-name = "[font-name] [size]"

For example:

    ~/.gtkrc-2.0

    gtk-icon-theme-name = "Tango"
    gtk-theme-name = "Murrine-Gray"
    gtk-font-name = "DejaVu Sans 8"

Note: The above example requires the packages ttf-dejavu, tangerine-icon-theme, gtk-engine-murrine from the official repositories, and gtk-theme-murrine-collection from the AUR.

Another example:

    ~/.gtkrc-2.0

    # GTK theme
    include "/usr/share/themes/Clearlooks/gtk-2.0/gtkrc"

    # Font
    style "myfont" {
        font_name = "DejaVu Sans 8"
    }
    widget_class "*" style "myfont"
    gtk-font-name = "DejaVu Sans 8"

    # Icon theme
    gtk-icon-theme-name = "Tango"

    # Toolbar style
    gtk-toolbar-style = GTK_TOOLBAR_ICONS

Note:

- The icon theme name is the name defined in the theme's index file, not the name of its directory.
- Valid toolbar styles are `GTK_TOOLBAR_ICONS`, `GTK_TOOLBAR_TEXT`, `GTK_TOOLBAR_BOTH`, and `GTK_TOOLBAR_BOTH_HORIZ`.
- If you edit your `.gtkrc-2.0` file, only newly started applications will display the changes.

### GTK+ 3.x

Note: As of GTK+ 3.14, Adwaita has replaced Raleigh as the default GTK+ theme. See [1].

To start with, you may wish to install the gnome-themes-standard package which provides Adwaita - the standard theme for GNOME with support for both GTK+ 2 and GTK+ 3.

In general, if a selected theme has support for both GTK+ 2 and GTK+ 3, the theme will be applied to all GTK+ 2 and GTK+ 3 applications. If a selected theme has support for only GTK+ 2, it will be used for GTK+ 2 applications and the default GTK+ theme will be used for GTK+ 3 applications. If the selected theme has support for only GTK+ 3, it will be used for GTK+ 3 applications and the default GTK+ theme will be used for GTK+ 2 applications. Thus for application theme consistency, it is best to use a theme which has support for both GTK+ 2 and GTK+ 3.

Most major desktop environments provide tools to configure the GTK+ theme, icons, font and font size. If you use GNOME, use GNOME Tweak Tool: install gnome-tweak-tool. If you use Xfce, use the Appearance tool: go to Settings > Appearance.

If you prefer not to install a theme manager at all, your theme can be set manually in `$XDG_CONFIG_HOME/gtk-3.0/settings.ini` (this is usually `~/.config/gtk-3.0/settings.ini`). An example `settings.ini` file:

    $XDG_CONFIG_HOME/gtk-3.0/settings.ini

    [Settings]
    gtk-application-prefer-dark-theme = false
    gtk-theme-name = Zukitwo
    gtk-fallback-icon-theme = gnome
    gtk-icon-theme-name = [icon theme name]
    gtk-font-name = [font name] [font size]

A full example of a custom theme as converted from GTK+ 2.x to GTK+ 3.x by lxappearance:

    $XDG_CONFIG_HOME/gtk-3.0/settings.ini

    [Settings]
    gtk-theme-name=TraditionalOk
    gtk-icon-theme-name=Fog
    gtk-font-name=Luxi Sans 12
    gtk-cursor-theme-name=mate
    gtk-cursor-theme-size=24
    gtk-toolbar-style=GTK_TOOLBAR_BOTH_HORIZ
    gtk-toolbar-icon-size=GTK_ICON_SIZE_LARGE_TOOLBAR
    gtk-button-images=1
    gtk-menu-images=1
    gtk-enable-event-sounds=0
    gtk-enable-input-feedback-sounds=0
    gtk-xft-antialias=1
    gtk-xft-hinting=1
    gtk-xft-hintstyle=hintslight
    gtk-xft-rgba=rgb

If it still does not change, delete old `gtk-3.0` folder in `$XDG_CONFIG_HOME` and copy `gtk-3.0` folder from /path/to/theme to `$XDG_CONFIG_HOME`. Example:

    $ rm -r ~/.config/gtk-3.0/
    $ cp -r /usr/share/themes/Zukitwo/gtk-3.0/ ~/.config/

After this, you need to set the same theme in your DE's appearance configuration tool. There are only a few themes which provide a uniform look for GTK+ 3.x and GTK+ 2.x apps. A few examples:

1. Adwaita (part of gnome-themes-standard)
2. Clearlooks-Phenix (AUR: clearlooks-phenix-gtk-theme)
3. Newlooks for GTK+ 3 and Clearlooks for GTK+ 2
4. Zukitwo (zukitwo-themes)
5. Elegant Brit
6. Atolm
7. Hope
8. OMG

Note:

- Some themes may require librsvg to display correctly, but not all specify it as a dependency. Try installing it if the chosen theme looks broken.
- There probably are other themes. Some of these themes are available in the AUR. Also, some of them are not usable as-is for displaying a GTK+ 2.x panel (light text over light background), so you need to use the provided panel background.

You could find what themes installed on your system have both an GTK+ 2.x and GTK+ 3.x version by using this command (does not work with names containing spaces):

    find $(find ~/.themes /usr/share/themes/ -wholename "*/gtk-3.0" | sed -e "s/^\(.*\)\/gtk-3.0$/\1/")\
    -wholename "*/gtk-2.0" | sed -e "s/.*\/\(.*\)\/gtk-2.0/\1"/

### GTK+ and Qt

If you have GTK+ and Qt (KDE) applications on your desktop then you know that their looks do not blend well. If you wish to make your GTK+ styles match your Qt styles please read Uniform Look for Qt and GTK Applications.

### GTK+ and HTML with Broadway

The GDK Broadway backend provides support for displaying GTK+ applications in a web browser, using HTML5 and web sockets. [2]

When using broadwayd, specify the display number to use, prefixed with a colon, similar to X. The default display number is 1.

    $ display_number=:5

Start it.

    $ broadwayd $display_number

Port Used on default

    port = 8080 + ($display_number - 1)

Point your browser to http://localhost:port

To Start apps

    $ GDK_BACKEND=broadway BROADWAY_DISPLAY=$display_number <<app>>

Alternatively can set address and port

    $ broadwayd --port $port_number --address $address $display_number

## Configuration

Note: See the GtkSettings properties in the GTK+ programming reference manual for the full list of GTK configuration options.

Depending on GTK version, these files are either located in `~/.config/gtk-3.0/settings.ini` or `~/.gtkrc-2.0`. System settings are applied in `etc/gtk-version`.

### Keyboard shortcuts

Note: This setting is deprecated since GTK 3.10.

Keyboard shortcuts (otherwise known as accelerators in GTK) may be changed by hovering the mouse over the respective menu item, and pressing the desired key combination. To enable this feature, set:

    gtk-can-change-accels = 1

### GNOME menu delay

Note: This setting is deprecated since GTK 3.10.

This setting controls the delay between pointing the mouse at a menu and that menu opening. This delay is measured in milliseconds.

    gtk-menu-popup-delay = 0

### Reduce widget sizes

If you have a small screen or you just do not like big icons and widgets, you can resize things easily. To have icons without text in toolbars, use

    gtk-toolbar-style = GTK_TOOLBAR_ICONS

To use smaller icons, use a line like this:

    gtk-icon-sizes = "panel-menu=16,16:panel=16,16:gtk-menu=16,16:gtk-large-toolbar=16,16\
    :gtk-small-toolbar=16,16:gtk-button=16,16"

Or to remove icons from buttons completely:

    gtk-button-images = 0

You can also remove icons from menus:

    gtk-menu-images = 0

See also [3] and [4].

### Disable recent documents

To disable storage of recently opened files, add:

    gtk-recent-files-max-age=0

## Troubleshooting

### Client-side decorations

Note: gtk3-noforcedcsd from the AUR disables client-side decorations through the `GTK_DISABLE_CSD` variable. [5]

GTK 3.12 introduced client-side decorations, which move the title-bar away from the window manager. This may present issues such as double title-bars, no title-bar at all or double shadows with compositing enabled.

To remove the shadow and gap around windows (for example in combination with a tiling window manager), create the following file:

    ~/.config/gtk-3.0/gtk.css

    .window-frame, .window-frame:backdrop {
     box-shadow: 0 0 0 black;
     border-style: none;
     margin: 0;
     border-radius: 0;
    }

    .titlebar {
     border-radius: 0;
    }

To adjust the buttons in the header bar, use the `gtk-decoration-layout` setting. [6] The below examples removes all buttons:

    ~/.config/gtk-3.0/settings.ini

    gtk-decoration-layout=menu:

### Enable cedilla ç/Ç instead of ć/Ć

This article or section needs language, wiki syntax or style improvements.

Reason: please use the first argument of the template to provide a brief explanation. (Discuss)

When you select the keyboard layout "U.S., alternative international" in Settings --> Keyboard --> Layout to enable accents, the typical combination for the cedilla ' + c results in ć instead of ç.

To change this suffice edit files gtk.immodules for gtk-2.0 and immodules.cache for gtk-3.0 in line that contains "cedilla" adding both "en" in the list "az:ca:co:fr:gv:oc:pt:sq:tr:wa" but in alphabetical order, staying that way in /etc/gtk-2.0/gtk.immodules

    "/usr/lib/gtk-2.0/2.10.0/immodules/im-cedilla.so"
    "cedilla" "Cedilla" "gtk20" "/usr/share/locale" "az:ca:co:en:fr:gv:oc:pt:sq:tr:wa"

and this in /usr/lib/gtk-3.0/3.0.0/immodules.cache

    "/usr/lib/gtk-3.0/3.0.0/immodules/im-cedilla.so"
    "cedilla" "Cedilla" "gtk30" "/usr/share/locale" "az:ca:co:en:fr:gv:oc:pt:sq:tr:wa"

Then, do

    # echo "export GTK_IM_MODULE=cedilla" >> /etc/environment

Done. Simply just close and reopen the gtk programs like gedit.

## See also

- The official GTK+ website
- Wikipedia article about GTK+
- GTK+ 2.0 Tutorial
- GTK+ 3 Reference Manual
- gtkmm Tutorial
- gtkmm Reference Manual

Category:

- Widget Toolkits