flash.ui

# Mouse - AS3

Package | flash.ui
Class | public final class Mouse
Inheritance | Mouse Object

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

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

More examples

Customizing the mouse cursor
Mouse input example: WordSearch

Learn more

Capturing mouse input

Related API Elements

flash.events.MouseEvent

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | constructor : 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
|  | 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
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | hide():void [static] Hides the pointer. | Mouse
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | registerCursor(name:String, cursor:MouseCursorData):void [static] Registers a native cursor under the given name, with the given data. | Mouse
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | show():void [static] Displays the pointer. | Mouse
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | unregisterCursor(name:String):void [static] Unregisters the native cursor with the given name. | Mouse
|  | valueOf():Object Returns the primitive value of the specified object. | Object

Property Detail

### cursor

property

`cursor:String`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10.2, AIR 1.5

The name of the native cursor.

Implementation
`public static function get cursor():String`
`public static function set cursor(value:String):void`

### supportsCursor

property

`supportsCursor:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10.1, 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`

Related API Elements

flash.system.Capabilities.touchscreenType
Example ( How to use this 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);

    }

Copy
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.
Copy

    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
        }
    }

### supportsNativeCursor

property

`supportsNativeCursor:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10.2, 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 Versions: | AIR 1.0, Flash Player 9

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()`.

Related API Elements

flash.display.DisplayObject.mouseX
flash.display.DisplayObject.mouseY

### registerCursor

()
method

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

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10.2, 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 Versions: | AIR 1.0, Flash Player 9

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()`.

Related API Elements

flash.display.DisplayObject.mouseX
flash.display.DisplayObject.mouseY

### unregisterCursor

()
method

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

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10.2, AIR 1.5

Unregisters the native cursor with the given name.

Parameters

| `name:String`

Examples How to use this example
MouseExample.as
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.

Copy

    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();
        }
    }

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00