Hooky : Tiny And Useful Open Source OS X Utility

Hooky is a small Mac OS X application that helps you use OS X shortcuts/hotkeys more conveniently.

Posted by Suewon Bahng on March 30, 2016

Why did I develop Hooky?

Hooky is a small Mac OS X application that may help you make use of OS X shortcuts/hotkeys in a more effective manner. (It’s open source and free)

If you are a Linux user, you might be aware that you can paste arbitrarily selected text by clicking mouse middle button. Some users might think that functionality is useless, but it looks really convenient to me. I had been using Linux Mint for quite a time, and came back to OS X, then I missed that functionality so much. I searched the web if I could find any way to use the similar feature in OS X. OS X doesn’t support any of similar features. But BetterTouchTool could let me mimic the functionality on the OS (not same though), and I was happy for a while until the tool became a commercial app.

BetterTouchTool is quite an excellent app, but for me I used to use a very small bit of it. The tool’s main feature is enhancing usability around devices such as a trackpad or magic mouse that I don’t own. I was using it for the sole purpose of emulating middle click paste similar to that of Linux. Unfortunately, the tool was quite expensive for me to purchase it only for that functionality. I gave up buying it. ( Not every Mac user is rich :-( )

In the mean while, I’d been quite interested in OS X Cocoa programming, but no experience at all. So I decided to make an app to fulfill my own requirement while challenging the unfamiliar world of OS X application development.

What does Hooky do?

Hooky is a small status bar (or menu bar) application. It sits on the menu bar area at the top of the screen and waits for any of UI events specified by you. When it detects any of those UI events, it invokes an existing keyboard shortcut (also specified by you) for you.

For instance, to emulate middle click paste of Linux systems, Hooky waits for any of middle click events and once it detects one, then it fires keyboard events equivalent to pushing ⌘V.

Events to detect such as Middle Button Click are referred to as Proxy Events in Hooky. Also the shortcuts to invoke such as ⌘V are referred to as Target Shortcuts.

Hooky accepts many pair of “Proxy Events/Target Shortcuts” from users. Users can create, edit, delete, disable/enable them via the following UI.

hooky-screenshot

Proxy Events

Hooky offers two types of Proxy Events.

  • Mouse Click Events
    • Long press, Single/Double/Triple click for any of left, right, middle buttons
    • One or more of Modifier Keys (⌘⌥⇧⌃) may be involved.
    • Note that long press needs you to release the mouse button to finally invoke the target shortcuts. (In other words, just holding down the button won’t signal anything.)
  • Multiple Keystrokes on Modifier Keys (MKM events)
    • Only works for a SINGLE Modifier Key (⌘ or ⌥ or ⇧ or ⌃)
    • Long press on the modifier keys won’t count. You should TAP on them!
    • No other regular keys or mouse buttons are involved.
    • Double/Triple/Quadruple tappings are supported
      • Note that single tap is not supported because it will cause lots of conflicts.
    • e.g., You may double tap on ⌥ to switch applications instead of pressing ⌘Tab.

It won’t make sense at all unless proxy events are easier to invoke than their target shortcuts. That’s why proxy events are just leveraging mouse clicks or modifier keys or combinations of both only.

Target Shortcuts

BTW, is ⌘V so much hard to press? It may be controversial. For me, it’s not so difficult to quickly press it without getting my eyes off of the screen, but it’s not so much easy either. Most of time, just clicking mouse middle button is a lot easier, especially when my hand is holding the mouse. ( even more handy when another hand is grabbing a cup or glass :-) )

Of course, when both of my hands are on the keyboard, ⌘V is a lot faster. Both approaches are effective alike. Hooky won’t shadow the target shortcuts so you can use them whenever you think they would be faster to invoke.

Unlike ⌘V, other shortcuts demand many more fingers and they are harder to push and harder to remember. Hooky might be a good tool to invoke those complicated shortcuts with more simpler motions.

Even not so complicated shortcuts such as ⌘Tab are (arguably) unfriendly to the muscle of your hand. At least for me, just tapping on the ⌃ key 2 ~ 3 times feels better than elongating my fingers to push ⌘Tab.

How to install/use

  1. Download the latest .dmg file from here.
  2. Double click the .dmg file and drag the .app file inside it into your /Applications directory.
  3. Open Spotlight and type Hooky.
  4. An icon that looks like a hook will appear on the menu bar.
  5. Clicking on that icon will bring up the window where you can register your “proxy event/target shortcut” pairs.

How to manage “Proxy Event/Target Shortcut” pairs

Let me explain how you can use Hooky UI.

