Interface Between Two Files Using the LocalConnection Class

In this tutorial we will use the AS3 LocalConnection class to send and receive data between two different SWF files. Today we will use this to detect mouse movement in one SWF and mirror it in another.

Final Result Preview

Let's take a look at the final result we will be working towards. Below are two completely different files.

This tutorial is split into two sections. The first will concentrate on the sending SWF and the second will involve building the receiving SWF. I will also be using the document class throughout this tutorial.

Section 1: Sending Information

Step 1: Sending New Flash Document

Firstly, create a new ActionScript 3.0 file.

Then, resize the file to 600px × 250px.

Step 2: Sending Add a Background

This step is not necessary for functionality, but more for aesthetics. Add your image to the stage and then lock its layer.

Step 3: Sending Create Document Class

Save your FLA as Sending.fla and then create a blank AS file. Save this file in the same folder as your FLA and name it Sending.as.

Then go back and link the document class to the FLA.

Step 4: Sending Set Up Document Class

Add a blank package, class and constructor function to your AS file.


package {

	public class Sending extends MovieClip {

		public function Sending() {
		}

	}

}

Step 5: Sending Import Classes

The first thing we need to do in our document class is to import all the classes which we will need in the future.


package {

	import flash.display.MovieClip;
	import flash.events.Event;
	import flash.events.StatusEvent;
	import flash.events.MouseEvent;
	import flash.net.LocalConnection;

	public class Sending extends MovieClip {

		public function Sending() {
		}

	}

}

Step 6: Sending LocalConnection Usage

Before we start sending information with a Local Connection, it is best that we learn exactly how to use it. This is really simple and consists of only two parts:

Declaring an instance of the class.
Using the .send() method.

Declaring an instance of the Local Connection class is easy:

1
2	private var localConnection:LocalConnection = new LocalConnection();

Next we need to use the .send method. This method connects to the other SWF and then triggers a function in the receiving file which handles any variables which are sent across. Let's see an example:

1
2	localConnection.send("_connectionName","methodName",variable1,variable2);

Both the connection name and the method name should be enclosed in quotation marks (as they are strings). In addition, it is best to start the connection name with an underscore ( _ ). The method name is simply the name of the function which you want to be triggered in the receiving SWF. The function, in the receiving SWF, will be provided with the variables as arguments. Now, let's use what we've just learnt!

Step 7: Sending Variables & Constructor

Here are all the variables we need to declare:


private var localConnection:LocalConnection = new LocalConnection();

private var mX:Number;
private var mY:Number;

After declaring an instance of our local connection, we create two variables. mX will hold the mouse's 'x' value and mY will hold the mouse's 'y' value. This code needs to be placed before the constructor function, but inside the class.

Next is the constructor function. This function contains just one line: adding an event listener for the Event.ENTER_FRAME event. We will cover the function it calls in the next step. Here is the finished constructor function:

1
2	public function Sending() {
3	stage.addEventListener(Event.ENTER_FRAME,mainLoop,false,0,true);
4	}

Step 8: Sending mainLoop Function

In the previous step, we created an event listener which calls this function once every frame. This function will be doing two things. The first is to set the variables mX and mY equal to the mouse's 'x' and 'y' position respectively. The second is to send these two variables, through the Local Connection, to the other SWF file.

Here is the finished function:


private function mainLoop(e:Event):void {
    mX = mouseX;
    mY = mouseY;
    
    localConnection.send("_mouseConnection","processData",mX,mY);
}

When sending the data, we use "_mouseConnection" as the connection name and "processData" as the method name. This means it will try to call processData(mX, mY).

Step 9: Sending Status Event

We are very nearly finished. All that remains to be done is to handle the status event. The LocalConnection object dispatches status events; in this project we will not be using the events; however, if we do not listen out for them, we will receive errors such as this: 'Error #2044: Unhandled StatusEvent:. level=error,code='

We have already imported the event in Step 5, so first we will add an event listener for a status event in the constructor function:


public function Sending() {
    stage.addEventListener(Event.ENTER_FRAME,mainLoop,false,0,true);
    localConnection.addEventListener(StatusEvent.STATUS, onStatus);
}

Now we need to create a blank function to respond to the event. The function is called 'onStatus'.

1
2	private function onStatus(e:StatusEvent):void {};

Step 10: Sending Summary

In Section 1, we have learnt how to use the LocalConnection class to send information, via a connection, to another flash file. Here is our finished AS file for Section 1:


package {
	
	import flash.display.MovieClip;
	import flash.events.Event;
	import flash.events.StatusEvent;
	import flash.events.MouseEvent;
	import flash.net.LocalConnection;
	
	public class Sending extends MovieClip {
		
		private var localConnection:LocalConnection = new LocalConnection();

		private var mX:Number;
		private var mY:Number;
				
		public function Sending() {
			stage.addEventListener(Event.ENTER_FRAME,mainLoop,false,0,true);
			localConnection.addEventListener(StatusEvent.STATUS, onStatus);
		}
		
		private function mainLoop(e:Event):void {
			mX = mouseX;
			mY = mouseY;
			
			localConnection.send("_mouseConnection","processData",mX,mY);
		}
		
		private function onStatus(e:StatusEvent):void {};
		
	}
	
}

