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.

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: relative to the width of the containing block
/* 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. For inline elements, auto will evaluate to 0.

Note that percentage margins are always evaluated relative to the width of the containing block, even for the top and bottom margins.

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.

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.

Note that, like margins, percentage padding values are always evaluated relative to the width of the containing block, even for the top and bottom.

/* 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.

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 shorthand properties

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%);
}