Logo Icon Logo
A Crowd-sourced Cookbook on Writing Great Android® Apps
GitHub logo Twitter logo OReilly Book Cover Art

Using Nine Patch Files

Published? true
FormatLanguage: WikiFormat

Problem:

When designing a User Interface you want to change the default View backgrounds to fit in with an App's overall style. The backgrounds must be able to scale correctly for different size Views.

Solution:

Android uses Nine Patch files to provide support for scaling of backgrounds as View sizes change.

Discussion:

In the following picture the word Text has a background that is a rounded rectangle (a black border with a grey background). The rectangle has then been uniformly scaled to fit in Longer Text. As a result of scaling the corners and vertical edges have distorted to give the rounded rectangle an unbalanced look. Compare that to the second Longer Text where the background has maintained its balance.

To correctly scale the background selected parts of the image are scaled in a particular direction or not scaled at all. Which parts are scaled and in which direction are shown in this diagram.

The X indicates that corners are not scaled, the vertical edges are scaled vertically, the horizontal edges are scaled horizontally and the central area is scaled in both directions. Hence the name Nine Patch.

  • 4 Corners
  • 2 Vertical Edges
  • 2 Horizontal Edges
  • 1 Central Area
  • 9 Areas (Patches) in Total

In the following example the default black border and grey gradient background of an EditText is replaced with a solid turquoise background with black border. The required rounded rectangle is drawn in a graphics program (such as Gimp, [1], or Paint.net, [2]). The rectangle is drawn as small as possible (resembling a circle) to support small Views. There is a one pixel border and transparent background. A version of the rectangle with an orange border is drawn to support focus indication used with keypad navigation.

Android needs to know which proportion of the vertical and horizontal edges need to be scaled, also where the View content sits in relation to the background. These factors are determined from indicators drawn within the image. To apply these indicators the draw9patch program supplied in the Android SDK tools folder is used. Start the program and open the background image (drag and drop onto the draw9patch dialog). The program will expand the image by one pixel all around. It is on this extra one pixel edging that indicator lines are drawn. Enlarge the image using the Zoom slider. In the left hand and top edges draw the indicator lines to mark which of the vertical and horizontal pixels can be duplicated for scaling. In the right hand and bottom edges draw the indicator lines to show where content can be positioned.

The following diagram shows the right and bottom markers for content placement. If content does not fit in the indicated rectangle then the background image is stretched using the area shown by the left and top markers.

Save the marked up file in the res/drawable folder for a project. Android determines if an image is scaled using Nine Patch scaling instead of uniform scaling via the file name, it must have .9 before the .png file extension. For example a image file named turquoise.png would be named turquoise.9.png. To use the background image reference it in a layout, android:background="@drawable/turquoise". If also using another image to indicate View focus use a selector file, for example save this XML file in the drawable folder as selector.xml:

<?xml version="1.0" encoding="utf-8"?>
<selector xmlns:android="http://schemas.android.com/apk/res/android">
     <item android:state_focused="true"
           android:drawable="@drawable/turqfocus" />
     <item android:drawable="@drawable/turquoise" />
</selector>

Reference it as android:background="@drawable/selector" (see ImageButton State Graphics Using Inkscape for another selector file example).

Notice that the new View background is using a little less space than the default (useful to know if a project needs a little bit more screen area).

Nine Patch files are not restricted to simple View backgrounds. This Nine Patch file is used to frame a photograph, the left and top scaling indicators are broken where detail that must not be scaled (because it would distort) is located.

See Also:

[1]

Download:

The source code for this project can be downloaded from http://tekeye.biz/download/ninepatch.zip.