RCSS BoxModel

RCSS BoxModel

The RCSS box model describes the boxes that each element in an RML element tree generates during layout. It is identical to the CSS box model. Please note that RCSS implements the CSS2 box model to specification (with one minor exception), and not the old IE box model. Important things to note about the box model are:

• The width and height properties set the size of the content area. Any borders and padding are in addition to the content area, not part of the content area as in the IE box model.
• For replaced elements (any element with intrinsic dimensions, such as input fields, images, drop-down lists, etc) borders and padding are calculated as part of the content area; ie, they use the IE box model. This allows for much easier placement of their internal elements.

Each box generated by an element is comprised of four areas:

• The content area, which contains the element’s content.
• The padding, which surrounds the content area.
• The border, which surrounds the padded area.
• The margin, which surrounds the bordered area.
• The padding is used to space the internal contents of the element from the element’s border. The border can be used as a decorative outline to the element. The margin is used to separate the element from other elements on the page.

The size of the content area is determined by a number of factors, such as the type of element generating the box, the contents of the box and the value of the width and height properties. The size of the padding, border and margins can be specified separately for each of the top, right, bottom and left edges of the box. Unlike CSS, a block box with an auto height grows to contain any floats inside it (see Floats).

A box’s background (and the default libRocket decorators) will render in the padded area of an element (ie, under the content area and the padded edges). The border will be rendered only along the border edges. The margin is always transparent (although a custom decorator could potentially render here).

Margin properties

• margin-top, margin-right, margin-bottom, margin-left

Value:	<length> | <percentage> | auto
Initial:	0px
Applies to:	all elements
Inherited:	no
Percentages:	left and right: relative to the width of the containing block. top and bottom: relative to the height of the containing block for block-level boxes, the width for inline elements (see below)

/* Sets a bottom margin of 1em on all H1 elements. */
h1
{
	margin-bottom: 1em;
}

These properties set the top, right, bottom and left margins of a box. Negative values are allowed, and will extend the content area of the box past its normal boundaries.

Margins set as auto are calculated depending on the generating box; the algorithm is fully specified in the CSS specification, but in summary: for block-level elements, the formula margin-left + padding-left + width + padding-right + margin-right = containing block width will be evaluated, with any auto margins being set equally to balance the equation. If width is auto, any auto margins will be evaluated as 0. So, setting both left and right margins to auto will have the effect of centering the element. Setting the left to auto and right to 0 will right-align the box, and so forth. The top and bottom margins are evaluated in a similar fashion against the containing block's height, but only if the box has a fixed height; for a box with an auto height, auto top and bottom margins are 0. For inline elements, auto will evaluate to 0.

Percentage top and bottom margins differ from CSS. On block-level boxes (display: block or inline-block, floats and absolutely positioned elements), a percentage margin-top or margin-bottom is evaluated against the height of the containing block, not its width as in CSS. For boxes in normal flow and floats, if the containing block has an auto height, the nearest ancestor with a known height is used instead, which may be the whole document. (Absolutely positioned elements are different; see Visual formatting model.) Only inline elements (such as an img in a line of text) use the width for their vertical margins.

This matters because a containing block's height often depends on its content, including text whose size is fixed in pixels, so a percentage vertical margin can shift as the screen resolution changes. For vertical spacing that scales with the layout, use percentage padding, which always resolves against the width.

• margin

A shorthand property for setting all four margin properties at once. If there is only one value, it applies to all sides. If there are two values, the first applies to the top and bottom, the second to left and right. If there are three values, the first applies to the top, the second to left and right, the third to the bottom. If there are four values, they are applied to top, right, bottom, left respectively.

/* Sets a top margin of 1em, a bottom margin of 10px, and a left and right margin of 0px on all div elements. */
div
{
	margin: 1em 0px 10px;
}

Collapsing margins

In libRocket, margins between sibling block boxes collapse as specified by CSS, but nested margins currently do not. Collapsing is only correct when both margins are positive. If either is negative the resulting gap is not what CSS would give, so don't rely on collapsing with negative margins.

Padding properties

• padding-top, padding-right, padding-bottom, padding-left

Value:	<length> | <percentage>
Initial:	0px
Applies to:	all elements
Inherited:	no
Percentages:	relative to the width of the containing block

These properties set the top, right, bottom and left padding of a box. Negative values are not allowed; a negative padding is treated as 0.

Note that percentage padding values are always evaluated relative to the width of the containing block, even for the top and bottom. This is unlike vertical margins (see above), and makes percentage padding the reliable way to space things vertically in proportion to the layout.

/* Specify a left padding for indenting major headings. */
h1, h2
{
	padding-left: 0.5em;
}

• padding

A shorthand property for setting all four padding properties at once. If there is only one value, it applies to all sides. If there are two values, the first applies to the top and bottom, the second to left and right. If there are three values, the first applies to the top, the second to left and right, the third to the bottom. If there are four values, they are applied to top, right, bottom, left respectively.

/* Specify uniform internal padding for a textarea. */
textarea
{
	padding: 15px;
}

Border properties

Note: the border-style properties are not supported. All borders are rendered as solid lines.

Border width

• border-top-width, border-right-width, border-bottom-width, border-left-width

Value:	<length> | <percentage>
Initial:	0px
Applies to:	all elements
Inherited:	no
Percentages:	relative to the width of the containing block

These properties set the border widths of a box. Note that the thin, medium and thick CSS values are not supported, but percentages are (relative to the containing block's width, for every edge). Negative widths are treated as 0.

• border-width

A shorthand property for setting all four border width properties at once. If there is only one value, it applies to all sides. If there are two values, the first applies to the top and bottom, the second to left and right. If there are three values, the first applies to the top, the second to left and right, the third to the bottom. If there are four values, they are applied to top, right, bottom, left respectively.

/* Set a thin border under all primary headings. */
h1
{
	border-bottom-width: 1px;
}

Border colour

• border-top-color, border-right-color, border-bottom-color, border-left-color

Value:	<color>
Initial:	black
Applies to:	all elements
Inherited:	no
Percentages:	N/A

These properties specify the colour of each of a box’s border edges.

• border-color

A shorthand property for setting all four border colour properties at once. If there is only one value, it applies to all sides. If there are two values, the first applies to the top and bottom, the second to left and right. If there are three values, the first applies to the top, the second to left and right, the third to the bottom. If there are four values, they are applied to top, right, bottom, left respectively.

Border shorthands

• border-top, border-right, border-bottom, border-left

Shorthand properties for setting the width and color of a border edge.

h1
{
	border-bottom: 2px rgb(0%, 23%, 80%);
}

There is no border shorthand for all four edges at once: border: 1px white; is silently ignored, with no warning. Set all four edges with border-width and border-color instead:

div.panel
{
	border-width: 1px;
	border-color: white;
}