Cursor Manager

The Cursor Manager in Flex lets you control the cursor image in your Flex application. You can use the Cursor Manager to provide visual feedback to users to indicate when to wait for processing to complete, to indicate allowable actions, or to provide other types of feedback. The cursor image can be a JPEG, GIF, PNG, or SVG image, a Sprite object, or a SWF file.

About the Cursor Manager

By default, Flex uses the system cursor as the application cursor. You control the system cursor by using the settings of your operating system.

The Flex Cursor Manager lets you control the cursor image in your Flex application. For example, if your application performs processing that requires the user to wait until the processing completes, you can change the cursor so that it reflects the waiting period. In this case, you can change the cursor to an hourglass or other image.

You also can change the cursor to provide feedback to the user to indicate the actions that the user can perform. For example, you can use one cursor image to indicate that user input is enabled, and another to indicate that input is disabled.

You can use a JPEG, GIF, PNG, or SVG image, a Sprite object, or a SWF file as the cursor image.

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):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

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 instance of the Window class 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 --> 
<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"> 
 
    <fx: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);   
            }               
        ]]> 
    </fx:Script> 
 
    <s:VGroup> 
        <!-- Image control to load the image. --> 
        <mx:Image id="image1" 
            height="50" 
            width="100" 
            scaleContent="true" 
            complete="loadComplete(event);"/> 
 
        <!-- Button triggers the load. --> 
        <s:Button id="myButton" label="Show" click="initImage(event);"/> 
    </s:VGroup> 
</s:Application>

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.

Using a busy cursor

Flex defines a default busy cursor that you can use to indicate that your application is processing, and that users should wait until that processing completes before the application will respond to inputs. The default busy cursor is an animated clock.

You can control a busy cursor in several ways:

  • You can use Cursor Manager methods to set and remove the busy cursor.

  • You can use the showBusyCursor property of the SWFLoader, WebService, HttpService, and RemoteObject classes to automatically display the busy cursor.

Setting a busy cursor

The following static Cursor Manager methods control the busy cursor:

Method

Description

 
setBusyCursor()

Displays the busy cursor.

 
removeBusyCursor()

Removes the busy cursor from the cursor list. If other busy cursor requests are still active in the cursor list, which means that you called the setBusyCursor() method more than once, a busy cursor does not disappear until you remove all busy cursors from the list.

You can modify the example in Creating and removing a cursor to use the default busy cursor, as the following example shows: 

<?xml version="1.0"?> 
<!-- cursors\DefBusyCursorApp.mxml --> 
<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"> 
 
    <fx:Script> 
        <![CDATA[ 
            import mx.managers.CursorManager; 
            import flash.events.*; 
            
            private function initImage(event:MouseEvent):void { 
                CursorManager.setBusyCursor(); 
                image1.load("../assets/DSC00034.JPG"); 
            } 
    
            private function loadComplete(event:Event):void { 
                CursorManager.removeBusyCursor(); 
            }    
        ]]> 
    </fx:Script> 
 
    <s:VGroup> 
        <!-- Image control to load the image. --> 
        <mx:Image id="image1" 
            height="50" 
            width="100" 
            scaleContent="true" 
            complete="loadComplete(event);"/> 
        
        <!-- Button triggers the load. --> 
        <s:Button id="myButton" label="Show" click="initImage(event);"/> 
    </s:VGroup> 
</s:Application>

Setting the busy cursor does not prevent a user from interacting with your application; a user can still enter text or select buttons. However, all containers support the enabled property. By default, this property is set to true to enable user interaction with the container and with the container's children. If you set the enabled property to false when you display a busy cursor, Flex dims the color of the container and of all of its children, and blocks user input to the container and to all of its children.

You can also disable user interaction for the entire application by setting the FlexGlobals.topLevelApplication.enabled property to false. If you are in a subclass or an ActionScript-only application, you must either explicitly import the mx.core.FlexGlobals class, or specify mx.core.FlexGlobals.topLevelApplication.enabled to set the property's value.

The busy cursor has a priority of CursorManagerPriority.LOW. Therefore, if the cursor list contains a cursor with a higher priority, the busy cursor does not appear until you remove the higher-priority cursor. To create a default busy cursor at a higher priority level, use the setCursor() method, as the following example shows:

<?xml version="1.0"?> 
<!-- cursors\ShowBusyCursorAppHighP.mxml --> 
<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"> 
 
    <fx:Script> 
        <![CDATA[ 
            import mx.managers.CursorManager; 
            import mx.managers.CursorManagerPriority; 
            import flash.events.*; 
            
            // Define a variable to hold the cursor ID. 
            private var cursorID:Number = 0; 
                       
            // Define event listener to display the busy cursor 
            // and to load the image. 
            private function initImage(event:MouseEvent):void { 
                // Set busy cursor. 
                cursorID = CursorManager.setCursor( 
styleManager.getStyleDeclaration("mx.managers.CursorManager").getStyle("busyCursor"),CursorManagerPriority.HIGH); 
                // 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);   
            }               
        ]]> 
    </fx:Script> 
 
    <s:VGroup> 
        <!-- Image control to load the image. --> 
        <mx:Image id="image1" 
            height="50" 
            width="100" 
            scaleContent="true" 
            complete="loadComplete(event);"/> 
 
        <!-- Button triggers the load. --> 
        <s:Button id="myButton" label="Show" click="initImage(event);"/> 
    </s:VGroup> 
</s:Application>

This statement uses the getStyleDeclaration() method of the top-level StyleManager (accessed with the Application object's styleManager property) to get the CSStyleDeclaration object for the Cursor Manager, and uses this object's getStyle() method to get the busy cursor, which it sets as a high priority cursor.

When you use this technique, you must also use the cursor ID in the removeCursor() method to remove the busy cursor.

Using the showBusyCursor property

The SWFLoader and MX Image controls, and the WebService, HTTPService, and RemoteObject classes, have a showBusyCursor property that automatically displays the default busy cursor until the class completes loading data. The default value is false.

The Spark Image control does not have a showBusyCursor property.

If you set the showBusyCursor property to true, Flex displays the busy cursor when the first progress event of the control is triggered, and hides the busy cursor when the complete event is triggered. The following example shows how you can simplify the example in the section Setting a busy cursor by using the showBusyCursor property of the MX Image control: 

<?xml version="1.0"?> 
<!-- cursors\ShowBusyCursorApp.mxml --> 
<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"> 
 
    <s:VGroup> 
        <!-- Image control to load the image. --> 
        <mx:Image id="image1" 
            height="50" 
            width="100" 
            scaleContent="true" 
            showBusyCursor="true"/> 
    
        <!-- Button triggers the load. --> 
        <s:Button id="myButton" label="Show" 
            click="image1.load('../assets/DSC00034.JPG');"/>    
    </s:VGroup> 
</s:Application>

Navigation

Using Flex » Enhancing usability

Adobe and Adobe Flash Platform are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries and are used by permission from Adobe. No other license to the Adobe trademarks are granted.