Tutorial 2: Images, and Nine Patch Images in MadComponents

In the first tutorial, we built a simple two page application with a button on each page, which triggered a page change.  The tutorial was an interpretation of “Build a mobile app in five minutes“.  But instead of building the project in Flash Builder 4.5, we built it using MadComponents.  It is recommended to read the previous tutorial to get the most out of this tutorial.

MadComponents is IDE agnostic.  So you can build mobile projects in Flash, or Flex (Flash Builder), or third-party Flash Platform tools.

In this tutorial, we’re going to learn about images, skinning, and nine patch images in MadComponents.

This tutorial assumes you have version MadComponentsLib0_5_1.swc or a later version.  Download it from http://code.google.com/p/mad-components/downloads/list

The image tag

We can include images into a MadComponents layout using the <image> tag.  For example:-

<image>{getQualifiedClassName(PICTURE64)}</image>

This layout just includes the image class “PICTURE64” into your layout.  getQualifiedClassName is an Adobe utility that coverts a Class reference to a textual representation. Here is the complete program:-

package
{
	import flash.display.Sprite;
	import flash.display.StageAlign;
	import flash.display.StageScaleMode;
	import flash.utils.getQualifiedClassName;

	import com.danielfreeman.madcomponents.*;

	public class MadImage extends Sprite
	{
		[Embed(source="images/picture64.png")]
		protected static const PICTURE64:Class;

		protected static const IMAGE:XML = <image>{getQualifiedClassName(PICTURE64)}</image>;

		public function MadImage(screen:Sprite = null)
		{
			if (screen)
				screen.addChild(this);

			stage.align = StageAlign.TOP_LEFT;
			stage.scaleMode = StageScaleMode.NO_SCALE;

			UI.create(this, IMAGE);
		}
	}
}

picture64 is your own .png image file. (Assumed to be 64×64 pixels). We assume we’ve put in in a folder called images.

Beware Copy And Paste

The following general advice isn’t only applicable to MadComponents project.  It is a general issue, that can affect any project.

Copying and pasting into Eclipse, or Flash can cause inexplicable errors in your code.  Especially code that has XML.   Working through a tutorial such as this, you’re likely to copy and paste.  The problems are caused by unprintable characters in the pasted code.  They look like spaces, or linefeeds, but they’re not.  And they screw things up.  If this happens, one way you can fix things is to delete all the spaces and linefeeds, and then reformat your code or layout xml.  Single, and double quote characters can also cause problems.  There are several versions of these characters, that look very similar – but the wrong character will cause a syntax error.

MadComponents provides a utility, UI.clean() that removes unwanted unprintable characters in XML layouts.

Instead of writing this:-

UI.create(this, LAYOUT);

Write this:-

UI.create(this, UI.clean(LAYOUT));

The reason that clean isn’t employed usually, is that there is an overhead to doing this.  If you run into problems, it is better to try and delete spaces, linefeeds, and reformat.  But UI.clean() is an easy thing to do if you run into copy paste problems during development.  And it can help eliminate this as a possibility when debugging your code.

Set image from ActionScript

You can use an image tag to define an empty placeholder for an image that you assign in ActionScript.  For example, here is an placeholder for an image 64 pixels by 64 pixels:-

<image id=”myimage”>64</image>

If you specify one number, the placeholder is assumed to be square.  But specify two numbers for a rectangular place holder, for example, 30 pixels (width) by 40 pixels (height):-

<image id=”myimage”>30,40</image>

To assign an image to this placeholder, use the following code:-

var myImage:UIImage = UIImage(UI.findViewById(“myimage”));

myImage.imageClass = PICTURE64; //Where this is the embedded Class from before.

Or you can write:-

myImage.imageClassName = getQualifiedClassName(PICTURE64);

If the placeholder size is smaller than the image size, then MadComponents will scale the image down to fit.

You can also set the image from a bitmap instance.  This is convenient for developers using Flash, as they can utilise an image that they’ve set up in their library.

myImage.image = bitmapValue; //From Flash Library.

You can assign any DisplayObject subclass instance to the image property.

myImage.image = anyDisplayObjectSubclassInstance;

Suppose you want to assign a different image to a placeholder, depending on the screen density of the device.  You might do something like this:-

var dpi:uint = Capabilities.screenDPI;

if (dpi>280)

myImage.imageClass = PICTURE64_320;

else if (dpi>200)

    myImage.imageClass = PICTURE64_240;

else

    myImage.imageClass = PICTURE64_160;

Here is an example with an image that changes every time you click on it.  (Make sure you have MadComponentsLib0_5_1.swc or higher)

