CSS extensions
============
There's a bunch of extensions we decided on for CSS. These are experimental and subject to change in the future. Because of this and because they are GTK extension, all those extensions are prefixed with -gtk (just like Mozilla prefixes with -moz and Webkit with -webkit). I'd want to document them somewhere but I don't know how to make gtk-doc emit code that looks like the CSS specs, so I'll just do a crude text-only imitation of that below. I'm open on how to get this into the API docs.
1. The -gtk-icontheme image
GTK extends the <image>[1] type to accept a <icontheme> icon. This allows using an icon from the icon theme anywhere an image is allowed.
The -gtk-icontheme() notation is defined as follows:
<icontheme> = -gtk-icontheme( <string> )
The '<string>' specifies the name of the icon in the icontheme. It will be looked up in the current icontheme in use. For symbolic icons, use a symbolic icon name. Symbolic icons will be colored using the value of the color property.
The <icontheme> image has no intrinsic size as iconthemes support icon lookups at any size and will therefore use the specified size. The intrinsic aspect ratio is 1.0 because icons in the icontheme are square.
ISSUE 1
For now, -gtk-icontheme() is mainly intended to be used for -gtk-icon-source. Coloring by the current color makes sense there, but might not make sense when using it for border images. We might want to revisit the coloring decision later.
ISSUE 2
For now, the -gtk-icon-style property does not influence the behavior of -gtk-icontheme(). You need to specify symbolicness of the icon yourself by using the right icon name.
2. Icon sources: The -gtk-icon-source property
Name: -gtk-icon-source
Value: none | <image> [1]
Initial: none
Applies to: Elements that draw an icon, such as spinners, arrows, checkmarks, radiomarks or expanders
Inherited: no
Percentages: N/A
Media: visual
Computed value: as specified, but with URIs made absolute
Animateable: yes
Specifies an image to use instead of the icon that was hardcoded to be rendered. If the value is "none", everything will work as it did in previous GTK versions that did not support this property. The icon source will be rendered with the specified size as given to the GTK theming function and will respect the "icon-shadow" and "-gtk-icon-transform" properties.
3. Icon source transformations: The -gtk-icon-transform property.
Name: -gtk-icon-transform
Value: none | <transform-list> [2]
Initial: none
Applies to: Elements that draw an icon, such as spinners, arrows, checkmarks, radiomarks or expanders. Does not apply to GtkImage.
Inherited: no
Percentages: refer to the bounding box of the icon source
Media: visual
Computed value: As specified, but with relative lengths converted into absolute lengths.
Animateable: yes
Specifies the transform to apply to an icon drawn via -gtk-icon-source(). Note that GTK only supports 2D transforms for now.
EXAMPLE
A simple way to animate a spinner for GTK could look like this:
@keyframes spin {
to { -gtk-icon-transform: rotate(1turn); }
}
.spinner {
-gtk-icon-source: url("spinner.png");
}
.spinner:active {
animation: spin 1s linear infinite;
}
This would cause GTK to draw the image "spinner.png" as a spinner icon. If the spinner was active, the icon would rotate clockwise once per second.
Shadows specified via icon-shadow are not influenced by the icon-transform. So in the above example, a shadow to the bottom right would stay in the bottom right even as the image was rotating.
4. Forcing icon styles: The -gtk-icon-style property
Name: -gtk-icon-style
Value: requested | regular | symbolic
Initial: requested
Applies
to: All elements
Inherited: yes
Media: visual
Computed value: as specified
Animateable: no
For elements that render icons from the icon theme, such as GtkImage, GtkEntry or GtkCellRendererPixbuf, this property allows to override the style to be used. Values have the following meanings
'requested'
Draw the icon as requested by the application. So "foo-symbolic" will cause a symbolic icon to be used while "bar" will cause a regular icon.
'symbolic'
Try to draw a symbolic icon. If no symbolic icon can be found looking at all possible icon names, fall back to the requested name.
'regular'
Try to draw a regular icon, i.e. try to not draw a symbolic icon. If no regular icon can be found looking at all possible icon names, fall back to the requested name
As always: Comments, questions to me!
Benjamin
