mouse

​
Inspect/manipulate the position of the mouse pointer
This module is based primarily on code from the previous incarnation of Mjolnir by Steven Degutis.
This module uses ManyMouse by Ryan C. Gordon.
MANYMOUSE LICENSE:
Copyright (c) 2005-2012 Ryan C. Gordon and others.
This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.
Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:
1.The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.
2.Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
3.This notice may not be removed or altered from any source distribution.
Ryan C. Gordon [email protected]​
API Overview
Functions - API calls offered directly by the extension
​absolutePosition​
​count​
​getButtons​
​getCurrentScreen​
​getRelativePosition​
​names​
​scrollDirection​
​setRelativePosition​
​trackingSpeed​
API Documentation
Functions
​absolutePosition​
Signature
hs.mouse.absolutePosition([point]) -> point
Type
Function
Description
Get or set the absolute co-ordinates of the mouse pointer
Parameters
An optional point table containing the absolute x and y co-ordinates to move the mouse pointer to
Returns
A point table containing the absolute x and y co-ordinates of the mouse pointer
Notes
If no parameters are supplied, the current position will be returned. If a point table parameter is supplied, the mouse pointer poisition will be set and the new co-ordinates returned
​count​
Signature
hs.mouse.count([includeInternal]) -> number
Type
Function
Description
Gets the total number of mice connected to your system.
Parameters
includeInternal - A boolean which sets whether or not you want to include internal Trackpad's in the count. Defaults to false.
Returns
The number of mice connected to your system
Notes
This function leverages code from ManyMouse.
This function considers any mouse labelled as "Apple Internal Keyboard / Trackpad" to be an internal mouse.
​getButtons​
Signature
hs.mouse.getButtons() -> table
Type
Function
Description
Returns a table containing the current mouse buttons being pressed at this instant.
Parameters
None
Returns
Returns an array containing indicies starting from 1 up to the highest numbered button currently being pressed where the index is true if the button is currently pressed or false if it is not.
Special hash tag synonyms for left (button 1), right (button 2), and middle (button 3) are also set to true if these buttons are currently being pressed.
Notes
This function is a wrapper to hs.eventtap.checkMouseButtons
This is an instantaneous poll of the current mouse buttons, not a callback.
​getCurrentScreen​
Signature
hs.mouse.getCurrentScreen() -> screen or nil
Type
Function
Description
Gets the screen the mouse pointer is on
Parameters
None
Returns
An hs.screen object that the mouse pointer is on, or nil if an error occurred
​getRelativePosition​
Signature
hs.mouse.getRelativePosition() -> point or nil
Type
Function
Description
Gets the co-ordinates of the mouse pointer, relative to the screen it is on
Parameters
None
Returns
A point-table containing the relative x and y co-ordinates of the mouse pointer, or nil if an error occured
Notes
The co-ordinates returned by this function are relative to the top left pixel of the screen the mouse is on (see hs.mouse.getAbsolutePosition if you need the location in the full desktop space)
​names​
Signature
hs.mouse.names() -> table
Type
Function
Description
Gets the names of any mice connected to the system.
Parameters
None
Returns
A table containing strings of all the mice connected to the system.
Notes
This function leverages code from ManyMouse.
​scrollDirection​
Signature
hs.mouse.scrollDirection() -> string
Type
Function
Description
Gets the system-wide direction of scolling
Parameters
None
Returns
A string, either "natural" or "normal"
​setRelativePosition​
Signature
hs.mouse.setRelativePosition(point[, screen])
Type
Function
Description
Sets the co-ordinates of the mouse pointer, relative to a screen
Parameters
point - A point-table containing the relative x and y co-ordinates to move the mouse pointer to
screen - An optional hs.screen object. Defaults to the screen the mouse pointer is currently on
Returns
None
​trackingSpeed​
Signature
hs.mouse.trackingSpeed([speed]) -> number
Type
Function
Description
Gets/Sets the current system mouse tracking speed setting
Parameters
speed - An optional number containing the new tracking speed to set. If this is ommitted, the current setting is returned
Returns
A number indicating the current tracking speed setting for mice
Notes
This is represented in the System Preferences as the "Tracking speed" setting for mice
Note that not all values will work, they should map to the steps defined in the System Preferences app, which are:
0.0, 0.125, 0.5, 0.6875, 0.875, 1.0, 1.5, 2.0, 2.5, 3.0
Note that changes to this value will not be noticed immedaitely by macOS