Creating and removing a cursor

To use the Cursor Manager, you import the mx.managers.CursorManager class into your application, and then reference its static properties and methods.

The Cursor Manager controls a prioritized list of cursors, where the cursor with the highest priority is currently visible. If the cursor list contains more than one cursor with the same priority, the Cursor Manager displays the most recently created cursor.

You create a new cursor, and set an optional priority for the cursor, by using the static setCursor() method of the CursorManager class. This method adds the new cursor to the cursor list. If the new cursor has the highest priority, it is displayed immediately. If the priority is lower than a cursor already in the list, it is not displayed until the cursor with the higher priority is removed.

To remove a cursor from the list, you use the static removeCursor() method. If the cursor is the currently displayed cursor, the Cursor Manager displays the next cursor in the list, if one exists. If the list ever becomes empty, the Cursor Manager displays the default system cursor.

The setCursor() method has the following signature:

public static setCursor(cursorClass:Class, priority:int = 2, xOffset:Number = 0,
    yOffset:Number = 0, setter:IUIComponent = null):int

The following table describes the arguments for the setCursor() method:

Argument	Description	Req/Opt
`cursorClass`	The class name of the cursor to display.	Required
`priority`	The priority level of the cursor. Valid values are `CursorManagerPriority.HIGH`, `CursorManagerPriority.MEDIUM`, and `CursorManagerPriority.LOW`. The default value is 2, corresponding to `CursorManagerPriority.MEDIUM`.	Optional
`xOffset`	The x offset of the cursor relative to the mouse pointer. The default value is 0.	Optional
`yOffset`	The y offset of the cursor relative to the mouse pointer. The default value is 0.	Optional
`setter`	The IUIComponent that set the cursor. Necessary (in multi-window environments) to know which window needs to display the cursor.	Optional

This method returns the ID of the new cursor. You pass the ID to the removeCursor() method to delete the cursor. This method has the following signature:

static removeCursor(cursorID:int):void

Note: In AIR, each mx.core.Window instance uses its own instance of the CursorManager class. In an AIR application, instead of directly referencing the static methods and properties of the CursorManager class, use the Window.cursorManager property to reference the CursorManager instance for the Window instance.

The following example changes the cursor to a custom wait or busy cursor while a large image file loads. After the load completes, the application removes the busy cursor and returns the cursor to the system cursor.

Note: The Flex framework includes a default busy cursor. For information on using this cursor, see Using a busy cursor.

<?xml version="1.0"?>
<!-- cursors\CursorManagerApp.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Script> 
        <![CDATA[
            import mx.managers.CursorManager;
            import flash.events.*;
            
            // Define a variable to hold the cursor ID.
            private var cursorID:Number = 0;
    
            // Embed the cursor symbol.
            [Embed(source="assets/wait.jpg")]
            private var waitCursorSymbol:Class;
                    
            // Define event listener to display the wait cursor
            // and to load the image.
            private function initImage(event:MouseEvent):void {
                // Set busy cursor.
                cursorID = CursorManager.setCursor(waitCursorSymbol);
                // Load large image.
                image1.load("../assets/DSC00034.JPG");
            }

            // Define an event listener to remove the wait cursor.
            private function loadComplete(event:Event):void {
                CursorManager.removeCursor(cursorID);   
            }               
        ]]>
    </mx:Script>

    <mx:VBox>
        <!-- Image control to load the image. -->
        <mx:Image id="image1" 
            height="50"
            width="100"
            scaleContent="true"
            complete="loadComplete(event);"/>

        <!-- Button triggers the load. --> 
        <mx:Button id="myButton" label="Show" click="initImage(event);"/>
    </mx:VBox>
</mx:Application>
The executing SWF file for the previous example is shown below:

This example uses a JPEG image as the cursor image. You can also use a Sprite, or a PNG, GIF, SVG, or SWF file, as the following example shows:

[Embed(source="assets/wait.swf")] 
var waitCursorSymbol:Class;

Or you can reference a symbol from a SWF file, as the following example shows:

[Embed(source="assets/cursorList.swf", symbol="wait")] 
var waitCursorSymbol:Class;

An advantage of using a SWF file is that you can create an animated cursor.

Adobe Flex 3 Help

Creating and removing a cursor