Working with native mouse cursors in Flash Player 10.2
Created
8 February 2011
Requirements
Prerequisite knowledge
Prior experience working in the Flash Professional authoring environment is required. Basic familiarity with writing ActionScript 3 code is also recommended.
User level
Intermediate
Required products
- Flash Professional (Download trial)
- Flash Player 10.2
The release of Adobe Flash Player 10.2 introduces a compelling new feature called native mouse cursors. You can now use bitmap-based mouse cursors that run at the OS level rather than inside the display list in Adobe Flash Player. In this article, you'll learn how to leverage this new capability using minimal coding.
Understanding native bitmap cursors
Since the introduction of Flash Player 5, developers have been able to use methods such as InteractiveObject.startDrag and Mouse.hide to customize the appearance of cursors in games and applications. However, the previous implementation had the following limitations:
- Display object implementations of cursors are limited to the dimensions of the Stage. The custom cursor isn't fully visible when the user places their cursor near the borders of the Stage.
- Display object cursors are very resource-intensive when rendered in Flash Player because the entire Stage must be re-rendered at a very high frame rate. The use of the
updateAfterEventmethod can lead to high CPU usage. - If the SWF file becomes frozen for a few milliseconds for any reason, the animation of the cursor is also blocked—which users may interpret as an unresponsive application.
- In general, the responsiveness of display object cursors are sluggish. In comparison, native mouse cursors look and perform better when the user interacts with an application.
Fortunately, leveraging the new native mouse cursor feature does not require writing a lot of code. You'll need to use slightly more ActionScript to implement simple Mouse.hide and startDrag functionality. The code is fairly straightforward and the visual effects are worth the effort required to customize the cursor or animate it.
Implementing native mouse cursors
When implementing native mouse cursors, you'll use several properties that are very concise and efficient. The primary functionality is performed by the MouseCursorData object that is located in the flash.ui package.
The following three properties control the MouseCursorData object:
- MouseCursorData.data: A vector of BitmapData objects used to display the cursors.
- MouseCursorData.hotSpot: The value of the registration point of the cursor, stored as a Point object.
- MouseCursorData.frameRate: The frame rate used to animate a sequence of bitmap images. This property allows you to create animated cursors.
After you've created a MouseCursorData object, use the Mouse.registerCursor method to assign it to the Mouse object. Once the Mouse object has been registered, you can pass the alias to the Mouse.cursor property.
Note: By passing a vector of BitmapData objects, you can specify a series of bitmap cursors in order to create a native animated cursor.
Examine the following code example:
// Create a MouseCursorData object
var cursorData:MouseCursorData = new MouseCursorData();
// Specify the hotspot
cursorData.hotSpot = new Point(15,15);
// Pass the cursor bitmap to a BitmapData Vector
var bitmapDatas:Vector.<BitmapData> = new Vector.<BitmapData>(1, true);
// Create the bitmap cursor
// The bitmap must be 32x32 pixels or smaller, due to an OS limitation
var bitmap:Bitmap = new zoomCursor();
// Pass the value to the bitmapDatas vector
bitmapDatas[0] = bitmap.bitmapData;
// Assign the bitmap to the MouseCursor object
cursorData.data = bitmapDatas;
// Register the MouseCursorData to the Mouse object with an alias
Mouse.registerCursor("myCursor", cursorData);
// When needed for display, pass the alias to the existing cursor property
Mouse.cursor = "myCursor";
It is important to remember that the bitmap files used for the cursors should not exceed 32 × 32 pixels, due to an OS limitation. Attempts to pass a larger bitmap will fail silently.
At any time, you can stop using the current bitmap cursor and switch back to display the default OS cursor. To achieve this, use one of the constant values of the MouseCursor class, as shown below:
Mouse.cursor = MouseCursor.AUTO;
The previous example created a simple static bitmap cursor; the next example creates an animated cursor. The process is easy—simply supply multiple bitmap images and then specify the frame rate of the cursor animation, as follows:
// Create a MouseCursorData object
var cursorData:MouseCursorData = new MouseCursorData();
// Specify the hotspot
cursorData.hotSpot = new Point(15,15);
// Pass the cursor's bitmap to a BitmapData Vector
var bitmapDatas:Vector.<BitmapData> = new Vector.<BitmapData>(3, true);
// Create the bitmap cursor frames
// Bitmaps must be 32 x 32 pixels or less, due to an OS limitation
var frame1Bitmap:Bitmap = new frame1();
var frame2Bitmap:Bitmap = new frame2();
var frame3Bitmap:Bitmap = new frame3();
// Pass the values of the bitmap files to the bitmapDatas vector
bitmapDatas[0] = frame1Bitmap.bitmapData;
bitmapDatas[1] = frame2Bitmap.bitmapData;
bitmapDatas[2] = frame3Bitmap.bitmapData;
// Assign the bitmap data to the MouseCursor object
cursorData.data = bitmapDatas;
// Pass the frame rate of the animated cursor (1fps)
cursorData.frameRate = 1;
// Register the MouseCursorData to the Mouse object
Mouse.registerCursor("myAnimatedCursor", cursorData);
// When needed for display, pass the alias to the existing cursor property
Mouse.cursor = "myAnimatedCursor";
By setting the MouseCursorData.frameRate property and passing a series of BitmapData objects, Flash Player automatically creates an animated cursor that plays at the specified frame rate. This happens automatically, so you do not need any additional code to animate the cursor.
Native cursor demo
The following demo shows examples of a native static cursor and native animated cursor. The bottom button resets to the default OS cursor.
Note: You must have Flash Player 10.2 installed to view this behavior.
Where to go from here
Whether you develop games or RIAs, the native mouse cursor feature makes it easier to customize cursors than ever before. Additionally, the new implementation enhances the appearance and responsiveness of an application while reducing the CPU load required to move and redraw the cursor on the Stage.
Check out Mihai Corlan's article, Working with native custom cursors in Flash, on the Adobe Flash Platform blog to research further.
Acknowledgments
The native cursor example uses icons from the Silk Icons 1.3 set by Mark James.
This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License
More Like This
- Vertex and Fragment Shaders
- Introducing the Starling 2D framework
- What is AGAL
- Working with the Proscenium framework
- Excerpt: Adobe Flash 11 Stage3D (Molehill) Game Programming Beginner’s Guide
- Hello Triangle
- Working with 3D cameras
- Creating 3D games and apps with Away3D 4 and Stage 3D – Part 1: Setting up a 3D project in 30 minutes
- Working with Stage3D and perspective projection
- Getting started with stage video
