event

​
Create, modify and inspect events for hs.eventtap
This module is based primarily on code from the previous incarnation of Mjolnir by Steven Degutis.
hs.eventtap.event.newGesture uses an external library by Calf Trail Software, LLC.
Touch Copyright (C) 2010 Calf Trail Software, LLC
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
API Overview
Constants - Useful values which cannot be changed
​properties​
​rawFlagMasks​
​types​
Functions - API calls offered directly by the extension
​newKeyEventSequence​
Constructors - API calls which return an object, typically one that offers API methods
​copy​
​newEvent​
​newEventFromData​
​newGesture​
​newKeyEvent​
​newMouseEvent​
​newScrollEvent​
​newSystemKeyEvent​
Methods - API calls which can only be made on an object returned by a constructor
​asData​
​getButtonState​
​getCharacters​
​getFlags​
​getKeyCode​
​getProperty​
​getRawEventData​
​getTouchDetails​
​getTouches​
​getType​
​getUnicodeString​
​location​
​post​
​rawFlags​
​setFlags​
​setKeyCode​
​setProperty​
​setType​
​setUnicodeString​
​systemKey​
​timestamp​
API Documentation
Constants
​properties​
Signature
hs.eventtap.event.properties -> table
Type
Constant
Description
A table containing property types for use with hs.eventtap.event:getProperty() and hs.eventtap.event:setProperty(). The table supports forward (label to number) and reverse (number to label) lookups to increase its flexibility.
​rawFlagMasks​
Signature
hs.eventtap.event.rawFlagMasks[]
Type
Constant
Description
A table containing key-value pairs describing the raw modifier flags which can be manipulated with hs.eventtap.event:rawFlags.
​types​
Signature
hs.eventtap.event.types -> table
Type
Constant
Description
A table containing event types to be used with hs.eventtap.new(...) and returned by hs.eventtap.event:type(). The table supports forward (label to number) and reverse (number to label) lookups to increase its flexibility.
Functions
​newKeyEventSequence​
Signature
hs.eventtap.event.newKeyEventSequence(modifiers, character) -> table
Type
Function
Description
Generates a table containing the keydown and keyup events to generate the keystroke with the specified modifiers.
Parameters
modifiers - A table containing the keyboard modifiers to apply ("cmd", "alt", "shift", "ctrl", "rightCmd", "rightAlt", "rightShift", "rightCtrl", or "fn")
character - A string containing a character to be emitted
Returns
a table with events which contains the individual events that Apple recommends for building up a keystroke combination (see hs.eventtap.event.newKeyEvent) in the order that they should be posted (i.e. the first half will contain keyDown events and the second half will contain keyUp events)
Notes
The modifiers table must contain the full name of the modifiers you wish used for the keystroke as defined in hs.keycodes.map -- the Unicode equivalents are not supported by this function.
The returned table will always contain an even number of events -- the first half will be the keyDown events and the second half will be the keyUp events.
The events have not been posted; the table can be used without change as the return value for a callback to a watcher defined with hs.eventtap.new.
Constructors
​copy​
Signature
hs.eventtap.event:copy() -> event
Type
Constructor
Description
Duplicates an hs.eventtap.event event for further modification or injection
Parameters
None
Returns
A new hs.eventtap.event object
​newEvent​
Signature
hs.eventtap.event.newEvent() -> event
Type
Constructor
Description
Creates a blank event. You will need to set its type with hs.eventtap.event:setType​
Parameters
None
Returns
a new hs.eventtap.event object
Notes
this is an empty event that you should set a type for and whatever other properties may be appropriate before posting.
​newEventFromData​
Signature
hs.eventtap.event.newEventFromData(data) -> event
Type
Constructor
Description
Creates an event from the data encoded in the string provided.
Parameters
data - a string containing binary data provided by hs.eventtap.event:asData representing an event.
Returns
a new hs.eventtap.event object or nil if the string did not represent a valid event
​newGesture​
Signature
hs.eventtap.event.newGesture(gestureType[, gestureValue]) -> event
Type
Constructor
Description
Creates an gesture event.
Parameters
gestureType - the type of gesture you want to create as a string (see notes below).
[gestureValue] - an optional value for the specific gesture (i.e. magnification amount or rotation in degrees).
Returns
a new hs.eventtap.event object or nil if the gestureType is not valid.
Notes
Valid gestureType values are:
beginMagnify - Starts a magnification event with an optional magnification value as a number (defaults to 0). The exact unit of measurement is unknown.
endMagnify - Starts a magnification event with an optional magnification value as a number (defaults to 0.1). The exact unit of measurement is unknown.
beginRotate - Starts a rotation event with an rotation value in degrees (i.e. a value of 45 turns it 45 degrees left - defaults to 0).
endRotate - Starts a rotation event with an rotation value in degrees (i.e. a value of 45 turns it 45 degrees left - defaults to 45).
beginSwipeLeft - Begin a swipe left.
endSwipeLeft - End a swipe left.
beginSwipeRight - Begin a swipe right.
endSwipeRight - End a swipe right.
beginSwipeUp - Begin a swipe up.
endSwipeUp - End a swipe up.
beginSwipeDown - Begin a swipe down.
endSwipeDown - End a swipe down.
​newKeyEvent​
Signature
hs.eventtap.event.newKeyEvent([mods], key, isdown) -> event
Type
Constructor
Description
Creates a keyboard event
Parameters
mods - An optional table containing zero or more of the following:
cmd
alt
shift
ctrl
fn
key - A string containing the name of a key (see hs.hotkey for more information) or an integer specifying the virtual keycode for the key.
isdown - A boolean, true if the event should be a key-down, false if it should be a key-up
Returns
An hs.eventtap.event object
Notes
The original version of this constructor utilized a shortcut which merged flagsChanged and keyUp/keyDown events into one. This approach is still supported for backwards compatibility and because it does work in most cases.
According to Apple Documentation, the proper way to perform a keypress with modifiers is through multiple key events; for example to generate 'Å', you should do the following:~~~lua hs.eventtap.event.newKeyEvent(hs.keycodes.map.shift, true):post() hs.eventtap.event.newKeyEvent(hs.keycodes.map.alt, true):post() hs.eventtap.event.newKeyEvent("a", true):post() hs.eventtap.event.newKeyEvent("a", false):post() hs.eventtap.event.newKeyEvent(hs.keycodes.map.alt, false):post() hs.eventtap.event.newKeyEvent(hs.keycodes.map.shift, false):post()~~~
The shortcut method is still supported, though if you run into odd behavior or need to generate flagsChanged events without a corresponding keyUp or keyDown, please check out the syntax demonstrated above.~~~lua hs.eventtap.event.newKeyEvent({"shift", "alt"}, "a", true):post() hs.eventtap.event.newKeyEvent({"shift", "alt"}, "a", false):post()~~~
​newMouseEvent​
Signature
hs.eventtap.event.newMouseEvent(eventtype, point[, modifiers) -> event
Type
Constructor
Description
Creates a new mouse event
Parameters
eventtype - One of the mouse related values from hs.eventtap.event.types
point - An hs.geometry point table (i.e. of the form {x=123, y=456}) indicating the location where the mouse event should occur
modifiers - An optional table (e.g. {"cmd", "alt"}) containing zero or more of the following keys:
cmd
alt
shift
ctrl
fn
Returns
An hs.eventtap object
​newScrollEvent​
Signature
hs.eventtap.event.newScrollEvent(offsets, mods, unit) -> event
Type
Constructor
Description
Creates a scroll wheel event
Parameters
offsets - A table containing the {horizontal, vertical} amount to scroll. Positive values scroll up or left, negative values scroll down or right.
mods - A table containing zero or more of the following:
cmd
alt
shift
ctrl
fn
unit - An optional string containing the name of the unit for scrolling. Either "line" (the default) or "pixel"
Returns
An hs.eventtap.event object
​newSystemKeyEvent​
Signature
hs.eventtap.event.newSystemKeyEvent(key, isdown) -> event
Type
Constructor
Description
Creates a keyboard event for special keys (e.g. media playback)
Parameters
key - A string containing the name of a special key. The possible names are:
SOUND_UP
SOUND_DOWN
MUTE
BRIGHTNESS_UP
BRIGHTNESS_DOWN
CONTRAST_UP
CONTRAST_DOWN
POWER
LAUNCH_PANEL
VIDMIRROR
PLAY
EJECT
NEXT
PREVIOUS
FAST
REWIND
ILLUMINATION_UP
ILLUMINATION_DOWN
ILLUMINATION_TOGGLE
CAPS_LOCK
HELP
NUM_LOCK
isdown - A boolean, true if the event should be a key-down, false if it should be a key-up
Returns
An hs.eventtap.event object
Notes
To set modifiers on a system key event (e.g. cmd/ctrl/etc), see the hs.eventtap.event:setFlags() method
The event names are case sensitive
Methods
​asData​
Signature
hs.eventtap.event:asData() -> string
Type
Method
Description
Returns a string containing binary data representing the event. This can be used to record events for later use.
Parameters
None
Returns
a string representing the event or nil if the event cannot be represented as a string
Notes
You can recreate the event for later posting with hs.eventtap.event.newEventFromData​
​getButtonState​
Signature
hs.eventtap.event:getButtonState(button) -> bool
Type
Method
Description
Gets the state of a mouse button in the event
Parameters
button - A number between 0 and 31. The left mouse button is 0, the right mouse button is 1 and the middle mouse button is 2. The meaning of the remaining buttons varies by hardware, and their functionality varies by application (typically they are not present on a mouse and have no effect in an application)
Returns
A boolean, true if the specified mouse button is to be clicked by the event
Notes
This method should only be called on mouse events
​getCharacters​
Signature
hs.eventtap.event:getCharacters([clean]) -> string or nil
Type
Method
Description
Returns the Unicode character, if any, represented by a keyDown or keyUp event.
Parameters
clean -- an optional parameter, default false, which indicates if key modifiers, other than Shift, should be stripped from the keypress before converting to Unicode.
Returns
A string containing the Unicode character represented by the keyDown or keyUp event, or nil if the event is not a keyUp or keyDown.
Notes
This method should only be used on keyboard events
If clean is true, all modifiers except for Shift are stripped from the character before converting to the Unicode character represented by the keypress.
If the keypress does not correspond to a valid Unicode character, an empty string is returned (e.g. if clean is false, then Opt-E will return an empty string, while Opt-Shift-E will return an accent mark).
​getFlags​
Signature
hs.eventtap.event:getFlags() -> table
Type
Method
Description
Gets the keyboard modifiers of an event
Parameters
None
Returns
A table containing the keyboard modifiers that present in the event - i.e. zero or more of the following keys, each with a value of true:
cmd
alt
shift
ctrl
fn
The table responds to the following methods:
contain(mods) -> boolean
Returns true if the modifiers contain all of given modifiers
containExactly(mods) -> boolean
Returns true if the modifiers contain all of given modifiers exactly and nothing else
Parameter mods is a table containing zero or more of the following:
cmd or ⌘
alt or ⌥
shift or ⇧
ctrl or ⌃
fn
​getKeyCode​
Signature
hs.eventtap.event:getKeyCode() -> keycode
Type
Method
Description
Gets the raw keycode for the event
Parameters
None
Returns
A number containing the raw keycode, taken from hs.keycodes.map
Notes
This method should only be used on keyboard events
​getProperty​
Signature
hs.eventtap.event:getProperty(prop) -> number
Type
Method
Description
Gets a property of the event
Parameters
prop - A value taken from hs.eventtap.event.properties
Returns
A number containing the value of the requested property
Notes
The properties are CGEventField values, as documented at https://developer.apple.com/library/mac/documentation/Carbon/Reference/QuartzEventServicesRef/index.html#//apple_ref/c/tdef/CGEventField
​getRawEventData​
Signature
hs.eventtap.event:getRawEventData() -> table
Type
Method
Description
Returns raw data about the event
Parameters
None
Returns
A table with two keys:
CGEventData -- a table with keys containing CGEvent data about the event.
NSEventData -- a table with keys containing NSEvent data about the event.
Notes
Most of the data in CGEventData is already available through other methods, but is presented here without any cleanup or parsing.
This method is expected to be used mostly for testing and expanding the range of possibilities available with the hs.eventtap module. If you find that you are regularly using specific data from this method for common or re-usable purposes, consider submitting a request for adding a more targeted method to hs.eventtap or hs.eventtap.event -- it will likely be more efficient and faster for common tasks, something eventtaps need to be to minimize affecting system responsiveness.
​getTouchDetails​
| Signature | hs.eventtap.event:getTouchDetails() -> table | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Returns a table contining more information about some touch related events. | | Parameters |
None
| | Returns |
if the event is a touch event (i.e. is an event of type hs.eventtap.event.types.gesture), then this method returns a table with zero or more of the following key-value pairs:
if the gesture is for a pressure event:
pressure - a number between 0.0 and 1.0 inclusive indicating the relative amount of pressure applied by the touch; trackpads which are not pressure sensitive will only report the discrete values of 0.0 and 1.0.
stage - an integer between 0 and 2 specifying the stage. 0 represents a touch transitioning to a state too light to be considered a touch, usually at the end of a click; 1 represents a touch with enough pressure to be considered a mouseDown event; 2 represents additional pressure, usually what would trigger a "deep" or "force" touch.
stageTransition - a number between 0.0 and 1.0. As the pressure increases and transition between stages begins, this will rise from 0.0 to 1.0; as the pressure decreases and a transition between stages begins, this will fall from 0.0 to -1.0. When the pressure is solidly within a specific stage, this will remain 0.0.
pressureBehavior - a string specifying the effect or purpose of the pressure. Note that the exact meaning (in terms of haptic feedback or action being performed) of each label is target application or ui element specific. Valid values for this key are:
"unknown", "default", "click", "generic", "accelerator", "deepClick", "deepDrag"
if the gesture is for a magnification event:
magnification - a number specifying the change in magnification that should be added to the current scaling of an item to achieve the new scale factor.
if the gesture is for a rotation event:
rotation - a number specifying in degrees the change in rotation that should be added as specified by this event. Clockwise rotation is indicated by a negative number while counter-clockwise rotation will be positive.
|
​getTouches​
| Signature | hs.eventtap.event:getTouches() -> table | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Returns a table of details containing information about touches on the trackpad associated with this event if the event is of the type hs.eventtap.event.types.gesture. | | Parameters |
None
| | Returns |
if the event is of the type gesture, returns a table; otherwise returns nil.
| | Notes |
if the event is of the type gesture, the table will contain one or more tables in an array. Each member table of the array will have the following key-value pairs:
device - a string containing a unique identifier for the device on which the touch occurred. At present we do not have a way to match the identifier to a specific touch device, but if multiple such devices are attached to the computer, this value will differ between them.
deviceSize - a size table containing keys h and w for the height and width of the touch device in points (72 PPI resolution).
force - a number representing a measure of the force of the touch when the device is a forcetouch trackpad. This will be 0.0 for non-forcetouch trackpads and the touchbar.
identity - a string specifying a unique identifier for the touch guaranteed to be unique for the life of the touch. This identifier may be used to track the movement of a specific touch (e.g. finger) as it moves through successive callbacks.
phase - a string specifying the current phase the touch is considered to be in. The possible values are: "began", "moved", "stationary", "ended", or "cancelled".
resting - Resting touches occur when a user simply rests their thumb on the trackpad device. Requires that the foreground window has views accepting resting touches.
timestamp - a number representing the time the touch was detected. This number corresponds to seconds since the last system boot, not including time the computer has been asleep. Comparable to hs.timer.absoluteTime() / 1000000000.
touching - a boolean specifying whether or not the touch phase is "began", "moved", or "stationary" (i.e. is not "ended" or "cancelled").
type - a string specifying the type of touch. A "direct" touch will indicate a touchbar, while a trackpad will report "indirect".
|
​getType​
Signature
hs.eventtap.event:getType([nsSpecificType]) -> number
Type
Method
Description
Gets the type of the event
Parameters
nsSpecificType - an optional boolean, default false, specifying whether or not a more specific Cocoa NSEvent type should be returned, if available.
Returns
A number containing the type of the event, taken from hs.eventtap.event.types
Notes
some newer events are grouped into a more generic event for watching purposes and the specific event type is determined by examining the event through the Cocoa API. The primary example of this is for gestures on a trackpad or touches of the touchbar, as all of these are grouped under the hs.eventtap.event.types.gesture event. For example:
​getUnicodeString​
Signature
hs.eventtap.event:getUnicodeString()
Type
Method
Description
Gets the single unicode character of an event
Parameters
None
Returns
A string containing the unicode character
​location​
| Signature | hs.eventtap.event:location([pointTable]) -> event | table | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the current mouse pointer location as defined for the event. | | Parameters |
pointTable - an optional point table specifying the x and y coordinates of the mouse pointer location for the event
| | Returns |
if pointTable is provided, returns the hs.eventtap.event object; otherwise returns a point table containing x and y key-value pairs specifying the mouse pointer location as specified for this event.
| | Notes |
the use or effect of this method is undefined if the event is not a mouse type event.
|
​post​
Signature
hs.eventtap.event:post([app])
Type
Method
Description
Posts the event to the OS - i.e. emits the keyboard/mouse input defined by the event
Parameters
app - An optional hs.application object. If specified, the event will only be sent to that application
Returns
The hs.eventtap.event object
​rawFlags​
| Signature | hs.eventtap.event:rawFlags([flags]) -> event | integer | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Experimental method to get or set the modifier flags for an event directly. | | Parameters |
flags - an optional integer, made by logically combining values from hs.eventtap.event.rawFlagMasks specifying the modifier keys which should be set for this event
| | Returns |
if flags is provided, returns the hs.eventtap.event object; otherwise returns the current flags set as an integer
| | Notes |
This method is experimental and may undergo changes or even removal in the future
See hs.eventtap.event.rawFlagMasks for more information
|
​setFlags​
Signature
hs.eventtap.event:setFlags(table) -> event
Type
Method
Description
Sets the keyboard modifiers of an event
Parameters
A table containing the keyboard modifiers to be sent with the event - i.e. zero or more of the following keys, each with a value of true:
cmd
alt
shift
ctrl
fn
Returns
The hs.eventap.event object.
​setKeyCode​
Signature
hs.eventtap.event:setKeyCode(keycode)
Type
Method
Description
Sets the raw keycode for the event
Parameters
keycode - A number containing a raw keycode, taken from hs.keycodes.map
Returns
The hs.eventtap.event object
Notes
This method should only be used on keyboard events
​setProperty​
Signature
hs.eventtap.event:setProperty(prop, value)
Type
Method
Description
Sets a property of the event
Parameters
prop - A value from hs.eventtap.event.properties
value - A number containing the value of the specified property
Returns
The hs.eventtap.event object.
Notes
The properties are CGEventField values, as documented at https://developer.apple.com/library/mac/documentation/Carbon/Reference/QuartzEventServicesRef/index.html#//apple_ref/c/tdef/CGEventField
​setType​
Signature
hs.eventtap.event:setType(type) -> event
Type
Method
Description
Set the type for this event.
Parameters
type - an integer matching one of the event types described in hs.eventtap.event.types​
Returns
the hs.eventtap.event object
​setUnicodeString​
Signature
hs.eventtap.event:setUnicodeString(string)
Type
Method
Description
Sets a unicode string as the output of the event
Parameters
string - A string containing unicode characters, which will be applied to the event
Returns
The hs.eventtap.event object
Notes
Calling this method will reset any flags previously set on the event (because they don't make any sense, and you should not try to set flags again)
This is likely to only work with short unicode strings that resolve to a single character
​systemKey​
Signature
hs.eventtap.event:systemKey() -> table
Type
Method
Description
Returns the special key and its state if the event is a NSSystemDefined event of subtype AUX_CONTROL_BUTTONS (special-key pressed)
Parameters
None
Returns
If the event is a NSSystemDefined event of subtype AUX_CONTROL_BUTTONS, a table with the following keys defined:
key -- a string containing one of the following labels indicating the key involved:
SOUND_UP
SOUND_DOWN
MUTE
BRIGHTNESS_UP
BRIGHTNESS_DOWN
CONTRAST_UP
CONTRAST_DOWN
POWER
LAUNCH_PANEL
VIDMIRROR
PLAY
EJECT
NEXT
PREVIOUS
FAST
REWIND
ILLUMINATION_UP
ILLUMINATION_DOWN
ILLUMINATION_TOGGLE
CAPS_LOCK
HELP
NUM_LOCK or "undefined" if the key detected is unrecognized.
keyCode -- the numeric keyCode corresponding to the key specified in key.
down -- a boolean value indicating if the key is pressed down (true) or just released (false)
repeat -- a boolean indicating if this event is because the keydown is repeating. This will always be false for a key release.
If the event does not correspond to a NSSystemDefined event of subtype AUX_CONTROL_BUTTONS, then an empty table is returned.
Notes
CAPS_LOCK seems to sometimes generate 0 or 2 key release events (down == false), especially on builtin laptop keyboards, so it is probably safest (more reliable) to look for cases where down == true only.
If the key field contains "undefined", you can use the number in keyCode to look it up in /System/Library/Frameworks/IOKit.framework/Headers/hidsystem/ev_keymap.h. If you believe the numeric value is part of a new system update or was otherwise mistakenly left out, please submit the label (it will defined in the header file as NX_KEYTYPE_something) and number to the Hammerspoon maintainers at https://github.com/Hammerspoon/hammerspoon with a request for inclusion in the next Hammerspoon update.
​timestamp​
| Signature | hs.eventtap.event:timestamp([absolutetime]) -> event | integer | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the timestamp of the event. | | Parameters |
absolutetime - an optional integer specifying the timestamp for the event.
| | Returns |
if absolutetime is provided, returns the hs.eventtap.event object; otherwise returns the current timestamp for the event.
| | Notes |
Synthesized events have a timestamp of 0 by default.
The timestamp, if specified, is expressed as an integer representing the number of nanoseconds since the system was last booted. See hs.timer.absoluteTime.
This field appears to be informational only and is not required when crafting your own events with this module.
|

Hammerspoon API - Previous

eventtap

Next - Hammerspoon API

expose

Last modified 6mo ago

API Overview

API Documentation

Constants

​properties​

​rawFlagMasks​

​types​

Functions

​newKeyEventSequence​

Constructors

​copy​

​newEvent​

​newEventFromData​

​newGesture​

​newKeyEvent​

​newMouseEvent​

​newScrollEvent​

​newSystemKeyEvent​

Methods

​asData​

​getButtonState​

​getCharacters​

​getFlags​

​getKeyCode​

​getProperty​

​getRawEventData​

​getTouchDetails​

​getTouches​

​getType​

​getUnicodeString​

​location​

​post​

​rawFlags​

​setFlags​

​setKeyCode​

​setProperty​

​setType​

​setUnicodeString​

​systemKey​

​timestamp​

properties

rawFlagMasks

types

newKeyEventSequence

copy

newEvent

newEventFromData

newGesture

newKeyEvent

newMouseEvent

newScrollEvent

newSystemKeyEvent

asData

getButtonState

getCharacters

getFlags

getKeyCode

getProperty

getRawEventData

getTouchDetails

getTouches

getType

getUnicodeString

location

post

rawFlags

setFlags

setKeyCode

setProperty

setType

setUnicodeString

systemKey

timestamp