Stage3D

ND2D – Fast, easy-to-use 2D framework built on top of Stage3D
https://github.com/nulldesign/nd2d

Marco Scabia’s articles on ADC. Best introduction to stage3D i have read (ie: the only one’s i understood!)
http://www.adobe.com/devnet/author_bios/marco_scabia.html

Coding Skills

Lifting the lid on a ton of little known features of ActionScript and Flex (don’t let the title deceive you – only about half is Flex specific)
http://tv.adobe.com/watch/max-2011-develop/discover-the-unknown-flex-45/

Need to brush up on your Maths? Who doesn’t? Here’s a huge bank of videos by the world’s greatest teacher
http://www.khanacademy.org/

Using RobotLegs or thinking about it? This book tells you everything you need to know (and in my case, everything i was doing wrong!)
http://shop.oreilly.com/product/0636920021216.do

To get around the limitation of neighbours (see the end of part two) we need to create a system of our own to let each peer know about all the other peers in the group. Then we can use the techniques of part two to send messages to any peer.

Here it is in action (open some copies of this page to get the member count to 16 or above if you wish):

{P2PLanExample3}

How It Works

There are no methods, classes or events in the code that aren’t covered in part 1 or 2 so i won’t explain the actual code used (the commented source code is available at the bottom of the post). Rather, i will explain the flow of messaging that allows every peer to know the id of every other.

When a new peer joins the group it sends out a group post (ie: to all peers in the group) containing the peer id of the new member. All peers store the received id, so every peer now knows about the new guy. Next, each peer sends a directed message back to the new peer containing their peer id – so now the new member knows about every other peer. Bingo! Now we can send a text message to anyone in the group using the techniques of part 2.

When a peer leaves the group, it would be nice if it could send out a group posting letting all the peers know to remove it from their list, but unfortunately this won’t work (for me at least) if the swf is running in a browser and the browser window/tab is closed (in short, there’s no way to send out the “i am disconnecting” group post message before the NetConnection has been closed). Luckily, the solution is straight-forward.

When a peer disconnects, its neighbours receive a NetGroup.Neighbor.Disconnect event. So we just get the neighbour to send out a “he is disconnecting” group post message instead. Easy peasy!

Of course, if you’re using AIR you can listen for the application exiting event and send the “i am disconnecting” group post directly, but this way works for a swf environment too.

Notes On The Code

This code does result in some duplication of messaging – for instance, every neighbour of a disconnecting peer will send out the same group post which could result in up to 13 identical post messages where only 1 is needed. Improving efficiency i leave as an exercise for the reader (a few pleadings in the comments might persuade me to get off my lazy backside).

We listen for the NetGroup.Neighbor.Connect event rather than the NetGroup.Connect.Success before dispatching the “i have connected” message (setting a flag to stop later NetGroup.Neighbor.Connect events triggering repeated “i have connected” messages). There’s no point sending a message if there are no other peers in the group!

The code uses messaging objects with either a cmd property (for behind-the-scenes messages, ie: managing the peer lists as explained above) or a txt property for messages that the user is sending.

In response to Rackdolls wise comment in part 2, i have used a belt and braces approach to unique ids for the messaging object this time – in addition to the date in milliseconds used before, each object now also contains the senders peer id and a random number.

Further Reading

If you want to see exactly how p2p is working under the hood there are some good sessions from MAX on adobe tv:

http://tv.adobe.com/watch/max-2009-develop/p2p-on-the-flash-platform-with-rtmfp/

http://tv.adobe.com/watch/max-2011-develop/advanced-p2p-with-rtmfp-tips-and-tricks/

For a ton of tutorials and info try:

http://www.flashrealtime.com/

And lastly, here’s the source code for this post: P2PLanExamples3.zip

{P2PLanExample2}

Note that i have removed the [EVENT] traces that exist in the part 1 example.

Sending a message to a specific peer is slightly more complex than the group posting behaviour in part 1; first we first need to know who the peers are (or more specifically, their peer IDs) before we can send a message to them.

So, in the constructor i’ve added a couple of extra UI elements; a Label to display the instances’ peer ID, and a ComboBox to hold a list of connected peers (and an “ALL” option to allow a group posting as before).

As with group posting, we need to enable direct routing before we can use it. We set the appropriate permission on the GroupSpecifier object in the setupGroup method:

//enable posting (to entire group)
groupspec.postingEnabled = true;
//enable direct routing (to individual peer)
groupspec.routingEnabled = true;

