PageOutline(1-5, Contents)

Table of Contents Style Guide Scrollbars Generated elements Applying RCSS properties The 'scrollbar-margin' property Example RCSS Sliders Drop-down selection boxes Generated elements Example RCSS

libRocket and the controls plugin features several functional elements that need to by sized and decorated with RCSS properties, such as scrollbars, sliders and drop-down boxes. This document will go over all these elements and give recommendations on how you should style them.

Any element with scrolling overflow (a value of 'scroll' or 'auto' on either of the 'overflow-x' or 'overflow-y' properties) may generate scrollbars along its bottom or right side. By default, these are simple block elements with no background colour or decorator.

The scrollbar elements are tagged scrollbarhorizontal or scrollbarvertical, depending on their orientation. They are hidden elements parented directly to the scrolling element. Each scrollbar element contains four child elements:

 * ''sliderarrowdec'': The button at the top (or left) of the scrollbar which can be clicked to scroll further up (or to the left) the element.
 * ''sliderarrowinc'': The button at the bottom (or right) of the scrollbar which can be clicked to scroll further down (or to the right) the element.
 * ''slidertrack'': The track that runs between the two arrow buttons.
 * ''sliderbar'': The bar that runs on the track. It represents the size and position of the visible segment of the element's content. It can be dragged to scroll the visible window around.

Image(styleguide_1.gif, nolink)

When both horizontal and vertical scrollbars are present on an element, they are both shortened by the amount necessary to avoid an intersection. Another element is created and placed in this intersection point, placed and sized appropriately. This corner element is tagged scrollbarcorner and exists only for decoration purposes.

All of these elements can be styled through RCSS to be sized, positioned and rendered appropriately. The recommended method for configuring a scrollbar is given below (note that this is for a vertical scrollbar; for a horizontal, swap width and height):

 1. Set the 'width' property of the ''scrollbarvertical'' element to the appropriate value for your interface design. This should be enough to encompass the arrows, track and bar.
 1. Set the 'width' and 'height' properties of the ''sliderarrowdec'' and ''sliderarrowinc'' elements as appropriate. Set them to '0' if you don't want buttons.
 1. Set the 'width' property of the ''slidertrack'' as appropriate. The 'height' value will be ignored for the track and will always be set internally. Use 'margin-left' to position the track within the scrollbar.
 1. Set the 'width' property of the ''sliderbar'' as appropriate. The height of the bar will be generated internally, but you can override this with the 'height' property, or use the 'min-height' and 'max-height' properties to influence it.
 1. Apply decorators to the elements as appropriate. 

See the Rocket Invaders from Mars demo style sheet and the [wiki:documentation/tutorials/WindowTemplate] for more pointers.

As described above, the scrollbar elements (scrollbarvertical and scrollbarhorizontal) will shorten themselves automatically to avoid a corner intersection. This can lead to scenarios where a scrollbar is popping on and off (during a window resize, for example) and causing the other scrollbar to rapidly change size. To avoid this, and force a scrollbar to always shorten itself for a corner, you can use the numerical 'scrollbar-margin' property on a scrollbar element. An element will shorten itself (on the bottom or right side, as appropriate) by the minimum of the appropriate corner dimension and the scrollbar margin.

The following is the section of the style sheet for Rocket Invaders from Mars relevant for scrollbars.

The controls plugin adds support for range sliders; these are instanced through the RML tag <input type="range"></input>. Internally these are very similar to scrollbars, and contain identical child elements, i.e.:

 * ''sliderarrowdec''
 * ''sliderarrowinc''
 * ''slidertrack''
 * ''sliderbar''

These are styled in the same way you style scrollbars. Note that for input types, the controls plugin automatically sets the 'type' attribute of an input element as a class to ease their specification in a style sheet. So the following rule will apply properties to an input's slider track:

The controls plugin adds support for drop-down boxes; these are instanced through the RML tag <select></select>, with individual options specified within the selection element with <option></option> tags.

The select element generates three hidden elements:

 * ''selectvalue'': The container element for the selected option.
 * ''selectarrow'': The button rendered to the right of the value element. This element has the pseudo-class 'checked' set on it when the selection box is visible.
 * ''selectbox'': The box containing the options. The visibility of this element is toggled when the arrow or value elements are clicked on, or when an option is selected.

Image(styleguide_2.gif, nolink)

The following are the select element's RCSS rules and properties from the Rocket Invaders from Mars style sheet: