AS3 Quickie – Native Mouse Cursors

We’re looking all the way back to Flash Player 10.2 for a peek at native mouse cursor support! This feature allows us to use bitmap based mouse cursors that run at the OS level rather than inside the display list in Flash Player. Huge performance gains!


Requires Flash Player 10.2 or above!

It is fairly simple to use a bitmap as a native cursor in Flash Player. We can do so through the [Embed] mechanism:

[Embed (source="AngryFace.png" )]
public static const AngryFace:Class;

Or by utilizing a bitmap image imported through the Flash Professional Library:

Perform the necessary imports:

import flash.ui.Mouse;
import flash.ui.MouseCursorData;
import flash.geom.Point;
import flash.display.BitmapData;

Verify that the system supports this feature:

if(Mouse.supportsNativeCursor){}

Set up all of our objects... note that AngryCursor is a bitmap object within our library:

public var angryCursor:AngryCursor;
private var cursorBitmapData:BitmapData;
private var cursorData:MouseCursorData;
private var cursorVector:Vector.<BitmapData>;

The first step is to create a new instance of AngryCursor and then draw the BitmapData from it for later:

angryCursor = new AngryCursor();
cursorBitmapData = new BitmapData(32, 32, true, 0x000000);
cursorBitmapData.draw(angryCursor);

The MouseCursorData requires a Vector of BitmapData objects [not to exceed 32x32 per OS restrictions]. Assign the newly created BitmapData to index 0 of our Vector:

cursorVector = new Vector.<BitmapData>();
cursorVector[0] = cursorBitmapData;

Now, we create a new MouseCursorData object. Set an offset, if desired, through the MouseCursorData.hotSpot property... and then assign the Vector we've created to the MouseCursorData.data property:

cursorData = new MouseCursorData();
cursorData.hotSpot = new Point(10, 10);
cursorData.data = cursorVector;

As the final step in this process, we assign the MouseCursorData to the Mouse object through Mouse.registerCursor and set Mouse.cursor to that names assignment.

Mouse.registerCursor("angryCursor", cursorData);
Mouse.cursor = "angryCursor";

That should do it! We will now have a native accelerated mouse cursor with our Flash application. The full code is below:

package  {
	import flash.display.Sprite;
	import flash.ui.Mouse;
	import flash.ui.MouseCursorData;
	import flash.geom.Point;
	import flash.display.BitmapData;
	
	public class NativeCursor extends Sprite {
		
		public var angryCursor:AngryCursor;
		private var cursorBitmapData:BitmapData;
		private var cursorData:MouseCursorData;
		private var cursorVector:Vector.<BitmapData>;
		
		public function NativeCursor() {
			if(Mouse.supportsNativeCursor){
				setupMouseCursor();
			}
		}
		
		private function setupMouseCursor():void {
			angryCursor = new AngryCursor();
			cursorBitmapData = new BitmapData(32, 32, true, 0x000000);
			cursorBitmapData.draw(angryCursor);
			
			cursorVector = new Vector.<BitmapData>();
			cursorVector[0] = cursorBitmapData;
			
			cursorData = new MouseCursorData();
			cursorData.hotSpot = new Point(10, 10);
			cursorData.data = cursorVector;
			
			Mouse.registerCursor("angryCursor", cursorData);
			Mouse.cursor = "angryCursor";
		}
		
		
	}
	
}

NOTE: If using multiple bitmap images, we can have animated cursors and control the playback frame rate via MouseCursorData.frameRate.

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

AS3 Quickie – “What’s New” Catch-up

For most of my “AS3 Quickie” series, I’ve focused on Flash Player 11.2-11.4, but really have plans to cover all sorts of interesting bits in the recent runtimes – even some additions with Flash Player 10.

For those who would like a comprehensive guide to everything new in Flash Player 11 and AIR 3, O’Reilly has published a set of books: “What’s New in Flash Player 11” and “What’s New in Adobe AIR 3“. These books are companion pieces as there is obvious overlap between what is new in each runtime, but are unique enough to require this manner of separation per volume. The books are currently available in digital format (ePub, Mobi, PDF) plus Amazon.com (Kindle), Barnes and Nobel, Safari Books Online, and other online retailers… and can actually be acquired for FREE*!

Details of both books are below, along with links to the publisher’s website which includes download of all source code and project assets. I do hope that many people do get access to these and build great stuff using Flash Player 11 and AIR 3 – so please spread the word!!!


What’s New in Flash Player 11

Quickstart Guide for Browser-Based Experiences

What’s New in Flash Player 11

Author: Joseph Labrecque

Publisher: O’Reilly Media (December, 2011)

ISBN-10: 1-4493-1109-1

ISBN-13: 978-1-4493-1109-4

Pages: 78

This book will detail the various enhancements, new functionalities, and general improvements available in this new version of Adobe Flash Player. Each item is explained in detail and when possible, a series of screen captures and a full code examples will be provided, enabling you to both grasp the new feature in a visual way, and integrate the feature into your own code quickly, based upon example.


What’s New in Adobe AIR 3

Quickstart Guide for Desktop and Mobile Development

What’s New in Adobe AIR 3

Author: Joseph Labrecque

Publisher: O’Reilly Media (December, 2011)

ISBN-10: 1-4493-1107-5

ISBN-13: 978-1-4493-1107-0

Pages: 104

