Packageflash.ui
Classpublic final class Mouse
InheritanceMouse Inheritance Object

Language version: ActionScript 3.0
Runtime version: 

The methods of the Mouse class are used to hide and show the mouse pointer, or to set the pointer to a specific style. The Mouse class is a top-level class whose properties and methods you can access without using a constructor. The pointer is visible by default, but you can hide it and implement a custom pointer.

View the examples.

See also

flash.events.MouseEvent


Public Properties
 PropertyDefined by
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
  cursor : String
[static] The name of the native cursor.
Mouse
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
  supportsCursor : Boolean
[static][read-only] Indicates whether the computer or device displays a persistent cursor.
Mouse
  supportsNativeCursor : Boolean
[static][read-only] Indicates whether the current configuration supports native cursors.
Mouse
Public Methods
 MethodDefined by
 Inherited
Indicates whether an object has a specified property defined.
Object
  
[static] Hides the pointer.
Mouse
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
  
[static] Registers a native cursor under the given name, with the given data.
Mouse
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
  
[static] Displays the pointer.
Mouse
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns the string representation of the specified object.
Object
  
[static] Unregisters the native cursor with the given name.
Mouse
 Inherited
Returns the primitive value of the specified object.
Object
Property detail
cursorproperty
cursor:String  [read-write]

Language version: ActionScript 3.0
Runtime version: AIR 1.5

The name of the native cursor.

Implementation
    public static function get cursor():String
    public function set cursor(value:String):void
supportsCursorproperty 
supportsCursor:Boolean  [read-only]

Language version: ActionScript 3.0
Runtime version: AIR 2

Indicates whether the computer or device displays a persistent cursor.

The supportsCursor property is true on most desktop computers and false on most mobile devices.

Note: Mouse events can be dispatched whether or not this property is true. However, mouse events may behave differently depending on the physical characteristics of the pointing device.

Implementation
    public static function get supportsCursor():Boolean

See also


Example
The following example is a simple test that indicates current support for a persistent cursor, or not. When testing this example, click the text field to see the property value:
import flash.events.~~;
import flash.display.~~;
import flash.ui.Mouse;
import flash.text.TextField;

var supportsCursorTxt:TextField = new TextField();
supportsCursorTxt.width = 200;
supportsCursorTxt.border = true;
addChild(supportsCursorTxt);

addEventListener (MouseEvent.CLICK, getScreenKeyboardType);

function getScreenKeyboardType(e:MouseEvent):void{
    supportsCursorTxt.text= "Supports Cursor is : " + String(flash.ui.Mouse.supportsCursor);

}

The following example tests and responds to different user input environments. This example assumes it is part of the code for a game that uses a cursor. First, the example tests to see if the environment supports a cursor. If not, it then tests to see if the environment supports interaction with a stylus. If so, then code can be inserted to customize the game for stylus use. If the environment supports finger interaction, code can be inserted to customize the program for the specific needs of finger touches. If no pointing device is supported at all, then the developer needs to create alternative cursors or some means of interaction, such as key presses.
if(Mouse.supportsCursor) {
    //Game acts as before
} else {
    if(Capabilities.touchscreenType == TouchscreenType.STYLUS ){
        //The Game has to change so that the character is chasing the location of the stylus as 
        //it's dragged around. Some of the animations will have to change
    }else if(Capabilities.touchscreenType = TouchscreenType.FINGER){
        //Same as above, except that the hit-area is larger for a finger.
    }else{
        //There's no pointing device at all. The developer designs some sort of custom cursor to 
        //be controlled with key presses or similar input
    }
}

supportsNativeCursorproperty 
supportsNativeCursor:Boolean  [read-only]

Language version: ActionScript 3.0
Runtime version: AIR 1.5

Indicates whether the current configuration supports native cursors.

Implementation
    public static function get supportsNativeCursor():Boolean
Method detail
hide()method
public static function hide():void

Language version: ActionScript 3.0
Runtime version: 

Hides the pointer. The pointer is visible by default.

Note: You need to call Mouse.hide() only once, regardless of the number of previous calls to Mouse.show().

See also

registerCursor()method 
public static function registerCursor(name:String, cursor:MouseCursorData):void

Language version: ActionScript 3.0
Runtime version: AIR 1.5

Registers a native cursor under the given name, with the given data.

Parameters
name:String
 
cursor:MouseCursorData
show()method 
public static function show():void

Language version: ActionScript 3.0
Runtime version: 

Displays the pointer. The pointer is visible by default.

Note: You need to call Mouse.show() only once, regardless of the number of previous calls to Mouse.hide().

See also

unregisterCursor()method 
public static function unregisterCursor(name:String):void

Language version: ActionScript 3.0
Runtime version: AIR 1.5

Unregisters the native cursor with the given name.

