2.3.4 9-Patches

A 9-patch is a method of rendering a texture so that it can be stretched to cover an area of any size without becoming distorted. This is achieved by dividing up the sprite into nine regions:

• the center, which can be stretched or tiled horizontally and vertically
• the four corners, which are never stretched or tiled
• the left and right sides, which can be stretched or tiled vertically
• the top and bottom sides, which can be stretched or tiled horizontally

The most common application of this technique is for graphical user interface widgets like buttons and dialog boxes which are often dynamically resizable. By using a 9-patch, they can be rendered at any size without scaling artifacts.

Procedure: draw-9-patch texture rect [#:margin 0] [#:top-margin margin] [#:bottom-margin margin] [#:left-margin margin] [#:right-margin margin] [#:mode stretch] [#:origin] [#:scale] [#:rotation] [#:blend-mode] [#:tint white]

Draw a 9-patch over the area rect using texture whose stretchable/tileable patches are defined by the given margin measurements. The corners are never stretched/tiled, the left and right edges will be stretched/tiled vertically, the top and bottom edges may be stretched/tiled horizontally, and the center may be stretched/tiled in both directions.

mode may be either stretch (the default) or tile.

margin specifies the margin size for all sides of the 9-patch. To make margins of differing sizes, the top-margin, bottom-margin, left-margin, and right-margin arguments may be used.

Refer to draw-sprite (see Sprites) for information about the other arguments as they are the same.