Repository: jasonrudolph/ControlEscape.spoon Branch: main Commit: cc5749931afe Files: 8 Total size: 12.0 KB Directory structure: gitextract_5s8fb70x/ ├── .gitignore ├── Brewfile ├── LICENSE ├── README.md ├── docs.json ├── init.lua └── script/ ├── generate-docs └── setup ================================================ FILE CONTENTS ================================================ ================================================ FILE: .gitignore ================================================ Brewfile.lock.json ================================================ FILE: Brewfile ================================================ cask 'hammerspoon' ================================================ FILE: LICENSE ================================================ MIT License Copyright (c) 2017 Jason Rudolph Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ================================================ FILE: README.md ================================================ # ControlEscape.spoon Supercharge your control key. Tap it for escape. Hold it for control. ### A more useful control key As Steve Losh points out in his [Modern Space Cadet](http://stevelosh.com/blog/2012/10/a-modern-space-cadet/#control-escape) post, there are "keys you hold down to change how other keys behave, but that (usually) don’t do anything if you use them on their own" (e.g., control), and there are "keys that you press and release but don’t want to 'repeat' as you hold them" (e.g., escape). "There are two [distinctly] different ways to use [these keys] and they’re each only useful in one of those ways. This means that we can *combine* them onto a single key without losing any useful functionality!" With that in mind, we can teach the control key to pull double duty: - If control is pressed and released in isolation, we can interpret it as escape - If control is held down and used in combination with another key, then we can let it provide the normal control key behavior ### Goes great with Touch Bar If you've got one of those fancy new Touch Bar Macs, you might find yourself longing for the good ol' days of a tactile escape key. Look no further. 😅 ### Optional: A more useful caps lock key What's more useful than a "more useful control key?" A more useful *and more-easily reachable* control key, of course. By repurposing the anachronistic caps lock key, we can skip the acrobatics needed to reach the physical control key. We can use caps lock to give us control and escape right on the home row. Say goodbye to [Emacs pinky](http://wiki.c2.com/?EmacsPinky). 👋 ## Dependencies This functionality is developed and tested with the following dependencies: - macOS Sierra 10.12 - [Hammerspoon 0.9.54][hammerspoon] ## Installation #### Just the basics ```sh mkdir -p ~/.hammerspoon/Spoons git clone https://github.com/jasonrudolph/ControlEscape.spoon.git ~/.hammerspoon/Spoons/ControlEscape.spoon cd ~/.hammerspoon/Spoons/ControlEscape.spoon script/setup ``` #### Optional: You're just a few seconds away from a [more useful caps lock key](#optional-a-more-useful-caps-lock-key) With one more bit of setup, you'll be able to hold caps lock for control, and tap caps lock for escape: Open *System Preferences*, navigate to *Keyboard > Modifier Keys*, and set the caps lock key to control. [[screenshot]](https://user-images.githubusercontent.com/2988/27111039-7f620442-507b-11e7-9bcf-93d46e14af13.png) Now you're ready to rock. 🤘 ## Where can I get this code as a Spoon? If you prefer to roll your own Hammerspoon config, this code is also available as a [Spoon](https://github.com/Hammerspoon/hammerspoon/blob/0.9.54/SPOONS.md#how-do-i-install-a-spoon). Just look for `ControlEscape.spoon.zip` included with the [latest release](https://github.com/jasonrudolph/ControlEscape.spoon/releases/latest). ## Shout-outs Shout-out to [@arbelt](https://github.com/arbelt) and [@jasoncodes](https://github.com/jasoncodes) for the original implementation of this functionality. ⚡️🍻🌟 This code is an adaptation of their work: - https://gist.github.com/arbelt/b91e1f38a0880afb316dd5b5732759f1 - https://github.com/jasoncodes/dotfiles/blob/ac9f3ac/hammerspoon/control_escape.lua ## You might also like... Still reading? Dude, you're pretty serious about your keyboard. :neckbeard: Lucky for you, there's more where this came from. Check out [jasonrudolph/keyboard](https://github.com/jasonrudolph/keyboard#features) for even more fun. ⌨🤓 [hammerspoon]: http://www.hammerspoon.org ================================================ FILE: docs.json ================================================ [ { "Constant" : [ ], "submodules" : [ ], "Function" : [ ], "Variable" : [ ], "stripped_doc" : [ ], "type" : "Module", "Deprecated" : [ ], "desc" : "Make the `control` key more useful...", "Constructor" : [ ], "items" : [ { "def" : "ControlEscape:start()", "name" : "start", "doc" : "Start sending `escape` when `control` is pressed and released in isolation", "stripped_doc" : [ "Start sending `escape` when `control` is pressed and released in isolation" ], "notes" : [ ], "signature" : "ControlEscape:start()", "type" : "Method", "returns" : [ ], "desc" : "Start sending `escape` when `control` is pressed and released in isolation", "parameters" : [ ] }, { "def" : "ControlEscape:stop()", "name" : "stop", "doc" : "Stop sending `escape` when `control` is pressed and released in isolation", "stripped_doc" : [ "Stop sending `escape` when `control` is pressed and released in isolation" ], "notes" : [ ], "signature" : "ControlEscape:stop()", "type" : "Method", "returns" : [ ], "desc" : "Stop sending `escape` when `control` is pressed and released in isolation", "parameters" : [ ] } ], "Method" : [ { "def" : "ControlEscape:start()", "name" : "start", "doc" : "Start sending `escape` when `control` is pressed and released in isolation", "stripped_doc" : [ "Start sending `escape` when `control` is pressed and released in isolation" ], "notes" : [ ], "signature" : "ControlEscape:start()", "type" : "Method", "returns" : [ ], "desc" : "Start sending `escape` when `control` is pressed and released in isolation", "parameters" : [ ] }, { "def" : "ControlEscape:stop()", "name" : "stop", "doc" : "Stop sending `escape` when `control` is pressed and released in isolation", "stripped_doc" : [ "Stop sending `escape` when `control` is pressed and released in isolation" ], "notes" : [ ], "signature" : "ControlEscape:stop()", "type" : "Method", "returns" : [ ], "desc" : "Stop sending `escape` when `control` is pressed and released in isolation", "parameters" : [ ] } ], "Command" : [ ], "doc" : "Make the `control` key more useful: If the `control` key is tapped, treat it\nas the `escape` key. If the `control` key is held down and used in\ncombination with another key, then provide the normal `control` key\nbehavior.", "Field" : [ ], "name" : "ControlEscape" } ] ================================================ FILE: init.lua ================================================ --- === ControlEscape === --- --- Make the `control` key more useful: If the `control` key is tapped, treat it --- as the `escape` key. If the `control` key is held down and used in --- combination with another key, then provide the normal `control` key --- behavior. local obj={} obj.__index = obj -- Metadata obj.name = 'ControlEscape' obj.version = '0.1' obj.author = 'Jason Rudolph ' obj.homepage = 'https://github.com/jasonrudolph/ControlEscape.spoon' obj.license = 'MIT - https://opensource.org/licenses/MIT' function obj:init() self.sendEscape = false self.lastModifiers = {} -- If `control` is held for this long, don't send `escape` local CANCEL_DELAY_SECONDS = 0.150 self.controlKeyTimer = hs.timer.delayed.new(CANCEL_DELAY_SECONDS, function() self.sendEscape = false end) -- Create an eventtap to run each time the modifier keys change (i.e., each -- time a key like control, shift, option, or command is pressed or released) self.controlTap = hs.eventtap.new({hs.eventtap.event.types.flagsChanged}, function(event) local newModifiers = event:getFlags() -- If this change to the modifier keys does not invole a *change* to the -- up/down state of the `control` key (i.e., it was up before and it's -- still up, or it was down before and it's still down), then don't take -- any action. if self.lastModifiers['ctrl'] == newModifiers['ctrl'] then return false end -- If the `control` key has changed to the down state, then start the -- timer. If the `control` key changes to the up state before the timer -- expires, then send `escape`. if not self.lastModifiers['ctrl'] then self.lastModifiers = newModifiers self.sendEscape = true self.controlKeyTimer:start() else if self.sendEscape then hs.eventtap.keyStroke({}, 'escape', 1) end self.lastModifiers = newModifiers self.controlKeyTimer:stop() end return false end ) -- Create an eventtap to run each time a normal key (i.e., a non-modifier key) -- enters the down state. We only want to send `escape` if `control` is -- pressed and released in isolation. If `control` is pressed in combination -- with any other key, we don't want to send `escape`. self.keyDownEventTap = hs.eventtap.new({hs.eventtap.event.types.keyDown}, function(event) self.sendEscape = false return false end ) end --- ControlEscape:start() --- Method --- Start sending `escape` when `control` is pressed and released in isolation function obj:start() self.controlTap:start() self.keyDownEventTap:start() end --- ControlEscape:stop() --- Method --- Stop sending `escape` when `control` is pressed and released in isolation function obj:stop() -- Stop monitoring keystrokes self.controlTap:stop() self.keyDownEventTap:stop() -- Reset state self.controlKeyTimer:stop() self.sendEscape = false self.lastModifiers = {} end return obj ================================================ FILE: script/generate-docs ================================================ #!/bin/sh # See https://github.com/Hammerspoon/hammerspoon/blob/0.9.54/SPOONS.md#generating hs -c "hs.doc.builder.genJSON(\"$(pwd)\")" | grep -v "^--" > docs.json ================================================ FILE: script/setup ================================================ #!/bin/sh MINIMUM_HAMMERSPOON_VERSION=0.9.54 set -e command -v brew > /dev/null || (echo "Homebrew is required: http://brew.sh/" && exit 1) brew bundle check || brew bundle # Prepare custom settings for Hammerspoon mkdir -p ~/.hammerspoon if ! grep -sq "ControlEscape" ~/.hammerspoon/init.lua; then echo "hs.loadSpoon('ControlEscape'):start() -- Load Hammerspoon bits from https://github.com/jasonrudolph/ControlEscape.spoon" >> ~/.hammerspoon/init.lua fi # If Hammerspoon is already running, kill it so we can pick up the new config # when opening Hammerspoon below killall Hammerspoon || true # Open Hammerspoon open /Applications/Hammerspoon.app # Enable Hammerspoon at startup osascript -e 'tell application "System Events" to make login item at end with properties {path:"/Applications/Hammerspoon.app", hidden:true}' > /dev/null # Output Hammerspoon version CURRENT_VERSION=$(brew info hammerspoon | grep "hammerspoon:") echo echo "Hammerspoon version $MINIMUM_HAMMERSPOON_VERSION or greater required. Actual installed version: $CURRENT_VERSION" echo echo "Done! Be sure to verify your version of Hammerspoon above. If your version is older than $MINIMUM_HAMMERSPOON_VERSION, run 'brew update && script/setup' to install a compatible version."