hooky-screenshot

  1. Pushing the button will make the edit box slide in.
    • With the edit box, you can set up a proxy event and target shortcut.
    • The edit box is the area surrounded by the blue dashed box
  2. Pushing the button will save your setup.
  3. Pushing the button will disable all the pairs.
    • Pushing the same button will enable the pairs again.
  4. Quit Hooky.
  5. Specify type of click or tap for the proxy event being edited.
    • For mouse click events, select either of Click/Double Click/Triple Click/Long Press
    • For MKM (Multiple Keystrokes on Modifier Keys) events, select either of Double Tap/Triple Tap/Quadruple Tap
  6. Specify type of mouse button for the proxy event being edited
    • Select either of NONE/MOUSE LEFT/MOUSE RIGHT/MOUSE MIDDLE
    • If NONE is selected, you can specify an MKM event.
    • Note that you can select a single modifier key only for MKK events.
  7. Specify the target shortcut.
    • Just press the keyboard shortcut you’d like to invoke via the proxy event.
    • [ KEY BY KEY MODE (IMPORTANT) ] This is a tricky part. This text field UI can’t detect global shortcuts because of an inherent limitation of Hooky. (See Limitations section below)
      • For example, If you try to input ⌘Space, only Spotlight shows up and nothing else.
      • In this case, press Space first, and then press ⌘. (Separately!)
      • This mode is referred to as Key By Key mode.
      • By pushing a regular key part (e.g., Space) of the shortcut first, the UI will switch to Key By Key mode automatically.
      • You will easily notice this mode because the background color of the text field suddenly changes.
      • After the regular key inserted, push the remaining modifier key part (e.g., ⌘)
      • Then, press Return to finish the Key By Key mode.
  8. Pushing the button will let you edit the corresponding pair.
  9. Pushing the button will let you delete the corresponding pair.
  10. Unchecking the checkbox will let you disable the corresponding pair.
    • You can reenable it by checking the same checkbox.

Note For Uninstallation:
Hooky will save your settings ~/.hooky folder.
This folder will be created when you install the app and it just contains a simple text file.
Delete the folder if you find it unnecessary when uninstalling Hooky.
The behavior for saving user settings is subject to change.

Limitations

Hooky doesn’t require any of higher privileges or registration procedures. But this imposes some limitations.

Hooky might not detect any of events being used by higher privileged applications (including apps permitted to use Accessibility API)

Applications like BetterTouchTool probably make use of low level APIs which need user permission. Those applications can do a lot more than Hooky can do and if they occupy UI events that Hooky has interest in, Hooky might not have a chance of detecting those events.

Also Hooky can’t modify existing behaviors of proxy events. This will cause problems when you want to use mouse left/right clicks as proxy events. Even though Hooky offers UI to let you register left/right clicks as valid proxy events, registering them is not recommended. (except a few, e.g., right double click) They can be only used when you are sure that they won’t conflict with other applications or existing OS behaviors.

Mouse middle click could be safely used as proxy events in most of cases. Note that you will have enough slots with middle click only. You have 4 types of mouse button clicks (Long press, single/double/triple click). And each click can be modified with 4 modifier keys (⌘⌥⇧⌃) and the number of USABLE modifier combinations is 10. (Total combinations are 15. However, pushing 3 or 4 keys together is against Hooky’s goal.) The total number of proxy events available with middle button only is up to 40 (= 4 x 10). In addition to that, the total number of MKM proxy events is 12 (= 3 x 4, 3 types of tapping and 4 modifier keys). So you have the total of 52 free slots without needing left/right buttons and I think that is more than enough.

Another limitation is that Hooky can’t detect regular key strokes. (A regular key means non-modifier keys such as alphanumeric keys or other special keys such as Return, Escape, F1, and so on.) The API that currently Hooky is using has such limitation imposed by Apple. MKM proxy events are detected when you tap on modifier keys in multiple times, but when you push a regular key by accident and the timing is really good, an unexpected behavior might happen.

Let’s say, while tapping on ⌘ modifier key twice, which has been assigned for zooming up screen (⌥⌘=) by you, if you press the ‘H’ key accidentally or intentionally, (as an unexpected side effect) your front app will become hidden (⌘H does that by default as you know). And then your screen will be zoomed up as an expected behavior.

But tapping on ⌘ key only twice is so easy and simple task. I guess the case like the above will rarely happen in reality.

Tips

Let me share with you some of useful pairs.

  • Mouse Middle Click - ⌘V (Paste from clipboard)
  • Mouse Right Double Click - ⌘C (Copy to clipboard)
  • Mouse Middle Long Press - ⌘` (Switch window of same application)
  • ⌃ Double Tap - ⌥⌘8 (Zoom in/out screen)
  • ⌃ Triple Tap - ⌘⇥ (Switch application)

Your configuration may depend on what you do everyday. For instance, if you need to take a screenshot frequently, you can assign middle double click as a proxy event to the target shortcut such as ⇧⌘3.

If you know what the target action is, but no keyboard shortcut is assigned yet, go to System Preferences > Keyboard > Shortcuts tab > select App Shortcuts from the left panel > add whatever shortcut you like.

Also note that you can quickly access Hooky’s UI all the time because it sits on the menu bar area where is always visible unless you enter a full screen mode. Disable each of pair or all the pairs when some conflicts occur and you think Hooky is in your way somehow. Once the conflicting situation is gone, you can easily revive disabled settings.

Hooky distinguishes which is a single click, double click, long press based on a configurable system setting. Go to _System Preferences > Mouse > Double-Click speed and adjust the slider as it suits you best. If you modify the double click speed faster, you need to double click that much faster in order for Hooky to identify that as a legitimate double click event.

That’s it.

Please, try Hooky if you find it useful. I’ll welcome any suggestion or bug report.