Distinguish between left and right modifiers

[harsilspatel]

I wanted to use right modifiers for binding my hotkeys but I realised the existing hotkey extension doesn't support it.

So, I used eventtap extension to listen for keyDown events and came up with this:

-- from skhd
local MODIFIER_FLAGS = {
  lalt = 0x00000020,
  ralt = 0x00000040,
  lshift = 0x00000002,
  rshift = 0x00000004,
  lcmd = 0x00000008,
  rcmd = 0x00000010,
  lctrl = 0x00000001,
  rctrl = 0x00002000
}

local bindings = {}

--- Parameters:
---  * modifierFlags - flags OR'ed from eventtap data for e.g 1573192
--- Returns:
---  * An array-like table of modifiers for e.g {'lcmd', 'ralt'}
local function getModifierNames(modifierFlags)
  local names = {}
  for keyname, flag in pairs(MODIFIER_FLAGS) do
    if (modifierFlags & tonumber(flag) > 0) then table.insert(names, keyname) end
  end
  return names
end

local function addModifierToAllCombinations(combinations, modifierName)
  return hs.fnutils.imap(combinations, function(combination)
    table.insert(combination, modifierName) -- mutates combination i.e. doesn't return anything
    return combination
  end)
end

--- Parameters:
---  * hotkeyModifierNames - modifiers to bind hotkey for e.g {'cmd', 'alt'}
--- Returns:
---  * A table of tables for all possible combinations of those modifiers, for given input result will be:
---  {{'lcmd', 'lalt'}, {'lcmd', 'ralt'}, {'rcmd', 'lalt'}, {'rcmd', 'ralt'}}
local function getAllModifierCombinations(hotkeyModifierNames)
  local combinations = {{}}

  for _, modifierName in ipairs(hotkeyModifierNames) do
    local leftModifier = 'l' .. modifierName
    local rightModifier = 'r' .. modifierName
    local isCommonModifier = MODIFIER_FLAGS[leftModifier] and MODIFIER_FLAGS[rightModifier]
    if isCommonModifier then
      local combinationsClone = hs.fnutils.imap(combinations,
        function(combination) return {table.unpack(combination)} end)
      combinationsClone = addModifierToAllCombinations(combinationsClone, leftModifier)

      combinations = addModifierToAllCombinations(combinations, rightModifier)
      combinations = hs.fnutils.concat(combinations, combinationsClone)
    else
      combinations = addModifierToAllCombinations(combinations, modifierName)
    end

  end

  return combinations
end

--- Parameters:
---  * mods - A table or a string containing the keyboard modifiers required,
---    which should be zero or more of the following:
---    * "cmd", "lcmd" or "rcmd"
---    * "ctrl", "lctrl" or "rctrl"
---    * "alt", "lalt" or "ralt"
---    * "shift", "lshift" or "rshift"
---  * key - A string containing the name of a keyboard key
--- Returns:
---  Returns a string of concetanated modifiers and key for e.g `lcmd.ralt.h`
local function generateHotkeyHash(modifiers, key)
  -- sorting combinations so "hash" is deterministic
  table.sort(modifiers)
  table.insert(modifiers, key)
  return table.concat(modifiers, '.')
end

local keyDownEventTap = hs.eventtap.new({hs.eventtap.event.types.keyDown}, function(event)
  local eventData = event:getRawEventData()['NSEventData']

  local keyCode = eventData.keyCode
  local keyName = hs.keycodes.map[keyCode]

  local modifierFlags = eventData.modifierFlags
  local eventModifiers = getModifierNames(modifierFlags)

  local eventHotkeyHash = generateHotkeyHash(eventModifiers, keyName)

  if #eventModifiers == 0 or (#eventModifiers == 1 and hs.fnutils.contains({'lcmd', 'rcmd'}, eventModifiers[1])) then
    return
  elseif (bindings[eventHotkeyHash]) then
    local pressedFn = bindings[eventHotkeyHash]
    pressedFn(eventData)
    return true
  end
end)

local module = {}

