Changes from Version 1 of documentation/StyleGuide

Author:

peterc (IP: 203.96.63.172)

Timestamp:

02/14/08 13:01:06 (10 years ago)

Comment:

--

documentation/StyleGuide

@@ +1 @@
+= Style Guide =
+
+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.
+
+== Scrollbars ==
+
+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.
+
+=== Generated elements ===
+
+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.
+
+<img>
+
+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.
+
+=== Applying RCSS properties ===
+
+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 templating tutorial] for more pointers.
+
+=== The 'scrollbar-margin' property ===
+
+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.
+
+=== Example RCSS ===
+
+The following is the section of the style sheet for Rocket Invaders from Mars relevant for scrollbars.
+
+{{{
+/* Fix the width and push the scrollbar back to the extents of the window. */
+scrollbarvertical
+{
+        margin-top: -6px;
+        margin-bottom: -6px;
+        margin-right: -11px;
+        width: 27px;
+}
+
+/* Decorate the slider track. */
+scrollbarvertical slidertrack
+{
+        background-decorator: tiled-vertical;
+        background-top-image: invader.png 70px 199px 97px 201px;
+        background-center-image: invader.png stretch 70px 201px 97px 202px;
+        background-bottom-image: invader.png 70px 203px 97px 204px;
+}
+
+/* Push the slider bar in 4 pixels from the left edge. Fix the width of the bar and make sure
+   the height doesn't drop below 46 pixels; under that the decorator will start squishing the
+   images. */
+scrollbarvertical sliderbar
+{
+        margin-left: 4px;
+        width: 23px;
+        min-height: 46px;
+
+        background-decorator: tiled-vertical;
+        background-top-image: invader.png 56px 152px 79px 175px;
+        background-center-image: invader.png stretch 56px 175px 79px 175px;
+        background-bottom-image: invader.png 56px 176px 79px 198px;
+}
+
+/* Animate the bar's decorator on hover. */
+scrollbarvertical sliderbar:hover
+{
+        background-top-image-s: 80px 103px;
+        background-center-image-s: 80px 103px;
+        background-bottom-image-s: 80px 103px;
+}
+
+/* Animate the bar's decorator on active. */
+scrollbarvertical sliderbar:active
+{
+        background-top-image-s: 104px 127px;
+        background-center-image-s: 104px 127px;
+        background-bottom-image-s: 104px 127px;
+}
+
+/* Fix the size of the 'page up' slider arrow and decorate it appropriately. */
+scrollbarvertical sliderarrowdec
+{
+        width: 27px;
+        height: 24px;
+        
+        icon-decorator: image;
+        icon-image: invader.png 0px 152px 27px 176px;
+}
+
+/* Fix the size of the 'page down' slider arrow and decorate it appropriately. */
+scrollbarvertical sliderarrowinc
+{
+        width: 27px;
+        height: 24px;
+        
+        icon-decorator: image;
+        icon-image: invader.png 28px 152px 55px 176px;
+}
+
+/* Animate the arrows on hover. */
+scrollbarvertical sliderarrowdec:hover,
+scrollbarvertical sliderarrowinc:hover
+{
+        icon-image-t: 177px 201px;
+}
+
+/* Animate the arrows on active. */
+scrollbarvertical sliderarrowdec:active,
+scrollbarvertical sliderarrowinc:active
+{
+        icon-image-t: 202px 226px;
+}
+}}}