|
|
| Line 1: |
Line 1: |
| {{RCSS}} | | {{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-Decorators}} |
| Decorators are an extension to CSS for RCSS. A decorator can be declared and named in a style sheet like a property, and then 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.
| |
| | |
| Important: Note that decorators can only be declared and defined in style sheets, not in style defined inline to an element.
| |
| | |
| ==Declaring decorators==
| |
| The declaration of a decorator is a property of the form:
| |
| | |
| <pre>
| |
| <name>-decorator: <type>;
| |
| </pre>
| |
| where <name> is the user-specified name of the decorator to declare, and <type> is the application-specific type of decorator. libRocket ships with the following decorator types:
| |
| *image
| |
| *tiled-box
| |
| *tiled-horizontal
| |
| *tiled-vertical
| |
| The decorator type none is a reserved name that represents no decorator. For example, in the following:
| |
| <pre>
| |
| button
| |
| {
| |
| icon-decorator: tiled-horizontal;
| |
| }
| |
| </pre>
| |
| the RCSS is attaching a decorator of type tiled-horizontal called ‘icon’ to all button elements. Note that the name ‘icon’ could be anything; it is only used to uniquely identify the decorator for applying properties to it.
| |
| | |
| Decorator types can be overridden like any other property. So, in the example:
| |
| <pre>
| |
| h1
| |
| {
| |
| icon-decorator: image;
| |
| }
| |
| | |
| h1:hover
| |
| {
| |
| icon-decorator: none;
| |
| }
| |
| </pre>
| |
| all h1 tags will have an image decorator attached, except when they are being hovered, when the decorator will not be rendered.
| |
| | |
| ==Decorator properties==
| |
| Decorators have their own property specifications with properties and shorthands, and these can be defined for declared decorators just like any other property. Decorator properties are set in the form:
| |
| | |
| <pre>
| |
| <name>-<property>: <value>;
| |
| </pre>
| |
| where <name> is the name the decorator was declared under, <property> is the name of the decorator’s property to set, and <value> is the value of the property. For example:
| |
| <pre>
| |
| h1
| |
| {
| |
| icon-decorator: image;
| |
| icon-image-src: ../images/header_arrow.png;
| |
| icon-image-s-begin: 5px;
| |
| }
| |
| </pre>
| |
| an image decorator is declared, called ‘icon’. On this decorator, the properties <name>-image-src is set to ‘../images/header_arrow.png’ and <name>-image-s-begin is set to ‘5px’. The other properties in the image specification are left to their defaults.
| |
| | |
| The decorator properties behave like other properties, so are subject to precedence and the cascade. For example, if the following RCSS was loaded after the previous example:
| |
| <pre>
| |
| h1
| |
| {
| |
| icon-image-s-begin: 3px;
| |
| }
| |
| | |
| h1:first-child
| |
| {
| |
| icon-decorator: none;
| |
| }
| |
| </pre>
| |
| all h1 tags will have their ‘icon’ decorators defined with an <name>-s-begin property of ‘3px’ instead of ‘5px’, and an h1 that is a first child will have no decorator.
| |
| | |
| Be careful of name conflicts! For example, in the following sample:
| |
| <pre>
| |
| h1
| |
| {
| |
| icon-decorator: image;
| |
| }
| |
| | |
| .secondary
| |
| {
| |
| icon-decorator: tiled-horizontal;
| |
| }
| |
| </pre>
| |
| an element of type h1 with a class of ‘secondary’ will have a single decorator, ‘icon’, of type tiled-horizontal. If the decorators had different names then they both would be present.
| |
| | |
| Specifying render order
| |
| If an element has more than one decorator on it, you can use the ‘z-index’ decorator property to control the render order in a similar fashion to elements. For example, in this sample:
| |
| <pre>
| |
| button
| |
| {
| |
| background-decorator: tiled-horizontal;
| |
| background-z-index: 0;
| |
| | |
| icon-decorator: image;
| |
| icon-z-index: 1;
| |
| }
| |
| </pre>
| |
| the ‘icon’ decorator will appear on top of the ‘background’ decorator. If no z-index is specified on a decorator, it will have the default z-index of 0.
| |
| | |
| Decorators and pseudo-classes | |
| Because of the way libRocket compiles pseudo-class rules within style sheets, overriding decorator properties within dynamic pseudo-classes (:active, :hover and :focus, not any of the structural classes) might not always work the way you think it should.
| |
| | |
| In a nutshell, each decorator will only process properties from their element’s base rules (ie, those not specifying dynamic pseudo-classes in their final simple selector) and one rule specifying a dynamic pseudo-class (or classes), that with the highest specificity. For example, in the following sample:
| |
| <pre>
| |
| button
| |
| {
| |
| background-decorator: tiled-horizontal;
| |
| background-image-src: ../button.png;
| |
| background-image-s-end: 128px;
| |
| }
| |
| | |
| button:hover
| |
| {
| |
| background-image-t-begin: 32px;
| |
| background-image-t-end: 64px;
| |
| }
| |
| | |
| button:active
| |
| {
| |
| background-image-s-begin: 128px;
| |
| background-image-s-end: 256px;
| |
| }
| |
| </pre>
| |
| if both the :hover and :active pseudo-classes are active on a button element, the <name>-image-s-begin and <name>-image-s-end properties from the :active rule will be set, but the <name>-image-t-begin and <name>-image-t-end properties from the :hover rule will be ignored. The :active rule is used as it has higher precedence that the :hover rule, appearing further down the file. If you wanted both the s and t properties set, you could create another rule:
| |
| <pre>
| |
| button:active:hover
| |
| {
| |
| background-image-t-begin: 32px;
| |
| background-image-t-end: 64px;
| |
| background-image-s-begin: 128px;
| |
| background-image-s-end: 256px;
| |
| } | |
| </pre>
| |
| | |
| ==image decorators==
| |
| Image decorators in Freespace Open's instance of librocket support a custom paramter, <code>image-fit</code>. Valid values are Stretch, Contain, Fill.
| |
| <pre>
| |
| .general_bg
| |
| {
| |
| background-decorator: image;
| |
| background-image: 2_preload.png;
| |
| background-image-fit: contain;
| |
| } | |
| </pre>
| |
| | |
| ==libRocket decorators==
| |
| libRocket comes with several built-in decorators for displaying images and tiled images behind elements.
| |
| | |
| *image decorator, for displaying a single stretched image.
| |
| *tiled-horizontal decorator, for tiling images horizontally.
| |
| *tiled-vertical decorator, for tiling images vertically.
| |
| *tiled-box decorator, for tiling images across a box.
| |