One of the things that bugs me about the use of the event model with Robotlegs is that Mediators are tightly coupled with the views. Take my Twitter Search Demo for example, the SearchEntryMediator class expects an instance of the SearchEntry class as its view, see below.

One suggestion could be type the view to an interface in the mediator, but this is too loosely coupled because an interface cannot define the events an object can dispatch. There are a few solutions to this issue, for example we could use function callbacks, however Robert Penner has come up with a better solution, AS3-Signals.

The solution: AS3-Signals

Robotlegs and AS3-Signals work really well together, especially with the introduction of the Command Signal Extension. Each of these libraries don’t rely on string constants to function, they are strongly typed, therefore the compiler is able to throw errors much sooner if something is wrong.

A Signal gives an event a concrete membership in a class, for this reason we are able to include Signals in interfaces. Using this the SearchEntryMediator in my Twitter Search Demo can type the view to an ISearchEntry, and any class that implements this interface must include the searchRequested signal, see below.

The interface is very simple and just defines the searchRequested signal.

Why bother?

It’s a good question, why should we go to the effort of creating interfaces for our views? We could quite easily continue to use the Event model with Robotlegs and it would work, but the use of interfaces would be beneficial for a multi-platform Flash application or for a workflow that involved more than one person.

Imagine an application that is to be deployed to many different devices that have various screen sizes, some can use a mouse, some can be touch enabled and some are restricted to keys. To create the best user experience you would want the view of your application, and the interaction with that view, to be tailored to that device. By using interfaces for our views we can use the same code base for all applications but have different views for each device; as long as our views implement our interfaces the application will work. More advantages to this are seen if different people implement the views; by using Signals in the interface the person developing the view must implement them whereas there’s nothing specify that the person must implement an event.

P.S It’s also worth noting that there are many other benefits to using AS3-Signals, for example they provide significant speed improvements over using Events, not just the ability to define them in interfaces.

The first demo I put together was a simple Twitter Search application, using the Twitter Search API. You can see the demo in all it’s glory by clicking the image below! View Source is enabled so you can download the source and have a play; you will need the Robotlegs SWC to compile though, you’ll find this on the Robotlegs website. If you have any feedback or questions please leave a comment below!

Robotlegs has been gaining a lot of ground over the last few months within the Flash community, and so I thought it was about time I gave it a shot. This post includes some of the resources I found really useful when getting started with the framework.

What is Robotlegs?

If you haven’t heard of Robotlegs before there’s a good explanation on their website:

Robotlegs is a pure AS3 micro-architecture (framework) with a light footprint and limited scope. Simply put, Robotlegs is there to help you wire your objects together. It provides the glue that your application needs to easily function in a decoupled way. Through the use of automated metadata based dependency injection Robotlegs removes boilerplate code in an application. By promoting loose coupling and avoiding the use of Singletons and statics in the framework Robotlegs can help you write code that is highly testable.

Robotlegs was heavily influenced by PureMVC, another pure AS3 micro-architecture framework, therefore if you are familiar with the roles and architecture PureMVC has then you will find Robotlegs easy to pick up. You will also notice that there’s a helluva lot less boiler-plate code in Robotlegs!

Where should I start?

A lot of people recommend getting started with the Robotlegs best practices document and whilst this is a good place to start it can be really overwhelming, even for someone familiar with frameworks, so I’d recommend watching the following video tutorials first.

• RobotLegs Hello World Video Tutorial by John Lindquist
• Robotlegs MVCS: Walkthrough of an AIR Twitter Client by Joel Hooks

Once you watched the videos you’ll have an rough understanding of each of the roles within Robotlegs; this is a great time to check out the best practices document and build on that knowledge. If you then watch the video tutorials again you should really understand exactly what’s going on!

What’s next?

Start using it! You can download the latest release version from the Robotlegs website or, if you’re familiar with GitHub, you can fork the repository. There’s some really useful demos available on GitHub too, which include examples of using the framework with Flash, modular development and the integration of services such as Flickr and GoogleMaps.

Don’t forget, if you’re really stuck you can always ask for help!

