GTK CSS Overview

GTK CSS Overview — The language used for style information in GTK

CSS in GTK

This chapter describes how GTK uses CSS for styling and layout. It is not meant to be an explanation of CSS from first principles, but focuses on listing supported CSS features and differences between Web CSS and GTK.

There is plenty of introductory documentation available that can be used to learn about CSS in general. In the tables below we include links to the official specs that can be used to look up the definition of individual selectors and properties.

CSS nodes

GTK applies the style information found in style sheets by matching the selectors against a tree of nodes. Each node in the tree has a name, a state and possibly style classes. The children of each node are linearly ordered.

Every widget has one or more of these CSS nodes, and determines their name, state, style classes and how they are layed out as children and siblings in the overall node tree. The documentation for each widget explains what CSS nodes it has.

Example 5. The CSS nodes of a GtkScale

1
2
3
4
5
6
7
8
9
10
11
12
13
scale[.fine-tune]
├── marks.top
   ├── mark
   
   ╰── mark
├── trough
   ├── slider
   ├── [highlight]
   ╰── [fill]
╰── marks.bottom
    ├── mark
    
    ╰── mark


Selectors

Selectors work very similar to the way they do on the web.

All widgets have one or more CSS nodes with element names and style classes. When style classes are used in selectors, they have to be prefixed with a period. Widget names can be used in selectors like IDs. When used in a selector, widget names must be prefixed with a # character.

Table 1. GTK CSS Selectors

Pattern Reference Notes
* CSS Selectors Level 3  
E CSS Selectors Level 3  
E.class CSS Selectors Level 3  
E#id CSS Selectors Level 3 GTK uses the widget name as ID
E:nth-child(nth-child) CSS Selectors Level 3  
E:nth-last-child(nth-child) CSS Selectors Level 3  
E:first-child CSS Selectors Level 3  
E:last-child CSS Selectors Level 3  
E:only-child CSS Selectors Level 3 Equivalent to E:first-child:last-child
E:link, E:visited CSS Selectors Level 3 Corresponds to GTK_STATE_FLAG_LINK and GTK_STATE_FLAGS_VISITED
E:active, E:hover, E:focus CSS Selectors Level 3 Correspond to GTK_STATE_FLAG_ACTIVE, GTK_STATE_FLAG_PRELIGHT, GTK_STATE_FLAGS_FOCUSED
E:focus-within CSS Selectors Level 4 Set on all ancestors of the focus widget, unlike CSS
E:focus-visible CSS Selectors Level 4 Set on focus widget and all ancestors, unlike CSS
E:disabled CSS Selectors Level 3 Corresponds to GTK_STATE_FLAG_INSENSITIVE
E:checked CSS Selectors Level 3 Corresponds to GTK_STATE_FLAG_CHECKED
E:indeterminate CSS3 Selectors Level 3 Corresponds to GTK_STATE_FLAG_INCONSISTENT
E:backdrop, E:selected   Corresponds to GTK_STATE_FLAG_BACKDROP, GTK_STATE_FLAG_SELECTED
E:not(selector) CSS Selectors Level 3  
E:dir(ltr), E:dir(rtl) CSS Selectors Level 4  
E:drop(active) CSS Selectors Level 4  
E F CSS Selectors Level 3  
E > F CSS Selectors Level 3  
E ~ F CSS Selectors Level 3  
E + F CSS Selectors Level 3  

GTK CSS Properties

GTK supports CSS properties and shorthands as far as they can be applied in the context of widgets, and adds its own properties only when needed. All GTK-specific properties have a -gtk prefix.

Basic types

All properties support the following keywords: inherit, initial, unset, with the same meaning as defined in the CSS Cascading and Inheritance spec.

The following units are supported for basic datatypes:

Length

px, pt, em, ex, rem, pc, in, cm, mm, calc()

Percentage

%, calc()

Angle

deg | grad | turn, calc()

Time

s | ms, calc()

Length values with the em or ex units are resolved using the font size value, unless they occur in setting the font-size itself, in which case they are resolved using the inherited font size value.

The rem unit is resolved using the initial font size value, which is not quite the same as the CSS definition of rem.

The calc() notation adds considerable expressive power. There are limits on what types can be combined in such an expression (e.g. it does not make sense to add a number and a time). For the full details, see the CSS3 Values and Units spec.

A common pattern among shorthand properties (called 'four sides') is one where one to four values can be specified, to determine a value for each side of an area. In this case, the specified values are interpreted as follows:

4 values:

top right bottom left

3 values:

top horizontal bottom

2 values:

vertical horizontal

1 value:

all


Colors

GTK extends the CSS syntax with several additional ways to specify colors.

The first is a reference to a color defined via a @define-color rule in CSS. The syntax for @define-color rules is as follows:

@define-color Name Color

To refer to the color defined by a @define-color rule, prefix the name with @.

GTK also supports color expressions, which allow colors to be transformed to new ones. Color expressions can be nested, providing a rich language to define colors. Color expressions resemble functions, taking 1 or more colors and in some cases a number as arguments.

lighter(Color) produces a brigher variant of Color
darker(Color) produces a darker variant of Color
shade(Color, Number) changes the lightness of Color. The number ranges from 0 for black to 2 for white.
alpha(Color, Number) replaces the alpha value of color with number (between 0 and 1)
mix(Color1, Color2, Number) interpolates between the two colors


Images

GTK extends the CSS syntax for images and also uses it for specifying icons. To load a themed icon, use

-gtk-icontheme(Name)

The specified icon name is used to look up a themed icon, while taking into account the values of the -gtk-icon-theme and -gtk-icon-palette properties. This kind of image is mainly used as value of the -gtk-icon-source property.

Symbolic icons from the icon theme are recolored according to the -gtk-icon-palette property, which defines a list of named colors. The recognized names for colors in symbolic icons are error, warning and success. The default palette maps these three names to symbolic colors with the names @error_color, @warning_color and @success_color respectively. The syntax for defining a custom palette is a comma-separated list of name-color pairs, e.g.

success blue, warning #fc3, error magenta

Recoloring is sometimes needed for images that are not part of an icon theme, and the

-gtk-recolor(uri, palette)

syntax makes this available. -gtk-recolor requires a url as first argument. The remaining arguments specify the color palette to use. If the palette is not explicitly specified, the current value of the -gtk-icon-palette property is used.

GTK supports scaled rendering on hi-resolution displays. This works best if images can specify normal and hi-resolution variants. From CSS, this can be done with

-gtk-scaled(Image1, Image2)

Table 2. GTK CSS Properties