Section 2: Receiving Information

Step 11: Receiving New Flash Document

Firstly, create a new ActionScript 3.0 file.

Then, resize the file to 600px × 250px.

Step 12: Receiving Add a Background

As before, this step is not necessary for functionality, but more for aesthetics. Add your image to the stage and then lock its layer.

Step 13: Receiving Create an Object

We now need to create an object to mirror the mouse pointer. It will be given the same X and Y values as the mouse pointer in the other file via ActionScript.

In this example I am using an icon of a pencil (courtesy of WeFunction). Import the icon to the stage, in its own layer, and then convert it to a MovieClip and give it an instance name of cursor_mc.

By default, the registration point (the cross, not the circle) is in the top left corner. This means that when we complete the project, the pencil will be slightly off from the location of the mouse. To fix, double click on the pencil, and realign it so that the end of the pencil is on the registration point.

Realign the image to match the registration point.

Step 14: Receiving Create Document Class

As in the first part, save your FLA as Receiving.fla and then create a blank AS file. Save this file in the same folder as your FLA and name it Receiving.as.

Then go back and link the document class to the FLA.

Step 15: Receiving Set Up Document Class

Add a blank package, class and constructor function to your AS file.


package {

	public class Receiving extends MovieClip {

		public function Receiving() {
		}

	}

}

Step 16: Receiving Import Classes

Just like before, import all the classes we will need.


package {
	
	import flash.display.MovieClip;
	import flash.events.Event;
	import flash.events.StatusEvent;
	import flash.net.LocalConnection;
	
	public class Receiving extends MovieClip {
		
		public function Receiving() {

		}
			
	}
	
}

Step 17: Receiving LocalConnection Usage

We are now ready to start writing the code to receive the information from the local connection. Here is what we need to do:

Declare an instance of the class.
Connect to the local connection.
Set the client for the local connection.
Create a method to receive data from the local connection.

Declaring an instance of the Local Connection class is the same as before:

1
2	private var localConnection:LocalConnection = new LocalConnection();

Next we need to connect to the connection which we created when we sent the data from the other file.

1
2	localConnection.connect("_connectionName");

Now we set the client. The client indicates the object on which the functions are called. It is normally set to this.

1
2	localConnection.client = this;

Finally, we need to create a blank function which will receive the data through its arguments.

1
2	public function methodName(variable1:type,variable2:type...):void {};

Step 18: Receiving Declaring the LocalConnection and Writing the Constructor Function

Now that we know how to receive information with a local connection, we can begin writing the script. First declare a new LocalConnection instance. Place this before the constructor function in the class.

1
2	private var localConnection:LocalConnection = new LocalConnection();

Then, in the constructor function, connect to the local connection and set its client:


public function Receiving() {
    localConnection.connect("_mouseConnection");
    localConnection.client = this;
}

(Notice that we are connecting to a local connection with the same ID as we used in the Sending file.)

Step 19: Receiving processData() Function

When information was sent from the sending file, a receiving function or method was named. In this project, I used the function processData(). The following function receives the X and Y coordinates as arguments and then uses them to set the pencil's position.


public function processData(mX:Number,mY:Number) {
    cursor_mc.x = mX;
    cursor_mc.y = mY;
}

This function needs to be a public function so that it can be accessed through the local connection.

Step 20: Receiving Status Event

As with Section 1, because we are using a local connection, we will need to handle status events. The event has already been imported in Step 16, so we now need to add an event listener for the events. Let's add a line to the constructor function:


public function Receiving() {
    localConnection.connect("_mouseConnection");
    localConnection.client = this;
    localConnection.addEventListener(StatusEvent.STATUS, onStatus);
}

Then we create a blank function to respond to the event listener:

1
2	private function onStatus(e:StatusEvent):void {};

Step 21: Receiving Summary

In this second part we have successfully received information from a local connection and processed it. Here is our finished AS file:


package {
	
	import flash.display.MovieClip;
	import flash.events.Event;
	import flash.events.StatusEvent;
	import flash.net.LocalConnection;
	
	public class Receiving extends MovieClip {
		
		private var localConnection:LocalConnection = new LocalConnection();

		public function Receiving() {
			localConnection.connect("_mouseConnection");
			localConnection.client = this;
			localConnection.addEventListener(StatusEvent.STATUS, onStatus);
		}
		
		public function processData(mX:Number,mY:Number) {
			cursor_mc.x = mX;
			cursor_mc.y = mY;
		}
		
		private function onStatus(e:StatusEvent):void {};
		
	}
	
}

Conclusion

In this tutorial we have learnt how to use the LocalConnection class. You have seen how to send information, receive information and also how to handle status events. This method is often used in web advertising when an advertiser wishes to synchronise an advert between two different ad positions on a single webpage. This same principle can easily be developed to include two-way communications between two files.

Thank you for reading this tutorial; I hope you enjoyed it!