Decorators
Decorators are an extension to CSS for RCSS. A decorator can be declared in a style sheet and configured with decorator-specific properties. Custom decorator types can be developed to suit the needs of the user, and in this manner any kind of decoration can be applied to an element.
See also the C++ documentation on decorators for more details and how to define your own decorators.
RmlUi decorators
RmlUi comes with several built-in decorators for displaying images and tiled images behind elements.
Decorator | Types | Description | Requires shader support |
---|---|---|---|
Image | image |
A single image. | |
Tiled horizontal | tiled-horizontal |
Tiled images horizontally. | |
Tiled vertical | tiled-vertical |
Tiled images vertically. | |
Tiled box | tiled-box |
Tiled images across a box. | |
Ninepatch | ninepatch |
Efficiently tiled images across a box. | |
Straight gradients | horizontal-gradient , vertical-gradient |
Horizontal and vertical color gradients. | |
Linear gradients | linear-gradient , repeating-linear-gradient |
Linear color gradients. | ✔️ |
Radial gradients | radial-gradient , repeating-radial-gradient |
Radial color gradients. | ✔️ |
Conic gradients | conic-gradient , repeating-conic-gradient |
Conic color gradients. | ✔️ |
Shader | shader |
Custom shaders. | ✔️ |
Some decorators require the backend renderer to support advanced rendering features, see the render interface feature table for details.
Decoration: The ‘decorator’ property
The decorator property is specified as follows.
decorator
Value: | none | [ <type>( <properties> ) <paint-area>? | <name> <paint-area>? ]#+ |
Initial: | none |
Inherited: | no |
Percentages: | N/A |
- <type>
- Declares the decorator type, see the list of built-in decorators above.
- <properties>
- Declares the properties specific to the given decorator type.
- <name>
- Declares a decorator name defined by an @decorator rule.
- <paint-area>
- Optionally, specifies the area of the element the decorator should be applied to, i.e. one of
border-box
,padding-box
, orcontent-box
. This value defaults topadding-box
when omitted.
For illustration, a single decorator can be used as in the following.
decorator: <type>( <properties> );
While multiple decorators can be used as follows. They will be rendered in the declared order from top to bottom.
decorator: <type>( <properties> ), <type>( <properties> ), ... ;
For performance reasons, it is recommended to declare decorators in style sheets, not in the style defined inline to an element.
When creating a custom decorator, you can provide a shorthand property named decorator
which will be used to parse the text inside the parenthesis of the property declaration. This allows specifying the decorator with inline properties as in the provided examples.
Examples
/* declares an image decorater by a sprite name */
decorator: image( icon-invader );
/* declares a tiled-box decorater by several sprites */
decorator: tiled-box(
window-tl, window-t, window-tr,
window-l, window-c, window-r,
window-bl, window-b, window-br
);
/* declares an image decorator by the url of an image,
displayed across the content box of the element */
decorator: image( invader.tga ) content-box;
For the built-in decorators with support for images and sprites, the specified ‘src’ looks for a sprite with the same name first. If none exists, then it treats it as a file name for an image.
Decorators can be overridden like any other property. So, in the example:
h1 {
decorator: image( cat.png );
}
h1:hover {
decorator: none;
}
all h1
tags will have an image decorator attached, except when they are being hovered, then they will not be rendered.
Decorator at-rule
The @decorator
at-rule in RCSS can be used to declare a decorator when the shorthand syntax given above is not sufficient. It is best served with an example, we use the custom starfield
decorator type from the invaders sample. In the style sheet, we can populate it with properties as follows.
@decorator stars : starfield {
num-layers: 5;
top-colour: #fffc;
bottom-colour: #fff3;
top-speed: 80.0;
bottom-speed: 20.0;
top-density: 8;
bottom-density: 20;
}
And then use it in a decorator.
decorator: stars;
Note the lack of parenthesis which means it is a decorator name and not a type with shorthand properties declared.