Parameters
name:String
Examples
examples\MouseExample
The following example uses the MouseExample, SimpleButton, ButtonDisplayState, and CustomCursor classes to place a simple button on the Stage. The button has a custom pointer and the button changes when clicked. This is accomplished with the following steps:
  1. Declare the following instance properties: cursor of type CustomCursor, child of type CustomButton, and gutter of type uint.
  2. Assign child to a new CustomButton instance, set its x and y coordinates to 10 pixels each, and then add the instance to the display list. The CustomButton class overrides the downState, upState, overState, and hitTestState properties in SimpleButton. Each of these properties instantiates a ButtonDisplayState object, which draws a different square, depending on the state of the child instance.
  3. The child instance is then used to add a MOUSE_OVER event listener and mouseOverHandler() listener method, along with a MOUSE_OUT event listener and associated mouseOutHandler() method.
  4. The event listeners work as follows:
    • mouseOverHandler: Hides the "normal" pointer and adds a MOUSE_MOVE listener, which processes the mouse moves using mouseMoveHandler(), described below.
    • mouseOutHandler: When the mouse moves outside the custom button, the "normal" pointer is shown, the MOUSE_MOVE event listener is removed, and the custom cursor's visibility is set to false.
    • mouseMoveHandler: Moves the custom cursor around wherever the pointer is moved and sets the custom cursor's visibility to true.
  5. Back in the MouseExample constructor, the cursor property is assigned to a new CustomCursor object and then added to the display list using addChild(). The CustomCursor class draws a small nearly black square in place of the "normal" pointer whenever the mouse is over child.
  6. A fourth event listener of type MOUSE_LEAVE is added, with the associated mouseLeaveHandler() method. In this method (called if the mouse leaves the Stage), mouseOutHandler() is passed a new mouseMove listener object, which essentially removes the pointer so it is not left on the Stage.
package {
    import flash.display.Sprite;
    import flash.display.DisplayObject;
    import flash.ui.Mouse;
    import flash.events.*;

    public class MouseExample extends Sprite {
         private var cursor:CustomCursor;
         private var child:CustomButton;
         private var gutter:uint = 10;

        public function MouseExample() {
            child = new CustomButton();
            child.x = gutter;
            child.y = gutter;
            addChild(child);

            child.addEventListener(MouseEvent.MOUSE_OVER, mouseOverHandler);
            child.addEventListener(MouseEvent.MOUSE_OUT, mouseOutHandler);

            cursor = new CustomCursor();
            addChild(cursor);

            stage.addEventListener(Event.MOUSE_LEAVE, mouseLeaveHandler);
        }

        private function mouseOverHandler(event:MouseEvent):void {
            trace("mouseOverHandler");
            Mouse.hide();
            child.addEventListener(MouseEvent.MOUSE_MOVE, mouseMoveHandler);
        }

        private function mouseOutHandler(event:MouseEvent):void {
            trace("mouseOutHandler");
            Mouse.show();
            child.removeEventListener(MouseEvent.MOUSE_MOVE, mouseMoveHandler);
            cursor.visible = false;
        }

        private function mouseMoveHandler(event:MouseEvent):void {
            trace("mouseMoveHandler");
            cursor.x = event.localX;
            cursor.y = event.localY;
            event.updateAfterEvent();
            cursor.visible = true;
        }

        private function mouseLeaveHandler(event:Event):void {
            trace("mouseLeaveHandler");
            mouseOutHandler(new MouseEvent(MouseEvent.MOUSE_MOVE));
        }
    }
}

import flash.display.Shape;
import flash.display.SimpleButton;
    
class CustomButton extends SimpleButton {
    var upColor:uint = 0xFFCC00;
    var overColor:uint = 0xCCFF00;
    var downColor:uint = 0x00CCFF;
    var size:uint = 80;
    
    public function CustomButton() {
        downState = new ButtonDisplayState(downColor, size+10);
        overState = new ButtonDisplayState(overColor, size);
        upState = new ButtonDisplayState(upColor, size);
        hitTestState = new ButtonDisplayState(upColor, size);
    }
}

class ButtonDisplayState extends Shape {
    var bgColor:uint;
    var size:uint;
    
    public function ButtonDisplayState(bgColor:uint, size:uint) {
        this.bgColor = bgColor;
        this.size = size;
        draw();
    }
    
    private function draw():void {
        graphics.clear();
        graphics.beginFill(bgColor);
        graphics.drawRect(0, 0, size, size);
        graphics.endFill();
    }
}
    
class CustomCursor extends Shape {
    var bgColor:uint = 0x333333;
    var size:uint = 10;
    
    public function CustomCursor() {
        visible = false;
        draw();
    }
    
    private function draw():void {
        graphics.clear();
        graphics.beginFill(bgColor);
        graphics.drawRect(0, 0, size, size);
        graphics.endFill();
    }
}