Update: The source code is now available.

]]> http://markstar.co.uk/blog/2010/flashplatform/actionscript/hype-shapelayout-experiment/feed/ 4 http://markstar.co.uk/blog/2010/flashplatform/actionscript/filereference-woes-on-macs/ http://markstar.co.uk/blog/2010/flashplatform/actionscript/filereference-woes-on-macs/#comments Wed, 17 Feb 2010 22:37:02 +0000 Mark http://markstar.co.uk/blog/?p=221 Today I found out (the hard way) that there are several issues that can occur when trying to upload files using the FileReference class on MACs.

FileReference.type always returns null

It’s often that case that you want to restrict the file type the user can upload, or perform different processes depending on the type of file uploaded. However the type property of a FileReference object always returns null on MACs; to work around this you must get the file extension manually. To do this you can use the following code (it’s good practice to always convert the file extension to lower case before working with it).

Server script must return data

When uploading files using the FileReference class you may experience the upload getting stuck at 100% progress and never firing the Event.COMPLETE event. This will only happen on the MAC and it’s because Flash doesn’t realise that the file has finished uploading until it gets a response from the server. I don’t why this is implemented differently on the different operating systems, but to overcome this problem your server script must write something to the page (it can just be a space character!).

Parameters must be added using URLVariables

You may want to pass URL parameters to the server script when uploading a file, and in our case the parameters and the URL were passed as one string via Flash vars. MACs don’t like this. So instead we have to pass the parameters using the data property of the URLRequest; to do this you need to use the URLVariables class. The following code snippet shows you how.

Feedback!

Has anyone else come across any weird quirks or handy hints when working with the FileReference class? Please leave a comment if you have and I’ll add it to the post!

This tutorial will build upon the Introduction to using the StatefulToolkit example; it will add the ability to utilize the Clipboard in our example. The example will use the ClipboardUtil, which is a utility class included in the toolkit that allows the user to copy and paste objects using the clipboard. The example application will build upon the last one; it will allow the user to position four circles, to save and load the state of the circles (i.e. where the circles are positioned) and to copy and paste the circles. The example can be seen here and source files are available.

Preparation

Before you being implementing this tutorial make sure you have the latest version of the StatefulToolkit SWC, and that you’re project is set to target Flash Player 10 (if you want to target FP9, simple replace the Vector with an array in the circle container) . This tutorial also uses Keith Peter’s Minimal Comps component set to create the buttons in the application so you may want to grab the SWC for that too, but you can use your own buttons if you prefer. Both SWC files are included in the available flex project.

Creating the Statable Object

The original circle class could be left as it is, however it would be helpful to know which circle we have selected, so we know which one we are adding to the clipboard. In order to do show this we will add two new methods to the Circle; select and deselect. Each method draws the circle in a different colour. The full contents of this class can be seen below.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

package couk.markstar.examples.ui
{
	import couk.markstar.statefultoolkit.core.IStatable;
 
	import flash.display.Sprite;
 
	public class Circle extends Sprite implements IStatable
	{
		/**
		 * The constructor draws the circle with a grey outline
		 */
		public function Circle():void
		{
			super();
 
			drawCircle( 0x999999 );
		}
 
		/**
		 * Change the display of the circle to show it's selected
		 */
		public function select():void
		{
			drawCircle( 0x990000 );
		}
 
		/**
		 * Change the display of the circle to the default
		 */
		public function deselect():void
		{
			drawCircle( 0x999999 );
		}
 
		/**
		 * Retrieve the state of the circle storing the x and y properties
		 *
		 * @return The current state of the circle as an XML string
		 */
		public function retrieveState():String
		{
			var xml:String = '<object>';
			xml += '<x>' + x + '</x>';
			xml += '<y>' + y + '</y>';
			xml += '</object>';
			return xml;
		}
 
		/**
		 * Set the state of the circle by getting it's x and y values from the xml
		 *
		 * @param state The new state of the circle
		 */
		public function setState( state:XML ):void
		{
			x = Number( state.x );
			y = Number( state.y );
		}
 
		/**
		 * Used internally for creating the circles' graphics
		 * 
		 * @param lineColor The color of the line around the circle
		 */
		protected function drawCircle( lineColor:uint ):void
		{
			graphics.clear();
			graphics.lineStyle( 1, lineColor )
			graphics.beginFill( 0xFFFFFFF );
			graphics.drawCircle( 0, 0, 10 );
			graphics.endFill();
		}
	}
}