Ok, now for maintaining a list of peers. If you take a look at the live example in part 1, you’ll see in the output that an event is being fired whenever a peer joins or leaves the group (the info.code property of the event is being displayed).

The relevant codes are “NetGroup.Neighbor.Connect” and “NetGroup.Neighbor.Disconnect”. By listening for these, we can maintain a list of connected peers. When these events fire i just add or remove the peer from the ComboBox list:

//neighbour connected so add details to list
case "NetGroup.Neighbor.Connect":
	var peer:Object = new Object();
	peer.id = event.info.peerID.toString();
	peer.label = truncateString(event.info.peerID);
	peerList.addItem(peer);
	break;
 
//neighbour disconnected so remove details from list
case "NetGroup.Neighbor.Disconnect":
	var len:uint = peerList.items.length;
	for (var i:uint=0;i<len;i++)
	{
		if (peerList.items[i].id==event.info.peerID)
		{
			peerList.removeItemAt(i);
			break;
		}
	}
	break;

The important data is the event.info.peerID property – this is our reference to the peer and allows us to direct messages to it. The peerID is a 64 character string which is why i am using a truncateString method to reduce it’s length where it’s being displayed in the UI.

Now we are ready to send out messages to specific peers. Here’s the revised button handler method:

private function btnHandler(event:MouseEvent):void
{
	// Create an object to hold the data to send
	var obj:Object = new Object();
	//add the data
	obj.txt = inputText.text;
	//add some extra data to ensure every sent object is unique
	obj.id = new Date().time;
	//update UI
	outputText.text += "[SENDING TO "+peerList.selectedItem.label+"]\n"+inputText.text+"\n";
 
	if (peerList.selectedItem.label=="ALL")
	{
		//send to everyone in group
		group.post(obj);
	}
	else
	{
		//get group address of peer
		var destination:String = group.convertPeerIDToGroupAddress(String(peerList.selectedItem.id));
		//save to message object
		obj.destination = destination;
		//send message
		group.sendToNearest(obj, destination);
	}
}

We create the object to send, update the UI and check the ComboBox selection. If it’s “ALL” we do a group post as before, otherwise we direct it to the specified peer:

First, we use the convertPeerIDToGroupAddress method of our NetGroup instance to create (unsurprisingly) a group address from the peer ID. Next we add this group address to our message object (we’ll need it later).

Lastly, we call the sendToNearest method of our NetGroup – passing our message object and the destination group address as arguments.

Note that this method doesn’t necessarily send the message directly to the recipient. It may only send it part of the way so we’ll need to cover that possibility in our code (which we will).

The last bit of code we need to add is for listening and responding to incoming (directed) messages. Again, we get a NetStatusEvent.NET_STATUS event when a directed message is received – this time with an info.code of “NetGroup.SendTo.Notify”. Here’s the code for it:

//directed message received so check if this is the final destination
case "NetGroup.SendTo.Notify":
	if (event.info.fromLocal==true)
		//is destination so display it
		outputText.text += "[RECEIVED]\n"+event.info.message.txt+"\n";
	else
		//not destination so re-send
		group.sendToNearest(event.info.message, event.info.message.destination);
	break;

First we check to see if this is the final destination of the message. The info.fromLocal property of the event tells us this – if it’s true, this is the final destination.

If this is the destination we add the message text to the UI, otherwise we call sendToNearest to send the message on its next hop towards its destination. This is why we added the destination to the original message object – so we could extract it and use it as the second argument for any further sendToNearest calls.

And that’s it – group posting and directed routing both working on a peer-to-peer group on a local area network. Or is it…

A Rather Large Gotcha

Take a p2p group consisting of 1000 peers; if every peer was directly connected to every other, there would be approximately 500,000 connections across the local network – i’m no network expert but i’m guessing that’s frowned upon.

To avoid this, peers are directly connected to only a few neighbouring peers  - hence the info.code of ”NetGroup.Neighbor.Connect” rather than “NetGroup.Peer.Connect”.  Unfortunately, there is no event for a non-neighbour dis/connecting and that’s a problem.

As we saw above, we use sendToNearest to bunny-hop a message to it’s destination – which is fine as long as we know the peer ID of the destination- but if it’s not a neighbour we’ll never get informed about it connecting, and can’t retrieve a peer ID to direct messages to.

The important number here is 14 – in a p2p group of 14 or less members, every peer is always a neighbour of every other.

