How to use the Feathers Scale3Image display object

The Scale3Image class displays a texture divided into three regions, either horizontally or vertically. When the direction of a Scale3Image is horizontal and the width is changed, the left and right regions will not scale and the center region will scale horizontally. When the direction of a Scale3Image is vertical, the top and bottom regions will not scale and the center region will scale vertically. This display object allows you to create skins with "pill" shapes for UI components like buttons, and sub-components like thumbs and tracks on scroll bars and sliders.

Regions

The image above shows two ways to divide a "pill" shape into three regions. The two lines on each shape show where the image is sliced. The exact pixel location of these "slices" are easily configurable, as you will see later.

The image below uses arrows to show how each of the regions will scale. Some regions will not scale. Some will scale only in one direction, horizontally or vertically.

From this point forward, each region will be named by its horizontal or vertical position. Horizontal positions are "left", "center", and "right". Vertical positions are "top", "middle", and "bottom".

The top, bottom, left, and right regions (the "caps" of the pill shape) will not be scaled.

The center region will scale horizontally. It will not scale vertically.

The middle region will scale vertically. It will not scale horizontally.

Scaling in the Opposite Direction

Scale3Image is designed to mainly scale in one direction. However, it is capable of scaling in the other direction too. In this situation, the "caps" will scale to maintain aspect ratio. As an example, if a cap is a half circle, it will remain perfectly round after scaling in both directions. The goal is to avoid distortion of the caps.

The image above shows how the caps maintain aspect ratio when scaled in the opposite direction.

The Grid

Two numeric values defines the grid. Actually, these specifically defines the center or middle region described above. Each of the other regions can be automatically calculated using these values along with the original width and height of the texture.

The horizontal orange pill shape pictured above is 200 pixels wide and 80 pixels tall. Using the lines in the picture, we'll define the grid. The x value is 40. The width value is 120 pixels.

40 + 120 + 40 = 200

It works similarly for a vertical pill shape, except the two values represent y and height.

The left and right regions don't necessarily need to be the same size. Neither do the top and bottom regions. However, for pill shapes, it will often be the case that these regions are the same size.

Code

First, let's create a feathers.textures.Scale3Textures object:

var texture:Texture = Texture.fromBitmapData( bitmapData );
var textures:Scale3Textures = new Scale3Textures( texture, 40, 120, Scale3Textures.DIRECTION_HORIZONTAL );

This object is created from a standard starling.textures.Texture object, the two region values, and the constant representing the direction of the regions. Either Scale3Textures.DIRECTION_HORIZONTAL or Scale3Textures.DIRECTION_VERTICAL.

We'll pass the Scale3Textures object to a new feathers.display.Scale3Image object:

var image:Scale3Image = new Scale3Image( textures );
image.width = 100;
this.addChild( image );

You can easily change the width property for horizontal Scale3Image objects (or the height property for vertical images), and the regions will scale appropriately, as described above.