Creating the Container

Previously the circle container implemented the IStatable interface but it now implements the IStateContainer interface, because it needs to interact with the ClipboardUtil. The IStateContainer interface inherits functionality from the IStatable interface, so the circle container is still required to have the methods setState and retrieveState, but it is also required to have the methods addObjectByState, hasSelectedObject and retrieveSelectedObject.

The addObjectByState method was already implemented in the previous function, but was used internally, now it will be used by the ClipboardUtil when the user is pasting an object. In order to implement hasSelectedObject and retrieveSelectedObject we must add to the circleDownListener. After setting the _currentCircle we can call the select method of the circle to show that it has been selected. Then, before we set the _currentCircle to the one the user has mouse downed, we must deselect the old one by calling it’s deselect method. The full contents of this class can be seen below.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

package couk.markstar.examples.ui
{
	import couk.markstar.statefultoolkit.core.IStatable;
	import couk.markstar.statefultoolkit.core.IStateContainer;
 
	import flash.display.Sprite;
	import flash.events.MouseEvent;
	import flash.geom.Point;
 
	public class CircleContainer extends Sprite implements IStateContainer
	{
		protected var _circles:Vector.<Circle>;
 
		protected var _currentCircle:Circle;
		protected var _dragOffset:Point;
 
		/**
		 * The constructor the vector containing the circles shown in the container
		 */
		public function CircleContainer():void
		{
			_circles = new Vector.<Circle>();
			super();
		}
 
		/**
		 * Retrieve the selected object
		 *
		 * @return The selected object
		 */
		public function retrieveSelectedObject():IStatable
		{
			return _currentCircle;
		}
 
		/**
		 * Check whether the container has a selected object
		 *
		 * @return Boolean denoting if the container has a selected object
		 */
		public function hasSelectedObject():Boolean
		{
			return( _currentCircle ) ? true : false;
		}
 
		/**
		 * Retrieve the state of the container and all contained circles
		 *
		 * @return The current state of the container, including the state's of all circles
		 */
		public function retrieveState():String
		{
			var xml:String = "<container>";
 
			for( var i:uint = 0; i < _circles.length; i++ )
			{
				xml += _circles[ i ].retrieveState();
			}
			xml += "</container>";
			return xml;
		}
 
		/**
		 * Add an object to the container by it's state.
		 *
		 * @param state The state of the object to add, in this case the circle
		 */
		public function addObjectByState( state:XML ):void
		{
			var circle:Circle = new Circle();
			circle.addEventListener( MouseEvent.MOUSE_DOWN, circleDownListener );
			circle.setState( state );
			addChild( circle );
			_circles[ _circles.length ] = circle;
		}
 
		/**
		 * Set the state of the container by adding all circles contained within the state. The container will be cleared first.
		 *
		 * @param state The new state of the container
		 */
		public function setState( state:XML ):void
		{
			clearContainer();
 
			for( var i:uint = 0; i < state.object.length(); i++ )
			{
				addObjectByState( XML( state.object[ i ] ) );
			}
		}
 
		/**
		 * Clear the container of all circles
		 *
		 */
		protected function clearContainer():void
		{
			for( var i:uint = 0; i < _circles.length; i++ )
			{
				removeChild( _circles[ i ] );
			}
			_circles.splice( 0, _circles.length );
		}
 
		/*
		 * The following methods are all event listeners to enable the circles to be dragged
		 */
		protected function circleDownListener( e:MouseEvent ):void
		{
			// Deselect the current circle (if there is one)
			if( _currentCircle )
			{
				_currentCircle.deselect();
			}
 
			_currentCircle = Circle( e.currentTarget );
			_currentCircle.select();
 
			stage.addEventListener( MouseEvent.MOUSE_MOVE, circleMouseMoveListener );
			stage.addEventListener( MouseEvent.MOUSE_UP, circleMouseUpListener );
 
			_dragOffset = new Point( _currentCircle.x - mouseX, _currentCircle.y - mouseY );
		}
 
		protected function circleMouseMoveListener( e:MouseEvent ):void
		{
			_currentCircle.x = mouseX + _dragOffset.x;
			_currentCircle.y = mouseY + _dragOffset.y;
			e.updateAfterEvent();
		}
 
		protected function circleMouseUpListener( e:MouseEvent ):void
		{
			stage.removeEventListener( MouseEvent.MOUSE_MOVE, circleMouseMoveListener );
			stage.removeEventListener( MouseEvent.MOUSE_UP, circleMouseUpListener );
		}
	}
}