--- Parameters:
---  * mods - A table or a string containing the keyboard modifiers required,
---    which should be zero or more of the following:
---    * "cmd", "lcmd" or "rcmd"
---    * "ctrl", "lctrl" or "rctrl"
---    * "alt", "lalt" or "ralt"
---    * "shift", "lshift" or "rshift"
---  * key - A string containing the name of a keyboard key
---  * pressedfn - A function that will be called when the hotkey has been pressed
--- Returns:
---  * None
function module.bind(mods, key, pressedFn)
  local combinations = getAllModifierCombinations(mods)
  local hotkeyHashes = hs.fnutils.imap(combinations,
    function(combination) return generateHotkeyHash(combination, key) end)

  hs.fnutils.ieach(hotkeyHashes, function(hotkeyHash) bindings[hotkeyHash] = pressedFn end)

  if (not keyDownEventTap:isEnabled()) then keyDownEventTap:start() end
end

hs.hotkeyextension = module
return (module)

which can be used like so

hs.hotkeyextension.bind({'ralt'}, 'f', function() hs.application.launchOrFocus('Spotify') end)

I'm wondering if it'd be worthwhile to add to it the main repo? (I'd be more than happy to clean-up this code and do it!)

[cmsj]

I can see some benefit to adding at least the table of modifiers to hs.eventtap.event somehow. I generally try to discourage using hs.eventtap for hotkeys, simply because it's a lot of overhead vs hs.hotkey where the OS is doing the work for us in a more optimised way. However, for cases where hs.hotkey can't meet a user's needs, it's certainly great to have options in hs.eventtap!

Perhaps a good first step would be to submit it to the official Spoons repo?

[muescha]

is it possible to add the rand l modifiers to the core so there is no need for a workaround with eventtap?

[harsilspatel]

@muescha is this in reference to the MODIFIER_FLAGS table? If so, I realised they're already present in the core!

[asmagill]

The hotkey module uses legacy Carbon methods to assign and detect hotkeys. It is tried and true, doesn't suffer from spurious disabling if Hammerspoon becomes unresponsive at the wrong time, works within every application and is pretty rock solid. But, as noticed -- it does have limitations, most especially that it doesn't distinguish between right and left for modifier keys.

Using eventtap is the obvious next contender, but this suffers from (a) it's more complex, (b) may interfere with other applications doing similar things with eventtaps, and (c) can be automatically disabled by the OS if Hammerspoon becomes unresponsive at the wrong time (this is mostly mitigated by an internal check for the appropriate notification when such disabling occurs, and will then automatically re-activate the event tap, but this isn't 100% effective because even this "you're disabled" notification can be missed if Hammerspoon is really unresponsive for an extended period of time.

What I would personally do is a combination:

Create your hotkeys with hs.hotkey.new instead of hs.hotkey.bind -- this creates, but doesn't activate them.

Use eventtap to detect flag changes only; this puts less strain on Hammerspoon because it isn't having to deal with every single character press.

When the left (or right) modifier you care about is set, turn on the series of hotkeys that you want active with hotkey:enable()

When the left (or right) modifier you care about is released, turn off the hotkeys with hotkey:disable().

Something like this (minimally tested) to get started:

local hotkey   = require("hs.hotkey")
local eventtap = require("hs.eventtap")
local keycodes = require("hs.keycodes")

local alert    = require("hs.alert")

-- set up your hotkeys in this table:
local myKeys = {
    hotkey.new({ "cmd" }, "1", function() alert("1 was pressed") end),
    hotkey.new({ "cmd" }, "2", function() alert("2 was pressed") end),
    -- etc
}
local myKeysActive = false

-- this determines whether or not to enable/disable the keys
et = eventtap.new(
    { eventtap.event.types.flagsChanged },
    function(e)
        local flags = e:rawFlags()
        if flags & eventtap.event.rawFlagMasks.deviceRightCommand > 0 then
            if not myKeysActive then
                for _, v in ipairs(myKeys) do
                    v:enable()
                end
                myKeysActive = true
            end
        else
            if myKeysActive then
                for _, v in ipairs(myKeys) do
                    v:disable()
                end
                myKeysActive = false
            end
        end
    end
):start()