Mouse

Edit on GitHub

S	Return	Name	Parameters
		Mouse	(void)
	void	Click	(Button button) const
	void	Press	(Button button) const
	void	Release	(Button button) const
	void	ScrollH	(int32 amount) const
	void	ScrollV	(int32 amount) const
✔	Point	GetPos	(void)
✔	void	SetPos	(const Point& point)
✔	void	SetPos	(uint32 x, uint32 y)
✔	bool	GetState	(Button button)
✔	bool	GetState	(ButtonState& result)
	Range	AutoDelay

Description

Provides a simple interface for generating native mouse events on the system. These events can be used for the purposes of test automation, self-running demos, and other applications where control of the mouse is needed. Certain platforms require special privileges or extensions to access low-level mouse controls. If the current platform configuration does not allow this, most of the functionality in the class will perform no operation or return otherwise invalid data. As an example, Linux depends on XTest 2.2 to carry out the majority of the low-level functionality, when missing, the class will not work.

Although mouse events are system-wide, a mouse object must still be created through the Constructor in order to support multiple auto delays. Once created, use the Press and Release functions to generate mouse button press and release events. Use the Click function to generate both a press, followed by a release. Use the ScrollH and ScrollV functions to generate either a horizontal or vertical mouse scroll event. All these functions will block after generating an event, the amount of time blocked can be configured through the AutoDelay property.

The Mouse class also offers a variety of non-blocking static functions. For instance, the position of the mouse can be manipulated through the GetPos and SetPos functions. Additionally, the current down-state of one of more mouse buttons can be retrieved through the GetState functions.

Types

typedef unordered_map<Button, bool> Robot::ButtonState;

Constructors

    

        



            
Mouse
            
(void)
        
    

Constructs a mouse with an AutoDelay between 40 and 90 milliseconds.

Functions

    

        


            
void
            
Click
            
(Button button) const
        
    

Performs a Press followed by a Release.

    

        


            
void
            
Press
            
(Button button) const
        
        


            
void
            
Release
            
(Button button) const
        
    

Presses or releases a single mouse button and blocks for AutoDelay milliseconds. The value of button can be any valid Button, however, not all buttons are supported on all platforms and will be ignored without blocking. Passing a button which is not part of the Button enumeration leads to undefined results. A pressed button should always be released. Pressing or releasing the same button multiple times is not always guaranteed to generate respective press or release events on the target platform.

Mac: Double clicking is simulated using an internal timer, therefore, calling click twice within a short period of time will simulate a double click, just like it would on any other platform.

    

        


            
void
            
ScrollH
            
(int32 amount) const
        
        


            
void
            
ScrollV
            
(int32 amount) const
        
    

Rotates the scroll wheel on wheel-equipped mice and blocks for AutoDelay milliseconds. Depending on the function used, the scroll wheel will either be rotated horizontally or vertically. amount refers to the physical number of "notches" to scroll. For horizontal scrolling, negative values indicate movement to the left while positive values indicate movement to the right. For vertical scrolling, negative values indicate movement down/towards the user while positive values indicate movement up/away from the user.

    

        

            
static
            
Point
            
GetPos
            
(void)
        
        

            
static
            
void
            
SetPos
            
(const Point& point)
        
        

            
static
            
void
            
SetPos
            
(uint32 x, uint32 y)
        
    

Gets or sets the global position of the mouse cursor in pixels. Out of bounds values are automatically corrected by the platform so that the cursor remains within the boundaries of the display devices on the computer.

    

        

            
static
            
bool
            
GetState
            
(Button       button)
        
    

Returns true if button is currently pressed system-wide, regardless of whether or not the calling application has focus. The value of button can be any valid Button, however, not all buttons are supported on all platforms and thus, will cause this function to return false. Passing a button which is not part of the Button enumeration will also cause this function to return false. If two of more button states need to be checked, consider using the other GetState function for improved performance.

    

        

            
static
            
bool
            
GetState
            
(ButtonState& result)
        
    

Checks the pressed state of all buttons system-wide, regardless of whether or not the calling application has focus. If an error occurs, this function will return false, however, result will always be cleared regardless of whether or not this function succeeds. Not all buttons are supported on all platforms and thus, will always be set to false. If only one button state needs to be checked, consider using the other GetState function for improved performance.

Properties

    

        


            
Range
            
AutoDelay
            

        
    

Provides direct access to the automatic delay range in milliseconds.

Button

Represents the mouse buttons supported by this class. These buttons do not map to any platform-dependent value. ButtonLeft and ButtonRight map to the users system-configured buttons rather than physical mouse buttons. ButtonMid and ButtonMiddle map to the same button. ButtonX1 and ButtonX2 are only supported on Windows and will be ignored when used on Linux and Mac.

enum Button
{
    ButtonLeft,
    ButtonMid,
    ButtonMiddle,
    ButtonRight,
    ButtonX1,
    ButtonX2,
};

Examples

// C++
#include <Robot.h>
ROBOT_NS_USE_ALL;

int main (void)
{
    Mouse mouse;
    // Click the right button
    mouse.Click (ButtonRight);

    // Current mouse position
    auto pos = Mouse::GetPos();

    // Move the mouse left
    // and up by 50 pixels
    Mouse::SetPos (pos - 50);

    // Change default auto delay
    mouse.AutoDelay.Min = 100;
    mouse.AutoDelay.Max = 200;

    // Maybe select some text
    mouse.Press   (ButtonLeft);
    mouse.ScrollV (4); // up
    mouse.Release (ButtonLeft);

    ButtonState s;
    while (true)
    {
        // Press left and right
        // buttons to exit loop
        Mouse::GetState (s);
        if (s[ButtonLeft ] &&
            s[ButtonRight])
            break;

        // Avoid busy wait
        Timer::Sleep (15);
    }

    return 0;
}

// Node
var robot = require ("robot-js");

var mouse = robot.Mouse();
// Click the right button
mouse.click (robot.BUTTON_RIGHT);

// Get current mouse position
var pos = robot.Mouse.getPos();

// Move the mouse left
// and up by 50 pixels
robot.Mouse.setPos (pos.sub (50));

// Change default auto delay
mouse.autoDelay.min = 100;
mouse.autoDelay.max = 200;

// Maybe select text in an editor
mouse.press   (robot.BUTTON_LEFT);
mouse.scrollV (4); // up
mouse.release (robot.BUTTON_LEFT);

while (true)
{
    // Press left and right
    // buttons to exit loop
    var s = robot.Mouse.getState();
    if (s[robot.BUTTON_LEFT ] &&
        s[robot.BUTTON_RIGHT])
        break;

    // Avoid busy waiting
    robot.Timer.sleep (15);
}