Color and Filter Properties
Name Reference Notes
color CSS Color Level 3  
opacity CSS Color Level 3  
filter CSS Filter Effects Level 1  
Font Properties
font-family CSS Fonts Level 3 defaults to gtk-font-name setting
font-size CSS Fonts Level 3 defaults to gtk-font-name setting
font-style CSS Fonts Level 3  
font-variant CSS Fonts Level 3 only CSS2 values supported
font-weight CSS Fonts Level 3  
font-stretch CSS Fonts Level 3  
font-kerning CSS Fonts Level 3  
font-variant-ligatures CSS Fonts Level 3  
font-variant-position CSS Fonts Level 3  
font-variant-caps CSS Fonts Level 3  
font-variant-numeric CSS Fonts Level 3  
font-variant-alternates CSS Fonts Level 3  
font-variant-east-asian CSS Fonts Level 3  
font-feature-settings CSS Fonts Level 3  
font-variation-settings CSS Fonts Level 4  
-gtk-dpi Number defaults to screen resolution
Font Shorthands
font CSS Fonts Level 3 CSS allows line-height, etc
font-variant CSS Fonts Level 3  
Text Caret Properties
caret-color CSS Basic User Interface Level 3 CSS allows an auto value
-gtk-secondary-caret-color Color used for the secondary caret in bidirectional text
Text Decoration Properties
letter-spacing CSS Text Level 3  
text-decoration-line CSS Text Decoration Level 3 CSS allows overline
text-decoration-color CSS Text Decoration Level 3  
text-decoration-style CSS Text Decoration Level 3 CSS allows dashed and dotted
text-shadow CSS Text Decoration Level 3  
Text Decoration Shorthands
text-decoration CSS Text Decoration Level 3  
Icon Properties
-gtk-icon-source Image, builtin or none used for builtin icons in buttons and expanders
-gtk-icon-theme Theme name icon theme to use with -gtk-icontheme()
-gtk-icon-size Length size used for builtin icons in buttons and expanders
-gtk-icon-style requested, regular or symbolic preferred style for application-loaded icons
-gtk-icon-transform Transform list or none applied to builtin and application-loaded icons
-gtk-icon-palette Color palette, as explained above used to recolor symbolic icons
-gtk-icon-shadow Shadow or none applied to builtin and application-loaded icons
-gtk-icon-filter Filter value list or none applied to builtin and application-loaded icons
Box Properties
transform CSS Transforms Level 2  
min-width CSS Box Model Level 3 CSS allows percentages
min-height CSS Box Model Level 3 CSS allows percentages
margin-top CSS Box Model Level 3 CSS allows percentages or auto
margin-right CSS Box Model Level 3 CSS allows percentages or auto
margin-bottom CSS Box Model Level 3 CSS allows percentages or auto
margin-left CSS Box Model Level 3 CSS allows percentages or auto
padding-top CSS Box Model Level 3 CSS allows percentages
padding-right CSS Box Model Level 3 CSS allows percentages
padding-bottom CSS Box Model Level 3 CSS allows percentages
padding-left CSS Box Model Level 3 CSS allows percentages
Box Shorthands
margin CSS Box Model Level 3 a 'four sides' property
padding CSS Box Model Level 3 a 'four sides' property
Border Properties
border-top-width CSS Backgrounds and Borders Level 3 CSS allows other values
border-right-width CSS Backgrounds and Borders Level 3 CSS allows other values
border-bottom-width CSS Backgrounds and Borders Level 3 CSS allows other values
border-left-width CSS Backgrounds and Borders Level 3 CSS allows other values
border-top-style CSS Backgrounds and Borders Level 3  
border-right-style CSS Backgrounds and Borders Level 3  
border-bottom-style CSS Backgrounds and Borders Level 3  
border-left-style CSS Backgrounds and Borders Level 3  
border-top-right-radius CSS Backgrounds and Borders Level 3  
border-bottom-right-radius CSS Backgrounds and Borders Level 3  
border-bottom-left-radius CSS Backgrounds and Borders Level 3  
border-top-left-radius CSS Backgrounds and Borders Level 3  
border-top-color CSS Backgrounds and Borders Level 3  
border-right-color CSS Backgrounds and Borders Level 3  
border-bottom-color CSS Backgrounds and Borders Level 3  
border-left-color CSS Backgrounds and Borders Level 3  
border-image-source CSS Backgrounds and Borders Level 3  
border-image-repeat CSS Backgrounds and Borders Level 3  
border-image-slice CSS Backgrounds and Borders Level 3 a 'four sides' property
border-image-width CSS Backgrounds and Borders Level 3 a 'four sides' property
Border Shorthands
border-width CSS Backgrounds and Borders Level 3 a 'four sides' property
border-style CSS Backgrounds and Borders Level 3 a 'four sides' property
border-color CSS Backgrounds and Borders Level 3 a 'four sides' property
border-top CSS Backgrounds and Borders Level 3  
border-right CSS Backgrounds and Borders Level 3  
border-bottom CSS Backgrounds and Borders Level 3  
border-left CSS Backgrounds and Borders Level 3  
border CSS Backgrounds and Borders Level 3  
border-radius CSS Backgrounds and Borders Level 3  
border-image CSS Backgrounds and Borders Level 3  
Outline Properties
outline-style CSS Basic User Interface Level 3 initial value is none, auto is not supported
outline-width CSS Basic User Interface Level 3  
outline-color CSS Basic User Interface Level 3 initial value is currentColor, invert is not supported
outline-offset CSS Basic User Interface Level 3  
Outline Shorthands
outline CSS Basic User Interface Level 3  
Background Properties
background-color CSS Backgrounds and Borders Level 3  
background-clip CSS Backgrounds and Borders Level 3  
background-origin CSS Backgrounds and Borders Level 3  
background-size CSS Backgrounds and Borders Level 3  
background-position CSS Backgrounds and Borders Level 3  
background-repeat CSS Backgrounds and Borders Level 3  
background-image CSS Backgrounds and Borders Level 3 not supported: urls without quotes, colors in crossfades
box-shadow CSS Backgrounds and Borders Level 3  
background-blend-mode CSS Compositing and Blending Level 1 only affects multiple backgrounds
Background Shorthands
background CSS Backgrounds and Borders Level 3  
Transition Properties
transition-property CSS Transitions  
transition-duration CSS Transitions  
transition-timing-function CSS Transitions  
transition-delay CSS Transitions  
Transition Shorthands
transition CSS Transitions  
Animation Properties
animation-name CSS Animations Level 1  
animation-duration CSS Animations Level 1  
animation-timing-function CSS Animations Level 1  
animation-iteration-count CSS Animations Level 1  
animation-direction CSS Animations Level 1  
animation-play-state CSS Animations Level 1  
animation-delay CSS Animations Level 1  
animation-fill-mode CSS Animations Level 1  
Animation Shorthands
animation CSS Animations Level 1  
Table-related Properties
border-spacing CSS Table Level 3 respected by GtkBox and GtkGrid