GNOME.org
 

Re: New icons features

It's early Christmas! Thanks Benjamin, especially for the spinner.

On Thu, May 15, 2014 at 1:19 AM, Benjamin Otte <otte gnome org> wrote:

Hey,

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.

Icontheme
=======
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.

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
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
'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


1: http://dev.w3.org/csswg/css-images-3/#image-values
2: http://dev.w3.org/csswg/css-transforms/#typedef-transform-list




-- 
Jakub Steiner <jimmac gmail com>
http://jimmac.musichall.cz
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]