Welcome to SignalsCircuit, if you're here you're probably curious about how PureMVC and as3-Signals come together in SignalsCircuit and why I chose to replace notifications from PureMVC with as3-signals.

Starting with the second part, the short answer to why I brought these two projects together under SignalsCircuit is because of the results that you can see in the benchmarks folder of the project and because of the speed and run time type checking that as3-signals provides. However, tests can be written and skewed to show different things, but I believe there are some design decisions in how PureMVC Notifications are implemented that cause it slow down when dispatching many notifications, making it not viable for complex games or applications that require a lot of notification dispatching, and as3-signals is a perfect fit because its small, lightweight, and fast.

In this home page I will try to outline how to quickly get started with SignalsCircuit, the code referenced is based off the "hashsignalscircuit" project in the examples folder of the Git repository. This quick step through assumes you have some working knowledge of both PureMVC and Robert Penner's as3-Signals. If not you should check out their sites, PureMVC (http://puremvc.org) and as3-signals(https://github.com/robertpenner/as3-signals). John Lindquist also recorded a great tutorial on as3-signals which I highly recommend, that is located here: http://johnlindquist.com/2010/01/21/as3-signals-tutorial/.

For info on SignalsCircuit 1.5 go here: https://github.com/s9tpepper/SignalsCircuit-for-PureMVC/wiki/SignalsCircuit-1.5---Multicore-Notes

Step 1: Facade Implementation

// In HashSignalsCircuitFacade.as

/**
 * Reference to the SignalsCircuit instance for the app
 * used to register Signal objects to ISignalCommand objects.
 */
private var _signalsCircuit:SignalsCircuit;

Add a member to your class to install SignalsCircuit. This object is what you use to register a Signal to an ISignalCommand class, which is like PureMVC's Command class with a slightly different signature. After you add the member move on to step 2.

Step 2: The Facade.initializeController() override

// In HashSignalsCircuitFacade.as

/**
 * Override initializeController().  Instead of starting up the
 * PureMVC Controller the SignalsCircuit is started up. Optionally,
 * you can use both, if you want/need them.
 */
override protected function initializeController():void
{
	_signalsCircuit = SignalsCircuit.getInstance();
	...
}

If you are using SignalsCircuit the idea is you aren't using notifications, so skip calling super.initializeController(); Instead, start up SignalsCircuit. Next we need some Signals to register.

Step 3: A Signals class

package org.signalscircuit.examples.hashsignalscircuit.signals
{
	import org.signalscircuit.examples.hashsignalscircuit.view.HashSignalsCircuitView;
	import org.osflash.signals.natives.NativeSignal;
	import org.osflash.signals.Signal;
	/**
	 * @author Omar Gonzalez
	 */
	public class HashSignalsCircuitSignals
	{
		/**
		 * Signal dispatched when the main game class is added
		 * to the stage.
		 */
		static public var APP_ADDED_TO_STAGE:NativeSignal;
		/**
		 * Signal dispatched to start the application.
		 */
		static public const START_APPLICATION:Signal = new Signal(HashSignalsCircuitView);
	}
}

This small class has some Signal objects defined to get the application started up. The first signal is used to listen for the Event.ADDED_TO_STAGED event from the main class of the application. Lets look at what happens when that signal is dispatched.

Step 4: Starting PureMVC with Signals The TwitterExample.mxml file's main tag is using the HashSignalsCircuitView class. In the constructor the NativeSignal is started and an event listener is attached. In the event listener for addedToStage the Facade implementation is used to call HashSignalsCircuitFacade.getInstance().startUp().