So for 14 or less peers, the code above works just fine. For 15 and above, it’s back to the drawing board…

I plan to cover 15+ members in part 3, but to be honest i haven’t actually decided on a strategy yet (let alone implemented it) so that may turn out to be a hollow promise.

And on that bombshell, here’s the latest source: P2PLanExamples2.zip

Below are two instances of the same swf; anything entered in the input field will be sent to all other instances of the swf and appear in their text areas – feel free to open more copies of this page if you want to increase the number of swfs. I also trace out some basic info to the text area so you can see whats going on behind the scenes.

You should get an annoying Flash Player alert asking you to confirm that you are happy to allow p2p for this website before it is activated (sigh):

{P2PLanExample1}

And here’s the code (using MinimalComps for the UI):

package
{
	import com.bit101.components.InputText;
	import com.bit101.components.PushButton;
	import com.bit101.components.TextArea;
 
	import flash.display.Sprite;
	import flash.events.MouseEvent;
	import flash.events.NetStatusEvent;
	import flash.net.GroupSpecifier;
	import flash.net.NetConnection;
	import flash.net.NetGroup;
 
	[SWF(width="250",height="300",backgroundColor="#EEEEEE")]
	public class P2PLanExample1 extends Sprite
	{
		private var netConn:NetConnection;
		private var group:NetGroup;
 
		private var inputText:InputText;
		private var outputText:TextArea;
		private var submitButton:PushButton;
 
		public function P2PLanExample1()
		{
			//create UI (using minimalComps)
			inputText = new InputText(this, 10, 10, "");
			submitButton = new PushButton(this, 120, 10, "Send", btnHandler);
			submitButton.width = 70;
			submitButton.enabled = false;
			outputText = new TextArea(this, 10, 35, "");
			outputText.width = 230;
			outputText.height = 255;
 
			//setup connection object
			netConn = new NetConnection();
			//listen for result of setup
			netConn.addEventListener(NetStatusEvent.NET_STATUS, netHandler);
			//connect to LAN
			netConn.connect("rtmfp:");
		}
 
		private function btnHandler(event:MouseEvent):void
		{
			//update UI
			outputText.text += "[SENDING]\n"+inputText.text+"\n";
			// Create an object to hold the data to send
			var obj:Object = new Object();
			//add the data
			obj.txt = inputText.text;
			//add some extra data to ensure every sent object is unique
			obj.id = new Date().time;
			//send to everyone in group
			group.post(obj);
		}
 
		private function netHandler(event:NetStatusEvent):void
		{
			//update UI
			outputText.text += "[EVENT]\n"+event.info.code+"\n";
			//handle event
			switch(event.info.code)
			{
				//connection succeeded so setup a group
				case "NetConnection.Connect.Success":
					setupGroup();
					break;
				//group setup succeeded so enable submit
				case "NetGroup.Connect.Success":
					submitButton.enabled = true;
					break;
				//posting received so add to output
				case "NetGroup.Posting.Notify":
					outputText.text += "[RECEIVED]\n"+event.info.message.txt+"\n";
					break;
			}
		}
 
		private function setupGroup():void
		{
			//create a GroupSpecifier object
			var groupspec:GroupSpecifier = new GroupSpecifier("myGroup");
			//enable posting (to entire group)
			groupspec.postingEnabled = true;
			//allow data to be exchanged on IP multicast sockets
			groupspec.ipMulticastMemberUpdatesEnabled = true;
			//set the IP adress and port to use
			groupspec.addIPMulticastAddress("225.225.0.1:30000");
			//create NetGroup with our NetConnection using GroupSpecifier details
			group = new NetGroup(netConn, groupspec.groupspecWithAuthorizations());
			//listen for result of setup
			group.addEventListener(NetStatusEvent.NET_STATUS, netHandler);
		}
 
	}
}

Setting Up

In the constructor i create the UI and then set up a NetConnection object. By passing only the protocol when calling connect (netConn.connect("rtmfp:");), we are telling FP that we want a local network connection. RTMFP stands for Real Time Media Flow Protocol btw.

If this was an internet-wide p2p setup, we would use something like netConn.connect("rtmfp://myServer.com/myPath"); to connect to a remote server (which helps set up the p2p connections – you wouldn’t want to connect to every flash player connected to the Internet would you?).