package
{
	import com.danielfreeman.madcomponents.*;

	import flash.display.Sprite;
	import flash.display.StageAlign;
	import flash.display.StageScaleMode;
	import flash.events.MouseEvent;
	import flash.utils.getQualifiedClassName;

	public class MadImage extends Sprite
	{
		[Embed(source="images/mp3_48.png")]
		protected static const MP3:Class;

		[Embed(source="images/mp4_48.png")]
		protected static const MP4:Class;

		protected static const IMAGE:XML = <image id="myImage" alignH="centre" alignV="centre">
			{getQualifiedClassName(MP3)}
		</image>;

		protected var _myImage:UIImage;
		protected var _toggle:Boolean = true;

		public function MadImage(screen:Sprite = null)
		{
			if (screen)
				screen.addChild(this);

			stage.align = StageAlign.TOP_LEFT;
			stage.scaleMode = StageScaleMode.NO_SCALE;

			UI.create(this, IMAGE);

			_myImage = UIImage(UI.findViewById("myImage"));
			_myImage.addEventListener(MouseEvent.MOUSE_UP,clicked);
			_myImage.mouseEnabled = true;
		}

		protected function clicked(event:MouseEvent):void {
			_toggle = !_toggle;
			_myImage.imageClass = _toggle ? MP3 : MP4;
		}
	}
}

ImageLoader

We can use an <imageLoader> to obtain an image from the server.  For example:-

<imageLoader>http://www.myserver.com/myImage.jpg</imageLoader&gt;

We can also define a placeholder.

<imageLoader id=”myImage”>40,30</imageLoader>

Control the <imageLoader> from ActionScript, as follows:-

var myImage:UIImageLoader = UIImageLoader(UI.findViewById(“myimage”));

myImage.value = “http://www.myserver.com/myImage.jpg&#8221;;

You can set up listeners on the UIImageLoader instance for Event.COMPLETE, SecurityErrorEvent.SECURITY_ERROR, IOErrorEvent.IO_ERROR, and ErrorEvent.ERROR.

Nine Patch Images

MadComponent buttons are skinnable.  We can use utilise a snazzy button design in the form of a .jpg, or .png image.  The size of the button may vary, for different screens, and depending on device orientation.  So the skin image must be resizable.  But when you resize an image, this can cause problems with pixelation and distortion of the bitmap.  The solution to the problem is called a “nine patch image”.  Some Flash developers reading this tutorial will be familiar with the concepts of nine patch images, but if you’re not – keep reading.

Suppose we have a snazzy button image:-

Now let’s resize the image vertically.

Now our button doesn’t look so snazzy any more.  The curved corners, and the corners of the highlight area are irregular and stretched.  There is a beveled area around the button, that’s looking very fat at the sides.  And I’m beginning to see pixelation raggedness on the curves.

Here is the same image vertically stretched, but this time, we’ve used a nine patch scheme:-

See the difference?  So how does nine patch scaling work?

We divide the image into nine regions.  Each region has different scaling rules.

In the corners (1, 3, 7 and 9 ) there is no scaling.  The sides ( 4 and 6 ) are only scaled vertically.  The top and bottom ( 2 and 8 ) are only scaled horizontally.  The centre ( 5 ) is scaled both horizontally and vertically.

We apply the nine patch to the red button image as show:-

The curved corners aren’t scaled, so their shapes are preserved.  The sides are scaled so that the bevel doesn’t get fat, and the highlight area of the button doesn’t get any taller.

In ActionScript, you can define a nine patch embedded image like this:-

[Embed(source="images/red.png",
      scaleGridTop="100", scaleGridBottom="200",
      scaleGridLeft="40", scaleGridRight="200")]
protected static const RED:Class;

Where scaleGridTop, scaleGridBottom, scaleGridLeft, and ScaleGridRight are the positions of the dividing lines of the nine patch (from the top-left corner).

Skinning a button

You can apply this nine patch image skin (or just a normal image) to a button within the layout like this:-

<button skin={getQualifiedClassName(RED)}>hello</button>

To set the height of a skinned button, you can use the height attribute:-

<button skin={getQualifiedClassName(RED)} height=”100″>hello</button>

You can also set a button skin in ActionScript:-

var button:UIButton = UIButton(UI.findViewById(“button”));

button.skinClass = RED;

//or

button.skin = getQualifiedClassName(RED);

button.skinHeight = 100.0;

Further reading

To find out more about MadComponents, you can read the other related threads on this blog, or download the documentation at http://code.google.com/p/mad-components/downloads/list

Please subscribe to this blog if you want to catch subsequent tutorials.

What’s next?

So far, we’ve barely scratched the surface of MadComponent’s capabilities.  In the next tutorial, we’ll be talking about lists and pickers.  Then we’ll build a Twitter client like the one described in this Flash Builder 4.5 tutorial.  But using MadComponents, it will be much, much easier than Flash Builder.