This book will detail the various enhancements, new functionalities, and general improvements available in this new version of Adobe AIR. Each item is explained in detail and when possible, a series of screen captures and a full code examples will be provided, enabling you to both grasp the new feature in a visual way, and integrate the feature into your own code quickly, based upon example.


*I’d like to note that this price has absolutely nothing to do with the November 2011 announcements from Adobe. Offering the books for no cost to readers was a mutually beneficial decision made between myself and the publisher months before.

AS3 Quickie – Mouse Lock and Relative Mouse Coordinates

Another great feature in Flash Player 11.2 is the combination of the mouseLock boolean in flash.display.Stage along with the ability to read movementX and movementY from MouseEvent.MOUSE_MOVE. When used within Flash Player, we must be in fullscreen for mouse lock to be enabled and the relative mouse coordinates made available.

The primary focus of this feature is to provide a better experience in gaming – particularly in 3D games within which the player is able to move and look around the entire environment. This can also be useful in full screen simulations and experimental pieces.


Requires Flash Player 11.2 or above!

To get this all working, we will first import the necessary classes to use fullscreen and work with aspects of the mouse:

import flash.display.Stage;
import flash.display.StageDisplayState;
import flash.events.MouseEvent;
import flash.events.FullScreenEvent;

In order to toggle the mouse lock boolean to true, we must first enter fullscreen (or fullscreen interactive):

stage.displayState = StageDisplayState.FULL_SCREEN;

The mouse lock boolean is available as a member of the stage. Once in fullscreen, we can set this to true:

stage.mouseLock = true;

Mouse lock will now be enabled. To additionally monitor for relative mouse coordinates, we employ a MouseEvent listener:

stage.addEventListener(MouseEvent.MOUSE_MOVE, onMouseActivity);

From within the method invoked through mouse movement, we then read out the coordinate data:

private function onMouseActivity(e:MouseEvent):void {
	statusField.text = "X: " + e.movementX + " Y: " + e.movementY + " \n" + statusField.text;
}

The important things to know about using mouse lock are that; it must be used in full screen only, it will automatically be turned off when exiting fullscreen, and the mouse cursor will be hidden by default when activated.

Here is the full source code:

package  {
	
	import flash.display.Sprite;
	import flash.display.MovieClip;
	import flash.display.Stage;
	import flash.display.StageDisplayState;
	import flash.text.TextField;
	import flash.events.MouseEvent;
	import flash.events.Event;
	import flash.events.FullScreenEvent;
	
	public class MouseCoordinates extends Sprite {
		
		public var statusField:TextField;
		public var fsButton:MovieClip;
		
		public function MouseCoordinates() {
			fsButton.addEventListener(MouseEvent.CLICK, toggleFullscreen);
			stage.addEventListener(FullScreenEvent.FULL_SCREEN, onFullscreen);
		}
		
		private function toggleFullscreen(e:MouseEvent):void {
			if(stage.displayState == StageDisplayState.FULL_SCREEN){
				stage.displayState = StageDisplayState.NORMAL;
			}else{
				stage.displayState = StageDisplayState.FULL_SCREEN;
			}
			statusField.text = stage.displayState + " \n" + statusField.text;
		}
		
		private function onFullscreen(e:FullScreenEvent):void {
			if(e.fullScreen){
				stage.mouseLock = true;
				stage.addEventListener(MouseEvent.MOUSE_MOVE, onMouseActivity);
			}else{
				stage.removeEventListener(MouseEvent.MOUSE_MOVE, onMouseActivity);
			}
		}
		
		private function onMouseActivity(e:MouseEvent):void {
			statusField.text = "X: " + e.movementX + " Y: " + e.movementY + " \n" + statusField.text;
		}
	}
	
}

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

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).


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.

AS3 Quickie – Removing the right-click menu from Flash content

One of the great new features introduced with Flash Player 11.2 is the ability to intercept the right-click from a user’s mouse. A simple MouseEvent listener can be added to the Stage or any object which extends flash.display.InteractiveObject. Not only does this have the effect of completely removing the right-click menu from Flash content, but we can also alternatively react to the right-click in any way we choose.


Requires Flash Player 11.2 or above!

To enable this, we must import the MouseEvent class into our project:

import flash.events.MouseEvent;

Next, let's add a listener to the Stage itself, disabling the context menu in the process:

stage.addEventListener(MouseEvent.RIGHT_CLICK, doNothing);

In the included example, we also register a listener upon our MovieClip symbol. A right-click upon this will fire off an additional method which controls the animation:

angryFace.addEventListener(MouseEvent.RIGHT_CLICK, destroyFace);

That's it! A pretty simple solution for a problem that Flash developers have had pretty much since Flash was Flash :)

Here is the full source code:

package  {
	import flash.display.Sprite;
	import flash.display.MovieClip;
	import flash.events.MouseEvent;
	import flash.display.MovieClip;
	
	public class KillContextMenu extends Sprite {
		
		public var angryFace:MovieClip;
		
		public function KillContextMenu() {
			stage.addEventListener(MouseEvent.RIGHT_CLICK, doNothing);
			angryFace.addEventListener(MouseEvent.RIGHT_CLICK, destroyFace);
		}
		
		private function doNothing(e:MouseEvent):void {
			//do nothing...
			trace(e.type);
		}
		
		private function destroyFace(e:MouseEvent):void {
			//send to oblivion
			e.currentTarget.gotoAndPlay("Destruction");
		}
		
	}
}

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