Once the NetConnection succeeds (or fails), a NetStatusEvent.NET_STATUS event is fired – which is picked up by the netHandler method. The info.code property of the NetStatusEvent can be used to determine what happened – in this case we are hoping for “NetConnection.Connect.Success” (and not “NetConnection.Connect.Failed”; a full list of possible codes is available at http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/events/NetStatusEvent.html).

Once the NetConnection object is ready, we set up a NetGroup in the setupGroup() method. First, we create a GroupSpecifier object and set some properties – giving the group a name of “myGroup” (you can have multiple groups), enabling posting to all members of the group, telling the group to use IP sockets and finally stating the IP address and port to utilise – 225.225.0.1:30000 is the value used in the AS3 docs and it works for me, so i suggest leaving it as it is unless you feel a need to change it.

Lastly, we create the NetGroup object, passing in a reference to the NetConnection and utilising a GroupSpecifier helper method to pass the groupspec data.

Success (or failure) of the NetGroup initialisation will be signalled by another NetStatusEvent.NET_STATUS event – this time with a code of “NetGroup.Connect.Success”. Once the NetGroup is ready, p2p communication is good to go.

Send And Receive

Sending data is managed here by the btnHandler method; we simply create an Object, attach some data to it (in this case, the text from the input field), and pass the object to the NetGroup post method. That’s it.

Incoming data (sent from the post method) fires a NetStatusEvent.NET_STATUS event with a code of “NetGroup.Posting.Notify”. The info.message property of the event is the same Object that was sent with the post method, so for this example (in netHandler method) the text data is in event.info.message.txt. Here we just add it to the output text area.

Final Thoughts

There can be a noticable lag between sending and receiving when the NetGroup is first initialised, but this usually improves greatly after a few messages have been sent.

Also, i should make clear that the swfs don’t need to be on the same device – it really is the whole local network – so if your phone hooks ups to your wifi when you’re at home, a swf in your browser could communicate with an AIR app running on your phone (use your phone as a remote control for a game running in the browser for example).

In part 2, i will extend this example to display info about members of the group and configure message sending to specific users. Until then, here’s the source code: P2PLanExamples1.zip

/* UPDATE */

It turns out that every message object sent must be completely unique or it may get ignored (ie: mistaken for a previous message already received). For instance, sending “hello” twice, may result in only a single “hello” being received.

Luckily, we can easily cover this by adding a unique property to each message object to ensure no two are ever alike. I have amended the btnHandler method to include a time stamp on each message object. Job done.

//add some extra data to ensure every sent object is unique
obj.id = new Date().time;

How is it done? Well the clue is in the title – we use the External Interface class. This is an ActionScript class that can communicate with the container for the swf – in this case, the browser. Of course, browsers being what they are, it doesn’t work with everything, but the main players are all covered (at least for the desktop). See the docs for details of compatibility.

Flash To JavaScript

Here’s an example of calling a JavaScript function:

{ExternalInterfaceExample1}

Clicking the button calls this method:

private function clickHandler(event:MouseEvent):void
{
	if (ExternalInterface.available)
		ExternalInterface.call("alert", "Hello from Flash!!!");
}

First we check that ExternalInterface will work (ie: that ExternalInterface.available is true) and then use the call method to trigger a JavaScript function. The first argument is the name of the JavaScript function to call and any remaining arguments are passed to the JavaScript function as its arguments. In this case i am calling the built-in JavaScript function ‘alert’ (which displays an alert popup); alert takes a string (to display) as its argument which in this case is ‘Hello from Flash!!!’. Simple.

We are not restricted to built-in functions though – any JavaScript functions defined in the HTML container (ie: within HTML <script> tags or linked external .js files) can be called. This example calls a JavaScript function that’s embedded in the page:

function myFabFunction(colour)
{
       	document.body.style.backgroundColor = colour;
}

{ExternalInterfaceExample2}

The AS method just alternates between passing white and red colour values:

private function clickHandler(event:MouseEvent):void
{
	flag = !flag;
	if (ExternalInterface.available)
	{
		ExternalInterface.call("myFabFunction", flag ? "#FFFFFF" : "#FF0000");
	}
}

Not a very imaginative or useful example, but it shows that we can manipulate the page DOM from Flash. With this gateway to the browser, we can call our own functions or hook into established libraries like jQuery to do the leg work.

JavaScript To Flash

Now for the reverse. Try resizing the browser window: the current date should appear in the brownish box below.

{ExternalInterfaceExample3}

This is the JavaScript code:

window.onresize = function(){
document.getElementById('swfobj_2').setFlashLabel(new Date());
}

This listens for a resize and then calls the method setFlashLabel, passing the current date as the argument (the swf file has an id of swfobj_2 so we use document.getElementById('swfobj_2') to get a reference to it. disclaimer: i’m not a JavaScript expert so there may be a better way).

Inside Flash we need to do 2 things. First we let ExternalInterface know that we have a method we wish to expose to JavaScript:

ExternalInterface.addCallback("setFlashLabel", setLabel);

The first argument of addCallback is the function name that JavaScript will use (see JavaScript code snippet above) and the second is the method in Flash. Here it is setLabel which just updates the textfield with the passed argument and then centers it.

private function setLabel(value:String):void
{
	tf.text = value;
	tf.x = int((400-tf.width)*0.5);
	tf.y = int((200-tf.height)*0.5);
}

There’s no reason why you shouldn’t use the same name for both arguments – i have just differentiated them so it’s easier to see which name refers to which side (and remember that the first argument is a String type and the second is a Function type).

And the circle is complete: ActionScript can talk to JavaScript and JavaScript can talk to ActionScript.

Final Note

One caveat: this blog uses SWFObject to embed the examples and I was forced to use SWFObject in dynamic mode for example 3 – JavaScript to Flash doesn’t seem to work when using static mode.

And that’s all there is to it. Here’s the source code: ExternalInterfaceExamples.zip

Without SWFAddress

Here’s a simple example of a 3 page site:

{SWFAddressExample1}

Here’s a quick overview of how the navigation works: when a button is clicked, this method is called:

private function clickHandler(event:MouseEvent):void
{
	showPage(int(event.target.name));
}

which takes the button name (each buttons name property is either “1″, “2″ or “3″), converts it to an integer and passes the value on to showPage:

private function showPage(index:int):void
{
	page1.visible = index==1;
	page2.visible = index==2;
	page3.visible = index==3;
}

This method just sets each pages’ visibility depending on the value of index. Pretty simple stuff. Needless to say, this is not the best way to handle multiple views (you should at least be removing them from the display list; if not destroying and recreating… but that’s another story). The point to note from this is that clickHandler calls showPage directly. With SWFAddress we do things slightly differently.

With SWFAddress

First off, SWFAddress requires SWFObject to work so read part one first, if you’re not yet using it. Otherwise head over to asual.com/swfaddress to download the latest source files (version 2.4 as i write this). Here is the same ‘site’ with deep linking enabled thanks to SWFAddress. Open a few pages with the 3 buttons to build up some history and then try the browser back/forward buttons. Pretty neat, huh!

{SWFAddressExample2}

Notice that the browser address updates every time you change the ‘page’ – adding (eg) #/1 to the end of the URL. This is the trick – changing the URL beyond the # adds new history to the browser (allowing back/next to navigate this history)  but does not cause the browser to refresh the page.

The first step was to add a link to the SWFAddress JavaScript library (swfaddess.js from downloaded source files) within this HTML page – and it’s important that the link to swfaddress.js is below the link to swfobject.js, eg:

<head>
	<script type="text/javascript" src="swfobject.js"></script>
	<script type="text/javascript" src="swfaddress.js"></script>
</head>

Next, the SWFAddress ActionScript library needs including – the downloaded source files come with AS1, AS2 and AS3 libraries, but as this is the 21st century, i will only cover AS3. The library is provided as a SWC  or as two AS3 files (SWFAddress.as and SWFAddressEvent.as).

Add library in Flex Builder/Flash Builder: Select ‘Properties’ from the ‘Project’ menu and choose ‘ActionScript Build Path’. Ensure that you are in ‘Library Path’, click on ‘Add SWC…’ and browse to the swc file you just extracted from the zip. Select it and click ‘ok’ to add it to the project.

Add library in Flash Professional:In the properties panel, click on the ‘Edit…’ button next to ‘ActionScript Settings’. In the subsequent pop-up window, ensure you are in ‘Library path’ and click on the ‘+’ symbol to add a new path and then click on the Flash (‘f’) icon to browse to the swc file you just extracted. Double click the swc file and you will see it listed. Now click on ‘ok’ to close the pop-up window.

Now we are ready to code…

In example 1 we called showPage directly from clickHandler. This time we call showPage indirectly – using SWFAddress as the middleman. clickHandler now looks like this:

private function clickHandler(event:MouseEvent):void
{
	SWFAddress.setValue("/"+event.target.name);
}

We call the static method setValue(), passing a string as the argument – the first character needs to be “/” and here i am adding either “1″, “2″ or “3″ depending on the button clicked. This will cause the browser address to update (to become …#/1 or …#/2 or …#/3 in this case). Now we listen for a browser address change (note that SWFAddress is a static class so we add listener to class rather than creating an instance of it):

SWFAddress.addEventListener(SWFAddressEvent.CHANGE, swfaddressHandler);

and then update the page based on the result:

private function swfaddressHandler(event:SWFAddressEvent):void
{
	//should be r on end of subst but wordpress throwing a wobbly!
	var pageIndex:int = int(event.value.subst(1));
	if (pageIndex==0)
		pageIndex = 1;
	showPage(pageIndex);
}

The value property of the SWFAddressEvent contains the text beyond the # (so the first character will be “/”). In this example, we strip off the slash, convert to an integer and store the result in pageIndex. After a quick validation check we call showPage as normal. If the address in the browser doesn’t contain a # then the value returned is a single “/” – in the code above, a single slash results in pageIndex of zero; in which case revert to the default (page 1).

In example 1, i called showPage(1); in the constructor to display the first page. In example 2 this isn’t necessary as SWFAddress fires a CHANGE event on startup – and this is used to trigger the initial page to display. Not only does this allow us to add back/next navigation but we could also provide links to specific content rather than the default ‘home’ page (eg: www.mycompany.com#/great-bargains).

Lastly i should mention that in the real world we would want to add some validation to the values coming in – after all, the user could type anything in the address bar. For this example, changing the URL to “…#/4″ results in no page being displayed – not professional. not professional at all.

Here’s the source code (excluding SWFAddress libraries): SWFAddressExamples.zip

I categorise my use of JavaScript into three areas: 1. Essential: embedding Flash in HTML (and providing alternative content), 2. Semi-essential: deep-linking (using browser back/next buttons for Flash navigation) and 3. Optional: everything else. I will cover 2 & 3 in later posts, but first…

1. Embedding Flash with SWFObject

Ok, you can skip over this because you already use SWFObject, right? If you’re not using it, then you’re doing it wrong (imho)! To quote the SWFObject website, “SWFObject is an easy-to-use and standards-friendly method to embed Flash content, which utilizes one small JavaScript file” – note the terms “easy-to-use”, “standards-friendly” and “one small”; music to my ears.

Even Adobe recommend and use it. Recent versions of Dreamweaver, Flash Pro and Flash Builder all use it; although not necessarily in the best way – I never use the HTML that Dreamweaver/Flash/Flash Builder generates, but create it like this…

First, download the latest code (version 2.2 as i’m writing) from http://code.google.com/p/swfobject/. Download the zip file and extract the contents for later.

Next, visit the online generator: http://www.bobbyvandersluis.com/swfobject/generator/index.html. This will generate the HTML for us (alternatively, offline AIR and HTML versions can be downloaded from the SWFObject site).

You’ll see this form:

Most of the form fields should be fairly self-explanatory but some do need explanation;

SWFObject (.js)

The path and filename of the swfobject.js file that you extracted from the zip file.

Publishing method

Either ‘Static’ or ‘Dynamic’. The static method embeds both the flash and the alternative content within the HTML page. The dynamic method only includes the alternative content within the page; it is replaced with the flash content at runtime (ie: once it has been loaded into the browser).

Detect Flash version

The minimum version of Flash Player required to view your swf.

Adobe Express Install

The path and filename of the expressInstall.swf file from zip file (only required if ticked). This allows the user to download and install the latest version of Flash Player without having to visit the Adobe site (as long as they already have version 6.0.65 or later).

Flash (.swf)

The path and filename of the swf file.

Dimensions

Width and height of the swf; either in pixels or percentages.

Flash content id

The ID to give the flash content in the HTML.

More

Further options can be included by clicking on the ‘more’ link below the content id field – this will reveal more fields for attributes (eg: alignment), parameters (eg: background colour) and FlashVars.

HTML Template

HTML document type.

Character encoding

HTML document character encoding.

Alternative content

HTML content to display when Flash content is not shown (eg: when user does not have Flash installed) – this content will also be indexed by search engines so it’s a great place to add some SEO stuff.

Generate HTML

The only decision to make is whether to use static or dynamic publishing. For me, the only answer is static publishing – it uses standards compliant markup and will still display the flash content if JavaScript has been turned off or isn’t available.

All we need to do is complete the form and click on ‘Generate’. This will output the required HTML below the generate button; which can then be copy/pasted in to your preferred HTML editor. Finally, copy the swfobject.js file (and the expressInstall.swf file if you ticked ‘Adobe Express Install’) from the downloaded zip into the location(s) you specificied in the form and you’re done (there are actually 2 swfobject.js files in the zip; one minimised and one not minimised – either will do but it’s best to use the smaller one for obvious reasons).

As i said at the top of the post, using SWFObject is not optional; it’s essential, it’s mandatory, it’s obligatory. It’s.. well you get the picture.

In  part 2, i will cover the semi-essential stuff – deep linking using SWFAddress – and guess what! SWFAddress requires SWFObject to work – so that make SWFObject essential, mandatory, obligatory…

To grab the colour in response to a mouse event:

//add listener for mouse clicks
stage.addEventListener(MouseEvent.CLICK, eventHandler);
 
function eventHandler(event:MouseEvent):void
{
	//1x1 bitmapData to store snapshot
	var bmd:BitmapData = new BitmapData(1, 1);
	//matrix object to 'move' stage so that pixel under mouse is effectively at 0,0
	var matrix:Matrix = new Matrix();
	//'move' stage according to mouse x,y values
	matrix.translate(-event.stageX, -event.stageY);
	//take snapshot of stage
	bmd.draw(stage, matrix);
	//get colour from snapshot data
	var pixel:uint = bmd.getPixel(0, 0);
	//trace result
	trace("colour = "+pixel.toString(16));
}

First, we setup a 1 pixel by 1 pixel BitmapData object; we are only interested in grabbing one pixel so there’s no need for anything larger.

Next, we setup a Matrix object and apply its translate method using negative mouse position values – this effectively moves the object that will have it’s snapshot taken with the draw() method – normally draw() will start copying from 0,0 of the source object but we only have room in our BitmapData object for a single pixel – the translated Matrix allows us to start copying at a different position. Namely, the position of the mouse.

Now we use the draw() method to take the snapshot (if you more details on this and other methods of BitmapData, see BitmapData Basics Part 1) and the getPixel() method to extract the colour of the single pixel. Hopefully, you can do something more interesting with the information than trace!

If you want to sample a specific object rather than the whole stage, just add an event listener to it (rather than the stage) and change the matrix translation to:

matrix.translate(-event.localX, -event.localY);

If you’re not responding to a mouse event, you can still get the mouse position from the display object you are targeting; eg: stage.mouseX or myMovieClip.mouseY. So the code would become (for stage version):

function getColour():void
{
	var bmd:BitmapData = new BitmapData(1, 1);
	var matrix:Matrix = new Matrix();
	matrix.translate(-stage.mouseX, -stage.mouseY);
	bmd.draw(stage, matrix);
	var pixel:uint = bmd.getPixel(0, 0);
	trace("colour = "+pixel.toString(16));
}

Told you it was easy…

Its not totally my fault – if Adobe are going to release Spark (Flex 4 SDK) and make it much better than Halo (Flex 3) then i can hardly be blamed for wanting to completely rewrite my app (and get to grips with Spark in the process). Anyway, only one year late on delivery – not bad for an IT project – it’s finally finished.

Here’s the link (i guess the domain tells you what it is): mandelbrot-explorer.com. I am fascinated by fractals, so i built the app to generate desktop wallpapers – its hardly the only one out there, but all the others seem to be Java applets – i haven’t seen a Flex (or pure Flash) one so let me know if you are aware of any.

If you interested in the technicals, it is a Flex 4 application with a standard MVC architecture (utilising RobotLegs). I apologise for the programmer art of the app, but i am not a designer.

As the project was a learning exercise for me, i don’t want to release the source code – some of the code was written before i really understood the best way to do things, so i don’t want to send anybody off in the wrong direction by following what i did. However, some parts of the code can be found elsewhere in this blog:

• Drawing the Mandelbrot graph uses bitmap drawing methods explained in BitmapData Basics Part 1
• Drawing the graph over multiple frames uses the threading technique as described in Saving An Image To HD With ActionScript Part 2
• Save feature uses the code and encoding classes provided in Saving An Image To HD With ActionScript Part 2

I plan to do some Flex-related posts soon(ish) but for now it’s back to the day job…