uiCursors

Required: Aspire UI Components Standard Edition

The uiCursors manager implements the use of custom cursors.

To use custom cursors in your application, you must first initialize the uiCursors class by calling the uiCursors.initialize() method:

// ** initializes the uiCursor class passing the stage object for the parameter **
uiCursors.initialize(stage);

uiCursors is a singleton class. To access the manager, use uiCursors.manager.

To use a specific custom cursor, set the cursor property of the uiCursors manager:

import com.ghostwire.ui.controls.uiLabelButton;
import com.ghostwire.ui.managers.uiCursors;
import flash.events.MouseEvent;
 
uiCursors.initialize(stage);
 
var helpbtn:uiLabelButton = new uiLabelButton("Instructions");
helpbtn.move(50,20);
addChild(helpbtn);
 
helpbtn.addEventListener(MouseEvent.ROLL_OVER,on_btnOver);
helpbtn.addEventListener(MouseEvent.ROLL_OUT,on_btnOut);
 
function on_btnOver(evt:MouseEvent):void
{
    uiCursors.manager.cursor = "HELP"; // ** use HELP.png as custom cursor **
}
function on_btnOut(evt:MouseEvent):void
{
    uiCursors.manager.cursor = null; // ** use default custom cursor **
}

NOTE: Custom cursors will not work with mouse interactive text fields, which includes editable (input) text fields; when the mouse hovers over such objects, the native Flash Player I-beam cursor will be used.

Assets for the custom cursors are PNG bitmap images stored in the folder “assets/images/cursors/”. The custom cursor will be rendered using the uiImage class. If you change the path property of the com.ghostwire.ui.controls.uiImage class (from the default “assets/images/”), the path for the cursor assets will change accordingly.

Where naming convention is concerned, we will keep custom cursor asset names in upper case, so the assets are stored as “ARROW.png”, “BUSY.png”, “HELP.png”, etc.

When designing your own custom cursor image, you should take note of the following:

• The image will be rendered “as is” without resizing.
• The image should use transparent background.
• The center point of the image is the “pointer” and will coincide with the mouse position. This means that for arrow-like cursors where the tip of the arrow should coincide with the mouse position, you would design the image such that the painted area occupy the lower bottom right quadrant of the image (with the pointer at the center of the image).

Example:¹⁾

The default custom cursor is “ARROW” (asset is “ARROW.png”). You can change this value by setting the defaultCursor property. For example, to use “NICE_CURSOR.png” as the default cursor, you would do:

uiCursors.manager.defaultCursor = "NICE_CURSOR";

NOTE: You need not include the file extension when specifying the cursor asset. This is because uiImage will use the default ”.png” file extension if you specify the source without the file extension.

For more information on the members of the com.ghostwire.ui.managers.uiCursors class, please refer to the API Reference.