New icons features


so I've landed the css-icons branch in git master and wanted to document the changes we did there so people can start using them.

The icontheme now handles ltr and rtl variants of icons. GTK widgets will do that lookup automatically based on the text direction of the widget. For developers looking up icons themselves, GtkIconLookupFlags has been extended to pass a flag for the desired direction.
When looking up an icon "foo", the name has to be "foo-ltr" or "foo-rtl" for the variants. If that variant does not exist, code will always fall back to looking for the "foo" icon. For symbolic icons, the naming has o be "foo-symbolic-ltr" or "foo-symbolic-rtl" for the "foo-symbolic" icon.

For people who actually looked at the new lookup flags: There's two other flags added, FORCE_REGULAR and FORCE_SYMBOLIC that force an icon lookup to look at symbolic or regular icons first. This is used in CSS code (see below) and intended to easily switch the HighContrast theme to symbolics.

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.

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.

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.

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
Percentages: N/A
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
  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.
  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.
  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!


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]