Creating the Document Class

The document class for this application very similar to the previous one. It was already responsible for creating the save and load buttons, creating the circle container, registering the circle container with the FileUtil and initialising the container with a default state. The only thing we need to add is the registration of the circle container with the ClipboardUtil. The full contents of this class can be seen below.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

package {
	import com.bit101.components.PushButton;
 
	import couk.markstar.examples.ui.CircleContainer;
	import couk.markstar.statefultoolkit.utils.ClipboardUtil;
	import couk.markstar.statefultoolkit.utils.FileUtil;
	import couk.markstar.statefultoolkit.utils.IClipboardUtil;
	import couk.markstar.statefultoolkit.utils.IFileUtil;
 
	import flash.display.Sprite;
	import flash.events.MouseEvent;
	import flash.text.TextField;
	import flash.text.TextFieldType;
 
	[SWF( backgroundColor='#F3F3F3',frameRate='30',width='592',height='300' )]
	public class ClipboardExample extends Sprite
	{
		protected var _saveButton:PushButton;
		protected var _loadButton:PushButton;
 
		protected var _circleContainer:CircleContainer;
		protected var _fileUtil:IFileUtil;
		protected var _clipboardUtil:IClipboardUtil;
 
		/**
		 * Create the save and load buttons to save and load the state. Then create the circle container and register it with the FileUtil.
		 * By registering the container with the FileUtil it means the FileUtil knows which statable object to retrieve and set the state on
		 * when save and load are executed.
		 * Register the container with the ClipboardUtil so it can capture keyboard shortcuts.
		 */
 
		public function ClipboardExample():void
		{
			// PushButton( parent, x, y, label, MouseEvent.CLICK event listener )
			_saveButton = new PushButton( this, 196, 275, "Save", saveClickListener );
			_loadButton = new PushButton( this, 295, 275, "Load", loadClickListener );
 
			_circleContainer = new CircleContainer();
 
			_fileUtil = new FileUtil();
			_fileUtil.registerObject( _circleContainer );
 
			// ClipboardUtil requires reference to the stage so it can manage the keyboard shortcuts
			_clipboardUtil = new ClipboardUtil( stage );
			_clipboardUtil.registerContainer( _circleContainer );
 
			addChild( _circleContainer );
 
			initDefaultState();
		}
 
		protected function saveClickListener( e:MouseEvent ):void
		{
			_fileUtil.save();
		}
 
		protected function loadClickListener( e:MouseEvent ):void
		{
			_fileUtil.load();
		}
 
		/**
		 * Initialise the circle container with four circles
		 */
		protected function initDefaultState():void
		{
			var defaultState:String = '<container>';
			defaultState += '<object><x>196</x><y>100</y></object>';
			defaultState += '<object><x>196</x><y>200</y></object>';
			defaultState += '<object><x>396</x><y>100</y></object>';
			defaultState += '<object><x>396</x><y>200</y></object>';
			defaultState += '</container>';
 
			_circleContainer.setState( new XML( defaultState ) );
		}
	}
}

Testing the application

You will now be able to run the application and test that the state of the application can be saved and loaded and that you can copy and paste circles. The structure of the project can be seen below. If you do have any questions about the tutorial, or constructive criticism on the toolkit, don’t hesitate leave a comment below.

Compiled Application

Once you have compiled the application, you should get the same output as below. Try copying and pasting the circles, you will also be able to save and load the state like before.

Source Files

Source files are available from GitHub, under the heading ClipboardExample.

Now to get back to the StatefulToolkit…

