AS3 Quickie – Monitor Throttle Events

One of the great new features introduced with Flash Player 11.2 is the ability to detect when the runtime throttles, pauses, or resumes normal activity through the flash.events.ThrottleEvent class. This is useful for saving state, or pulling back our activity when a throttle is detected. What does the throttle actually do? Well, if you have multiple tabs open in a web browser, and navigate from a tab with Flash content to another tab – the Flash content will enter a throttled state in which the frames per second is drastically slowed down so as not to take any unnecessary resources. Similarly, when we navigate back to the Flash content tab, the content receives focus and normal FPS is resumed.

There are three types of throttle events we can receive notification of; throttle, pause, and resume. These are returned as ThrottleEvent.state and can be verified against flash.events.ThrottleType. In the example below, we are printing out the state and new frame rate for each ThrottleEvent (with the addition of flash.utils.getTimer ticks to measure against).

[kml_flashembed publishmethod=”static” fversion=”11.2.0″ movie=”/wp-content/uploads/2012/06/Throttle.swf” width=”550″ height=”400″ targetclass=”flashmovie” play=”true” loop=”true” menu=”false” quality=”high” wmode=”direct” allowfullscreen=”true” allowscriptaccess=”always” allownetworking=”all”]
Requires Flash Player 11.2 or above!

To enable this, we must import the ThrottleEvent and ThrottleType classes into our project:

import flash.events.ThrottleEvent;
import flash.events.ThrottleType;

Then, we add an event listener to the Stage or some other display object:

stage.addEventListener(ThrottleEvent.THROTTLE, onThrottle);

Finally, configure a method to deal with the ThrottleEvent:

private function onThrottle(e:ThrottleEvent):void {
	trace(e.state); //this is the ThrottleType 
	trace(e.targetFrameRate) //this is the new FPS
}

That’s just about it! If you want to read up on the specifics on which runtimes support this event and other particulars, you can do so over at the ActionScript® 3.0 Reference for the Adobe® Flash® Platform.

Here is the full source code:

package  {
	
	import flash.display.MovieClip;
	import flash.events.ThrottleEvent;
	import flash.events.ThrottleType;
	import flash.text.TextField;
	import flash.events.Event;
	import flash.utils.getTimer;
	
	public class ThrottleMonitor extends MovieClip {
		
		public var statusField:TextField;
		
		public function ThrottleMonitor() {
			this.addEventListener(Event.ADDED_TO_STAGE, init);
		}
		
		private function init(e:Event):void {
			stage.addEventListener(ThrottleEvent.THROTTLE, onThrottle);
			statusField.text = getTimer() + " - START!\n" + statusField.text;
		}
		
		private function onThrottle(e:ThrottleEvent):void {
			statusField.text = getTimer() + " - " + e.state + ": " + e.targetFrameRate + "FPS\n" + statusField.text;
		}
	}
	
}

Want the full package? Download below:
Packaged code and Flash Professional CS6 project

---

Incidentally, I plan on doing a whole series of these for new capabilities of Flash Player 11.2, 11.3, and 11.4. They can be found all in one place by accessing the “ACTIONSCRIPT QUICKIES!” link at the top of this blog. I may also do some quick recordings around these items as well – in which case any older posts will be edited to include them.