// In HashSignalsCircuitView.as
		public function HashSignalsCircuitView()
		{
			super();

			usePreloader = false;

			HashSignalsCircuitSignals.APP_ADDED_TO_STAGE = 
                                      new NativeSignal(this, FlexEvent.APPLICATION_COMPLETE, FlexEvent);
			HashSignalsCircuitSignals.APP_ADDED_TO_STAGE.addOnce(_startApplication);
		}
		
		/**
		 * Handles the Event.ADDED_TO_STAGE of the main
		 * game class and starts up the game core.
		 * 
		 * @param event Event dispatched by Gigapede when its added to stage.
		 */
		private function _startApplication(event:FlexEvent):void
		{
			HashSignalsCircuitFacade.getInstance().startUp(this);
		}

Instead of directly dispatching the signal we are using a startUp() method on the Facade, this ensures PureMVC starts up and is ready.

// In HashSignalsCircuitFacade.as

/**
 * Starts up the application using the Signal for start up.
 */
public function startUp(hashSignalsCircuit:HashSignalsCircuitView):void
{
	HashSignalsCircuitSignals.START_APPLICATION.dispatch(hashSignalsCircuit);
}

The startUp() method in the Facade implementation dispatches the signal for starting the application and sends a reference to the HashSignalsCircuitView, as the Signal required based on its intantiation in the code example in step 3. The START_APPLICATION signal must now be registered to a ISignalCommand object to do usual PureMVC things at start up like load mediators and proxies.

Step 5: Register start up Signal to a command

// In HashSignalsCircuitFacade.as

/**
 * Override initializeController().  Instead of starting up the
 * PureMVC Controller the SignalsCircuit is started up. Optionally,
 * you can use both, if you want/need them.
 */
override protected function initializeController():void
{
	_signalsCircuit = SignalsCircuit.getInstance();
	_signalsCircuit.registerSignal(HashSignalsCircuitSignals.START_APPLICATION, StartApplicationCommand);
	...
}

Back in the override from step 2, using the registerSignal() method of the SignalsCircuit instance commands can be registered that execute whenever the Signal is dispatched. In the command you have access to the facade, like in regular PureMVC commands, and you receive the Signal that was dispatched and the arguments sent in the dispatch. Lets take a look at the StartApplicationCommand.

package org.signalscircuit.examples.hashsignalscircuit.controller.commands.startup
{
	import org.osflash.signals.Signal;
	import org.signalscircuit.examples.hashsignalscircuit.model.proxies.TwitterProxy;
	import org.signalscircuit.examples.hashsignalscircuit.view.HashSignalsCircuitView;
	import org.signalscircuit.examples.hashsignalscircuit.view.HashSignalsCircuitMediator;
	import org.signalscircuit.puremvc.as3.patterns.command.SimpleSignalCommand;

	/**
	 * @author Omar Gonzalez
	 */
	public class StartApplicationCommand extends SimpleSignalCommand
	{
		/**
		 * @inheritDoc
		 */
		override public function execute(signal:Signal, args:Array):void
		{
			// Get Signal argument
			var hashSignalsCircuit:HashSignalsCircuitView = args[0];
			
			// Start view mediators
			facade.registerMediator(new HashSignalsCircuitMediator(hashSignalsCircuit));
			
			// Start data proxies
			var twitterProxy:TwitterProxy = new TwitterProxy();
			facade.registerProxy(twitterProxy);
			
			// Load tweets for #SignalsCircuit
			twitterProxy.loadHashTag("SignalsCircuit");
		}
	}
}

This command looks pretty much identical to a regular PureMVC command, with the change in the signature of the execute() method. The signal argument is a reference to the Signal that triggered the command, and the args Array object will have in it the arguments that are passed into the Signal when the Signal was instantiated. In the example above the HashSignalsCircuitSignals.START_APPLICATION Signal has one argument type passed in making the Signal require a HashSignalsCircuitView, and above is how to get the reference to that object when the signal is dispatched like it is in step 4 from the startUp() command in the HashSignalsCircuitFacade.

If you find any issues or bugs, or have any feature request please post them in the Issues section by creating a new issue. Thank you in advanced, I appreciate any feedback good or bad. If you have any questions email me at omar at laflash.org.