Mouse Object Functions
Function Synopsis
| Function | Brief Description |
|---|---|
| move_delay([delay]) | The delay at each pixel movement. |
| down_delay([delay]) | How long the mouse stays down when "clicked". |
| click_delay([delay]) | How long to pause between mouse clicks. |
| click(btn[, cnt]) | Click the mouse. |
| btn_down(btn) | Press and hold down the mouse. Don't forget to release it! |
| btn_up(btn) | Release a previously pressed down mouse. |
| move(x, y[, win]) | Moves the mouse to the specified coordinates. |
| x([win]) | Returns the mouse's current y position. |
| y([win]) | Returns the mouse's current y position. |
Function:
move_delay([delay])
How long to wait between at each pixel movement in milliseconds. 0 means move the mouse instantly. 10 is the default, and moves the mouse fairly rapidly. Anything greater than about 100 will start being annoying. Does not make any changes if delay is less than zero or is omitted.
Parameters:
| Param | Req | Description |
|---|---|---|
| delay | no | The delay in milliseconds |
Return Value:
The current delay which may or may not have changed.Example(s):
#Change the move delay to 5 ms import xaut mouse = xaut.mouse() delay = mouse.move_delay(5) print(delay) #Prints "5"
#Make mouse jump instantly import xaut mouse = xaut.mouse() delay = mouse.move_delay(0) print(delay) #Prints "0"
#Find the current delay without making any changes import xaut mouse = xaut.mouse() delay = mouse.move_delay() print(delay) #Prints current delay
Function:
down_delay([delay])
How long the mouse button stays down when "clicked" in milliseconds. Default is 10 milliseconds, and usually works with most applications. Does not make any changes if delay is less than zero. Regardless, this function always returns the current delay.
Parameters:
| Param | Req | Description |
|---|---|---|
| delay | no | The delay in milliseconds |
Return Value:
The current delay which may or may not have changed.Example(s):
#Change the down delay to 5 ms import xaut mouse = xaut.mouse() delay = mouse.down_delay(5) print(delay) #Prints "5"
#Find the current delay without making any changes import xaut mouse = xaut.mouse() delay = mouse.down_delay() print(delay) #Prints current delay
Function:
click_delay([delay])
The number of milliseconds delay between clicks in a multi-click event. Default is 10 milliseconds, and usually works with most applications. Does not make any changes if delay is less than zero. Regardless, this function always returns the current delay.
Parameters:
| Param | Req | Description |
|---|---|---|
| delay | no | The delay in milliseconds |
Return Value:
The current delay which may or may not have changed.Example(s):
#Change the click delay to 5 ms import xaut mouse = xaut.mouse() delay = mouse.click_delay(5) print(delay) #Prints "5"
#Find the current delay without making any changes import xaut mouse = xaut.mouse() delay = mouse.click_delay() print(delay) #Prints current delay
Function:
click(btn[, cnt])
Performs a mouse click. In pseudo-code this performs the following:
for i = 1 to count
mouse_down(btn)
sleep_millis(mouse_down_delay)
mouse_up(btn)
if count > i
sleep_millis(mouse_click_delay)
endif
next
Parameters:
| Param | Req | Description |
|---|---|---|
| btn | yes | The mouse button to click |
| cnt | no | The number of clicks. 1 is default. |
Return Value:
Non-zero value if call succeeds, zero otherwise.
Be cautious, "succeeds" in this context doesn't necessarily mean that your application received the mouse click. It means that X11 did not report any errors or throw any exceptions.
Example(s):
#Click the mouse once import xaut mouse = xaut.mouse() mouse.click(1)
#Double click the mouse import xaut mouse = xaut.mouse() mouse.click(1, 2)
#Click the middle mouse button import xaut mouse = xaut.mouse() mouse.click(2)
Function:
btn_down(btn)
Presses down and does not release the button pointed to by btn. Note that this must be followed by a call to btn_up, otherwise the mouse will stay down until a sequence of events causes X11 to reset mouse status.
The most reasonable use for this method is to perform a mouse selection. You would put the mouse at one corner of the drag operation, press the button down, move the mouse to the opposite corner of the drag, and then release the button.
Parameters:
| Param | Req | Description |
|---|---|---|
| btn | yes | The button to press down |
Return Value:
Non-zero value of call succeeds, zero otherwise.
Be cautious, "succeeds" in this context doesn't necessarily mean that your application received the mouse click. It means that X11 did not report any errors or throw any exceptions.
Example(s):
#Performs a selection over the area 100x100 -> 200x200 import xaut mouse = xaut.mouse() mouse.move(100, 100) mouse.btn_down(1) mouse.move(200, 200) mouse.btn_up(1)
Parameters:
| Param | Req | Description |
|---|---|---|
| btn | yes | Releases the button |
Return Value:
Non-zero value of call succeeds, zero otherwise.
Be cautious, "succeeds" in this context doesn't necessarily mean that your application received the mouse click. It means that X11 did not report any errors or throw any exceptions.
Example(s):
#Performs a selection over the area 100x100 -> 200x200 import xaut mouse = xaut.mouse() mouse.move(100, 100) mouse.btn_down(1) mouse.move(200, 200) mouse.btn_up(1)
Function:
move(x, y[, win])
Moves the mouse to the coordinates supplied.
If a window is not supplied, then the coordinates are considered relative to the screen. In this case, the x and y coordinates supplied are normalized such that they cannot be less than zero or greater than the screen's resolution.
If a window is supplied, then the coordinates are considered relative to the window. In this case, the x and y coordinates are normalized such that their relative values cannot exceed the maximum absolute values that the windows position dictates. For example, if a window's top left coordinates are 100 x 100, then the minimum value allowed in this function are -100 x -100.
Parameters:
| Param | Req | Description |
|---|---|---|
| x | yes | The desired target x coordinate |
| y | yes | The desired target y coordinate |
| win | no | The x and y coordinates are relative to this window. |
Return Value:
Non-zero value of call succeeds, zero otherwise.
Be cautious, "succeeds" in this context doesn't necessarily mean that your application received the mouse click. It means that X11 did not report any errors or throw any exceptions.
Example(s):
#Move the mouse smoothly to 100x100 (like a user would) import xaut mouse = xaut.mouse() mouse.move(100, 100)
#Move the mouse instantly to 100x100 import xaut mouse = xaut.mouse() mouse.move_delay(0) mouse.move(100, 100)
#Move the mouse to 20x20 on the current window import xaut win = xaut.window.active_window() mouse = xaut.mouse() mouse.move(20, 20, win)
Function:
x([win])
Returns the mouse's current x coordinate. If a window object is supplied as a parameter, then the x coordinate is relative to the window.
Parameters:
| Param | Req | Description |
|---|---|---|
| win | no | If supplied, then the x coordinate is relative to the window. |
Return Value:
The x coordinate.
Returns "INT_MIN" (which is architecture dependent) and prints an error to the error stream in the event the call fails. Basically, if you receive an impossibly small value the call most likely failed.
Example(s):
#Get the current absolute x coordinate import xaut mouse = xaut.mouse() x = mouse.x() msg = "The mouse's current x coordinate is %d" % (x) print(msg)
#Get the current x coordinate relative to the active window import xaut mouse = xaut.mouse() win = xaut.window.active_window() x = mouse.x(win) msg = "The mouse x is at %d relative to %s" % (x, win.name()) print(msg)
#Attempt to get the x coordinate with an invalid window import xaut mouse = xaut.mouse() win = xaut.window(3) # <- ALMOST CERTAINLY THAT IS INVALID!! x = mouse.x(win) msg = "The value returned was %d" % (x) print(msg) #Notice that it printed an impossibly small number.
Function:
y([win])
Returns the mouse's current y coordinate. If a window object is supplied as a parameter, then the y coordinate is relative to the window.
Parameters:
| Param | Req | Description |
|---|---|---|
| win | no | If supplied, then the y coordinate is relative to the window. |
Return Value:
The y coordinate.
Returns "INT_MIN" (which is architecture dependent) and prints an error to the error stream in the event the call fails. Basically, if you receive an impossibly small value the call most likely failed.
Example(s):
#Get the current absolute y coordinate import xaut mouse = xaut.mouse() y = mouse.y() msg = "The mouse's current y coordinate is %d" % (y) print(msg)
#Get the current y coordinate relative to the active window import xaut mouse = xaut.mouse() win = xaut.window.active_window() y = mouse.y(win) msg = "The mouse is at %d relative to %s" % (y, win.name()) print(msg)
#Attempt to get the y coordinate with an invalid window import xaut mouse = xaut.mouse() win = xaut.window(3) # <- ALMOST CERTAINLY THAT IS INVALID!! y = mouse.y(win) msg = "The value returned was %d" % (y) print(msg) #Notice that it printed an impossibly small number.