By default, the Flex application cursor is an arrow, except when a selectable/editable text element has focus, at which point the cursor becomes a text selection cursor. Using the mx.managers.CursorManager class you can control the cursor that gets displayed in the application. This can be useful for giving the user a visual queue of the status of the application.

The CursorManager class has a handful of static methods that allow you to control the cursor by doing the following: showing and removing busy cursors and showing and removing custom cursors.

The Flex framework has just one built-in cursor apart from the default system cursors. The one built-in cursor is a busy cursor that displays a small clock face with a spinning hand to let the user know that something is being processed. The CursorManager class has two static methods for displaying and removing the busy cursor: setBusyCursor() and removeBusyCursor(). The following demonstrates a very simple example that sets and removes the busy cursor when the user clicks two buttons:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

  <mx:Script>
  <![CDATA[

    import mx.managers.CursorManager;

  ]]>
  </mx:Script>

  <mx:VBox>
    <mx:Button label="Show Busy Cursor" click="CursorManager.setBusyCursor()" />
    <mx:Button label="Hide Busy Cursor" click="CursorManager.removeBusyCursor()"
/>
  </mx:VBox>

</mx:Application>

Typically, you would use the busy cursor for asynchronous operations such as remote procedure calls. You can use the setBusyCursor() method just prior to starting such an operation, and you can call removeBusyCursor() when the operation completes. To simplify things, several of the components have a built-in feature that automatically does this. The SWFLoader, WebService, HttpService, and RemoteObject components all allow you to set a showBusyCursor property. When the showBusyCursor property is set to true for any of these components, the component automatically displays the busy cursor when initiating the request, and it hides the busy cursor when the response is complete.

For customized cursors you can use any standard embedded graphic or SWF as a cursor using the CursorManager.setCursor() method. You can remove custom cursors using the removeCursor() method.

The setCursor() method requires at least one parameter: the Class object representing the embedded graphic. Example 10-6 uses a PNG as the cursor.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
                initialize="initializeHandler(event)">

  <mx:Script>
  <![CDATA[

    import mx.managers.CursorManager;

    [Embed(source="cursor.png")]
    private var customCursor:Class;

    private function initializeHandler(event:Event):void {
      CursorManager.setCursor(customCursor);
    }

  ]]>
  </mx:Script>

</mx:Application>

The setCursor() method returns an integer ID, which you need in order to remove the cursor. You can pass the ID to the removeCursor() method, as the following example illustrates:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
                initialize="initializeHandler(event)">

  <mx:Script>
  <![CDATA[

    import mx.managers.CursorManager;

    [Embed(source="cursor.png")]
    private var customCursor:Class;

    private var cursorId:int;

    private function initializeHandler(event:Event):void {
      cursorId = CursorManager.setCursor(customCursor);
    }

  ]]>
  </mx:Script>

  <mx:Button label="Reset Cursor" click="CursorManager.removeCursor(cursorId)" />

</mx:Application>

In this example, the custom cursor is applied when the application initializes using an initialize event handler. When the user clicks the button, it calls the removeCursor() method to remove the cursor. Note that the cursor ID returned by setCursor() is saved in a property so that it is accessible throughout the document.