In this tutorial I’ll take you through the basic premise behind the StatefulToolkit and demonstrate how it can be used in a project. If you haven’t heard of StatefulToolkit before then be sure to read up on it. This example will also demonstrate use of the FileUtil, which is a utility class included in the toolkit that allows the user to load and save states. The application is very basic and will allow the user to position four circles and to save and load the state of the circles (i.e. where the circles are positioned). The example can be seen here and source files are available.

Preparation

Before you being implementing this tutorial make sure you have the latest version of the StatefulToolkit SWC, and that you’re project is set to target Flash Player 10 (if you want to target FP9, simple replace the Vector with an array in the circle container) . This tutorial also uses Keith Peter’s Minimal Comps component set to create the buttons in the application so you may want to grab the SWC for that too, but you can use your own buttons if you prefer.

Creating the Statable Object

We’re going to start by creating the circles that the user can move. In order for the position of the circles to be saved the class must implement the IStatable interface. The class itself is very simple; the constructor creates the graphics of the circle, the retrieveState method returns the position of the circle as a String, and the setState method sets the position of the Circle based on the new state. The retrieveState and setState methods are both required by the IStatable interface. Note that I’ve put the class in the couk.markstar.examples.ui package, but you don’t have to. The full contents of this class can be seen below.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

package couk.markstar.examples.ui
{
	import couk.markstar.statefultoolkit.core.IStatable;
 
	import flash.display.Sprite;
 
	public class Circle extends Sprite implements IStatable
	{
		/**
		 * The constructor draws the circle with a grey outline
		 */
		public function Circle():void
		{
			super();
 
			drawCircle( 0x999999 );
		}
 
		/**
		 * Change the display of the circle to show it's selected
		 */
		public function select():void
		{
			drawCircle( 0x990000 );
		}
 
		/**
		 * Change the display of the circle to the default
		 */
		public function deselect():void
		{
			drawCircle( 0x999999 );
		}
 
		/**
		 * Retrieve the state of the circle storing the x and y properties
		 *
		 * @return The current state of the circle as an XML string
		 */
		public function retrieveState():String
		{
			var xml:String = '<object>';
			xml += '<x>' + x + '</x>';
			xml += '<y>' + y + '</y>';
			xml += '</object>';
			return xml;
		}
 
		/**
		 * Set the state of the circle by getting it's x and y values from the xml
		 *
		 * @param state The new state of the circle
		 */
		public function setState( state:XML ):void
		{
			x = Number( state.x );
			y = Number( state.y );
		}
 
		/**
		 * Used internally for creating the circles' graphics
		 *
		 * @param lineColor The color of the line around the circle
		 */
		protected function drawCircle( lineColor:uint ):void
		{
			graphics.clear();
			graphics.lineStyle( 1, lineColor )
			graphics.beginFill( 0xFFFFFFF );
			graphics.drawCircle( 0, 0, 10 );
			graphics.endFill();
		}
	}
}

Creating the Container

In this example the container is responsible for managing the circles. This includes creating and deleting circles, setting and retrieving the state of the circles and adding behaviours to the circles so the user can position them.

The circle container must also implement the IStatable interface ,so it can be used with the FileUtil. The container is set up to assume that an unknown amount of circles could be stored in the state, therefore there’s some additional code in the class to create and remove circles. Firstly, there’s the addObjectByState method, which takes the state of a circle as it’s parameter and creates a circle based on the state, and there’s the clearContainer method that loops through all of the circles and removes them from the stage.

The retrieveState and setState methods are also slightly different to the ones found in the Circle class. The retrieveState method loops through all circles and adding their states to the string to be returned, and the setState method clears any circles currently there and loops through the new state creating new circles as necessary. The last three methods of the class are event listeners that are there to enable the positioning of circles. The full contents of this class can be seen below.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

