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

Adobe Animate CC

Flash Builder (Download trial)

Flash Player 10.2

Adobe AIR

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 updateAfterEvent method 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.