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.

[kml_flashembed publishmethod=”static” fversion=”11.2.0″ movie=”/wp-content/uploads/2012/06/MouseLock.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 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