package couk.markstar.examples.ui
{
	import couk.markstar.statefultoolkit.core.IStatable;
	import couk.markstar.statefultoolkit.core.IStateSelectContainer;
 
	import flash.display.Sprite;
	import flash.events.MouseEvent;
	import flash.geom.Point;
 
	public class CircleContainer extends Sprite implements IStateSelectContainer
	{
		protected var _circles:Vector.<Circle>;
 
		protected var _currentCircle:Circle;
		protected var _dragOffset:Point;
 
		/**
		 * The constructor the vector containing the circles shown in the container
		 */
		public function CircleContainer():void
		{
			_circles = new Vector.<Circle>();
			super();
		}
 
		/**
		 * Retrieve the selected object
		 *
		 * @return The selected object
		 */
		public function retrieveSelectedObject():IStatable
		{
			return _currentCircle;
		}
 
		/**
		 * Check whether the container has a selected object
		 *
		 * @return Boolean denoting if the container has a selected object
		 */
		public function hasSelectedObject():Boolean
		{
			return( _currentCircle ) ? true : false;
		}
 
		/**
		 * Retrieve the state of the container and all contained circles
		 *
		 * @return The current state of the container, including the state's of all circles
		 */
		public function retrieveState():String
		{
			var xml:String = "<container>";
 
			for( var i:uint = 0; i < _circles.length; i++ )
			{
				xml += _circles[ i ].retrieveState();
			}
			xml += "</container>";
			return xml;
		}
 
		/**
		 * Add an object to the container by it's state.
		 *
		 * @param state The state of the object to add, in this case the circle
		 */
		public function addObjectByState( state:XML ):void
		{
			var circle:Circle = new Circle();
			circle.addEventListener( MouseEvent.MOUSE_DOWN, circleDownListener );
			circle.setState( state );
			addChild( circle );
			_circles[ _circles.length ] = circle;
		}
 
		/**
		 * Set the state of the container by adding all circles contained within the state. The container will be cleared first.
		 *
		 * @param state The new state of the container
		 */
		public function setState( state:XML ):void
		{
			clearContainer();
 
			for( var i:uint = 0; i < state.object.length(); i++ )
			{
				addObjectByState( XML( state.object[ i ] ) );
			}
		}
 
		/**
		 * Clear the container of all circles
		 *
		 */
		protected function clearContainer():void
		{
			for( var i:uint = 0; i < _circles.length; i++ )
			{
				removeChild( _circles[ i ] );
			}
			_circles.splice( 0, _circles.length );
		}
 
		/*
		 * The following methods are all event listeners to enable the circles to be dragged
		 */
		protected function circleDownListener( e:MouseEvent ):void
		{
			// Deselect the current circle (if there is one)
			if( _currentCircle )
			{
				_currentCircle.deselect();
			}
 
			_currentCircle = Circle( e.currentTarget );
			_currentCircle.select();
 
			stage.addEventListener( MouseEvent.MOUSE_MOVE, circleMouseMoveListener );
			stage.addEventListener( MouseEvent.MOUSE_UP, circleMouseUpListener );
 
			_dragOffset = new Point( _currentCircle.x - mouseX, _currentCircle.y - mouseY );
		}
 
		protected function circleMouseMoveListener( e:MouseEvent ):void
		{
			_currentCircle.x = mouseX + _dragOffset.x;
			_currentCircle.y = mouseY + _dragOffset.y;
			e.updateAfterEvent();
		}
 
		protected function circleMouseUpListener( e:MouseEvent ):void
		{
			stage.removeEventListener( MouseEvent.MOUSE_MOVE, circleMouseMoveListener );
			stage.removeEventListener( MouseEvent.MOUSE_UP, circleMouseUpListener );
		}
	}
}

Creating the Document Class

The document class for this application is pretty simple. It’s responsible for creating the save and load buttons, creating the circle container, registering the circle container with the FileUtil and initialising the container with a default state. The save and load buttons are created using the Minimal Comps component set, you can replace these with buttons of your own if you choose not to use them. The full contents of this class can be seen below.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

