In this Quick Tip I will show you how to set the operating system's Native Cursor through AS3, using the new feature in Flash Player 10.2.

Brief Overview

In the SWF you'll see a Start button.When you click on this button, your mouse becomes a crosshair ready to do some damage. As you click around on the stage, a gunshot sounds and a bullet hole graphic gets added to the stage at the point where you clicked with the mouse.

Compare it to the "old school" method which we discussed yesterday:

Step 1: Downloading and Setting up the Flex SDK

Before you can code the Native Cursor you need to make sure you have the correct Flex SDK. For this tutorial we will be using the cutting edge "Hero" SDK. I downloaded the one with a build date of Thu Feb 3, 2011(4.5.0.19786). Once you download it you will need to extract it; I extracted my copy to my C: drive.

Open Flash Builder and go to Menu > Window > Preferences. Choose "Flash Builder/Installed Flex SDKS" then click on the "Add" button.

Browse to the location where you extracted the SDK.Press the "OK" Button when you are finished.

You will be taken back to the installed SDK's screen.Check the box next to the newly installed SDK and press "Apply".We are now ready to use the new SDK.

Step 2: Setting Up the Flex Project

In Flash Builder, go to Menu > New > Flex Project. Set the following attributes

• "Project Name": NativeCursor
• "Application Type": Web (runs in Adobe Flash Player)
• "Flex SDK Version": Use Default SDK (currently "Flex 4.5")

In the "Package Explorer" right click on the project folder and go to New > Folder.

Name this folder "assets".

In the project download there is a source folder. In this folder are two .pngs and one .mp3 file; copy these files and paste them into the newly created "assets" folder.

Step 3: Setting Up the Button and Sprite Container

In the NativeCursor.mxml within the s:Application attribute change the minWidth to "500" and the minHeight to "400". Add a width and height attribute and set them to "500" and "400" respectively. Lastly add a creationComplete="Setup()" attribute.The creationComplete attribute sets a function to be called when the application first loads.

<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
        xmlns:s="library://ns.adobe.com/flex/spark" 
        xmlns:mx="library://ns.adobe.com/flex/mx"  minWidth="500" minHeight="400" 
        width="500" height="400" creationComplete="Setup()">

You can delete the fx:Declarations block; we don't need it here.

Add the following code to the .mxml. The s:SpriteVisualElement is used as a container for a sprite in which we will place the button and bullet hole graphics:

<s:Button x="199" y="199" label="Start" id="startGame"/>
<s:SpriteVisualElement id="container" />

Step 4: Import the classes and Set Up Variables

Above the Button and SpriteVisualElement, add an fx:Script tag.

Within this tag, inside the ![CDATA[ section, add the following code:

import flash.ui.Mouse;
import flash.ui.MouseCursor;
import flash.ui.MouseCursorData;
import mx.core.BitmapAsset;

			
//The crosshair graphic
[Embed(source="assets/crosshair.png")]
[Bindable]
var CrossHair:Class;
//The Bullet Hole graphic
[Embed(source="assets/BulletHole.png")]
[Bindable]
var BulletHole:Class;
//Gunshot 
[Embed(source="assets/GunShot.mp3")]
[Bindable]
var GunShot:Class;
			
//Container to hold button and bullet Holes
var sprite:Sprite;
//Used to test if this is the first time user shoots
var firstShot:Boolean = true;
//Creates a new gunshot sound
var gunshot:Sound = new GunShot();

//Needed for the gunshot sound
var soundChannel:SoundChannel = new SoundChannel;

Here we just imported the classes we need, and set up some variables.

Step 5: Coding the SetUp() function

The SetUp() function is called when the application first loads, much like a constructor function. Here we add our Sprite to the container, add the button to that Sprite and add an EventListener to the button.

sprite = new Sprite();
container.addChild(sprite);
container.addChild(startGame);
startGame.addEventListener(MouseEvent.CLICK,startTheGame);

Step 5: Coding the startGame() function

The startGame() function is called when the user clicks on the "Start" button.

Add the following code

private function startTheGame(e:MouseEvent):void{
    //Remove the button from the stage
    container.removeChild(startGame);
    //MouseCursorData allows us to set the appearance of the Mouse Cursor
    var cursorData:MouseCursorData = new MouseCursorData(); 
    //Vector to hold the bitmapData of our image (the CrossHair)
    var crossHairData:Vector.<BitmapData> = new Vector.<BitmapData>();
    //Create a new CrossHair
    var crossHair:Bitmap = new CrossHair();
    //Set the vector to the bitmapData of the crossHair
    crossHairData[0] = crossHair.bitmapData;
    // Specify the hotspot 
    cursorData.hotSpot = new Point(0,0)
    //set the cursorData to the vector which holds the crossHairs bitmapData
    cursorData.data = crossHairData;
    
    Mouse.registerCursor("crossHairCursor", cursorData)
    Mouse.cursor = "crossHairCursor";
    stage.addEventListener(MouseEvent.CLICK,fireShot);
    
}

The first thing we do is remove the button from the stage.

Next we create a new MouseCursorData() object. The MouseCursorData class lets you define the appearance of a "native" mouse cursor -- i.e., one that replaces your operating system's cursor. Then we code a Vector to hold the BitmapData of our "crossHair" PNG image, which we embedded earlier.

Next we set the hotspot for our cursorData. Think of the hotspot as a "registration" point; it defines where the "tip" of the cursor is. We also set the cursorData.data property to our crossHairData Vector, which holds the BitmapData of the "crossHair" image.

Lastly we register the cursor with the cursorData object we created, and set the Mouse.cursor property. We also add a MouseEvent.CLICK event listener to the stage.

Step 6: Coding the fireShot() function

The fireShot()function is called whenever the user clicks on the stage.

Add the following code below the startGame() function:

private function fireShot(e:MouseEvent):void{
    //If they have clicked once then we do this
    if(firstShot == false){
            //create new BulletHole image
            var bulletHole:Bitmap = new BulletHole();
            //Add Bullet hole
            container.addChild(bulletHole);
            bulletHole.x = e.stageX-16;
            bulletHole.y = e.stageY-16;
            //Play the sound
            soundChannel = gunshot.play();
    }
    firstShot = false;
    
}

We first check to see if this is the first time the user has clicked; if it is not the first time then we play the gunshot sound and add the bulletHole to the position on stage where the user clicked by using e.stageX ande.stageY. We actually subtract 16 from the stage.X and stage.Y so the image will be centered with the crosshair (the image is 32x32px). The event holds information about itself,you can see what it contains by using trace(e.toString())

If we did not check if this was the first time, then when the user first clicked on the Start button it would add a crosshair and play the gunshot sound -- and we don't want that.

Conclusion

One thing you should note about using Native Cursors is that the image cannot be bigger than 32 x 32px.

You can also use have an animated cursor with the Native Cursor by adding multiple Bitmaps (one per frame of animation) to the crossHairData Vector (let us know if you'd like a full Quick Tip explaining this).

Native Mouse Cursors are a welcome addition to the Flash Player (if not long overdue!)

Thanks for reading and I hope you found this tutorial useful.