The ninepatch decorator splits a sprite into a 3x3 grid of patches by declaring another inner sprite. The corners of the ninepatch are rendered at their native size by default, while the inner patches are stretched so that the whole element is filled. In a sense, it can be considered a simplified and more performant version of the tiled-box decorator.

The decorator renders across the padded area of its element.

decorator: ninepatch( <outer>, <inner>, <edge>? );

The edge property is optional.

Properties

outer

This property defines a sprite name. The sprite declares the outer rectangle of the decorator. Image urls cannot be used in this decorator.

inner

This property defines a sprite name, and must be located in the same sprite sheet as outer. The inner sprite declares the inner rectangle of the decorator.

The area between the inner and outer rectangle defines the decorator’s corners and edges. The corners are fixed in size, the edges only scale in one direction, while the center is stretched to cover the remaining area of the element’s boundaries.

edge

The edge property is specified in the common top-right-bottom-left box order. If the property is specified (not all 0px), the rendered size of each edge can be specified as a length, or number/percentage to scale it relative to the natural size of the image edge. The natural size is determined by the sprite’s associated resolution property and the current dp-ratio. The normal box shorthands are available, e.g., a single value will be replicated to all edges.

Example

The decorator can be specified by two sprites, defining an outer and inner rectangle:

@spritesheet my-button {
	src: button.png;
	button-outer: 247px  0px 159px 45px;
	button-inner: 259px 19px 135px  1px;
}

The inner rectangle defines the parts of the sprite that will be stretched when the element is resized.

The ninepatch decorator is applied as follows:

decorator: ninepatch( button-outer, button-inner );

Furthermore, the ninepatch decorator can have the rendered size of its edges specified manually.

decorator: ninepatch( button-outer, button-inner, 19px 12px 25px 12px );

Percent and numbers can also be used, they will scale relative to the natural size of the given edge. Thus, setting

decorator: ninepatch( button-outer, button-inner, 2.0 );

will double the size of all edges.