package
{
	import com.bit101.components.PushButton;
 
	import couk.markstar.examples.ui.CircleContainer;
	import couk.markstar.statefultoolkit.utils.FileUtil;
	import couk.markstar.statefultoolkit.utils.IFileUtil;
 
	import flash.display.Sprite;
	import flash.events.MouseEvent;
 
	[SWF( backgroundColor='#F3F3F3',frameRate='30',width='592',height='300' )]
	public class SaveLoadExample extends Sprite
	{
		protected var _saveButton:PushButton;
		protected var _loadButton:PushButton;
 
		protected var _circleContainer:CircleContainer;
		protected var _fileUtil:IFileUtil;
 
		/**
		 * Create the save and load buttons to save and load the state. Then create the circle container and register it with the FileUtil,
		 * by registering the container with the FileUtil it means the FileUtil knows which statable object to retrieve and set the state on
		 * when save and load are executed.
		 */
		public function SaveLoadExample():void
		{
			// PushButton( parent, x, y, label, MouseEvent.CLICK event listener )
			_saveButton = new PushButton( this, 196, 275, "Save", saveClickListener );
			_loadButton = new PushButton( this, 295, 275, "Load", loadClickListener );
 
			_circleContainer = new CircleContainer();
 
			_fileUtil = new FileUtil();
			_fileUtil.registerObject( _circleContainer );
 
			addChild( _circleContainer );
 
			initDefaultState();
		}
 
		protected function saveClickListener( e:MouseEvent ):void
		{
			_fileUtil.save();
		}
 
		protected function loadClickListener( e:MouseEvent ):void
		{
			_fileUtil.load();
		}
 
		/**
		 * Initialise the circle container with four circles
		 */
		protected function initDefaultState():void
		{
			var defaultState:String = '<container>';
			defaultState += '<object><x>196</x><y>100</y></object>';
			defaultState += '<object><x>196</x><y>200</y></object>';
			defaultState += '<object><x>396</x><y>100</y></object>';
			defaultState += '<object><x>396</x><y>200</y></object>';
			defaultState += '</container>';
 
			_circleContainer.setState( new XML( defaultState ) );
		}
	}
}

Testing the application

You will now be able to run the application and test that the state of the application can be saved and loaded. The structure of the project can be seen below. If you do have any questions about the tutorial, or constructive criticism on the toolkit, don’t hesitate leave a comment below.

Compiled Application

Once you have compiled the application, you should get the same output as below. Try moving the circles, saving the state then moving the circles again and loading the state. Notice that the circles go back to the saved state when it’s loaded.

Source Files

Source files are available from GitHub, under the heading SaveLoadExample.

What is it?

The StatefulToolkit was developed to enable the simple management of states in AS3. At the heart of the toolkit is one interface called IStatable. Any object that requires the retrieval or setting of its state must implement this interface. The toolkit comes with utility classes to help carry out some of the basic tasks associated with state management.

What’s included in the beta?

The initial 0.1 beta release includes the interfaces to implement and two utility classes, one to aid in saving and loading states and another to enable clipboard management, so you can copy and paste objects.

The utility classes are both currently optimized for the Flash Player – that’s not to say they can’t be used in the AIR runtime (they’d work perfectly fine) but they take into account the security sandbox restrictions that are found in the Flash Player. For example, the FileUtil allows you to save and load states, but does this using the FileReference class whereas in an AIR application you may want this to be done silently (without the browse box appearing), which would use the File class.

Why is it in beta?

The main reason is that it’s still in early stages of development; I haven’t implemented all of the features yet and the code hasn’t been optimized, that being said it is stable in its current release. I’d also like to get some community feedback on the project before making a 1.0 release.

Where can I get it?

The source code is available at GitHub, alternatively you can download the SWC on the downloads page of the project.

Where can I find examples?

I’ll be posting tutorials for some example projects on this blog and you can find all example projects on the downloads page of the project in GitHub. This will evolve as the toolkit expands.

Where would I use it?

Essentially it can be used for any application that needs it’s state saving. However, I think it would be useful in the following type of applications:

• Wireframing applications, such as Balsamiq Mockups and LovelyCharts
• Game level editors
• Drawing tools
• General applications (for things like panel states, window positions, settings panels, etc)

What have you got planned for the future?

More utility classes! In the near future there will be a utility class to allow history management (undo and redo). Following this I want to create AIR versions of the utility classes and provide some form of automation for the setting and retrieval of states, so you don’t have to construct and parse the XML manually.

How can I help?

Feedback! Whether its feature requests, bugs, constructive criticism or just general questions about the toolkit, I want to hear it. You can either post comments on this blog, or file issues for the project at GitHub.