README.md

betterglobekey

Make macOS Globe key great again!

Ask a Question • Report a Bug • Request a Feature

About the Project

macOS features a brilliant idea for the way to switch your keyboard's input source—the Globe key. While the idea is brilliant in design, in practice, however, the key is coded in a very intrusive and impractical way, which might prevent some users—especially those who tend to switch their input source often—from enjoying their overall user experience.

This utility completely reworks the way the Globe key functions and provides users with an improved overall user experience, and I sincerely hope that one day Apple is going to make it this way out-of-box.

(back to top)

Getting Started

The utility enhances the functionality of the Globe key by introducing two distinct modes of operation and starting from the currently active input source:

1. Single Press Mode

   Single press mode is activated when the Globe key is pressed once.

   In this mode, the utility cycles through a collection of input sources. Each press of the Globe key switches to the next input source within the current collection.

   The collections of input sources are defined in the configuration under collections, an ordered list of named collections. For example:

   collections:
     - name: foo
       sources:
         - com.apple.keylayout.US
         - com.apple.keylayout.Russian
     - name: bar
       sources:
         - com.apple.keylayout.Finnish
         - com.apple.keylayout.Ukrainian-PC
         - com.apple.inputmethod.Kotoeri.RomajiTyping.Japanese
   

   Upon initialization, the utility determines the current active input source and starts from that particular source within its respective collection.

2. Double Press Mode

   Double press mode is activated when the Globe key is double-pressed.

   In this mode, the utility switches between different collections of input sources. Each double press of the Globe key cycles to the next collection in the configuration.

   The maximum time interval between the first and second press that is considered a double press can be configured in the double_press.maximum_delay property. This delay is specified as a Go duration, e.g. 250ms.

Hold Shift while pressing the Globe key to go back: a single press returns to the previously used input source (toggling between the two most recent), and a double press switches to the previous collection.

On each change, an on-screen HUD briefly shows the new input source with its collection name. It is enabled by default; set hud.enabled: false in the configuration to turn it off. The configuration is reloaded automatically when the file changes, so edits take effect without restarting the service.

betterglobekey requires macOS Accessibility permission to observe the Globe key, and works best with the Globe key set to "No Action" (System Settings › Keyboard) so macOS does not switch the input source as well. Run betterglobekey doctor to check your setup.

These enhancements aim to provide a more versatile and user-friendly experience for managing multiple input sources, especially for users who frequently switch between different languages or keyboard layouts.

The utility also provides helper commands: betterglobekey list (available input sources, with names), betterglobekey current, betterglobekey doctor (diagnose configuration and permissions), and betterglobekey edit (open the configuration file). See the documentation for more information on how to set up and configure the utility.

Prefer a graphical interface? An optional companion app lets you edit your configuration—behavior, collections, and logging—without touching the YAML file, applying changes to the running service instantly.

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create, so any contributions you make are greatly appreciated.

If you would like to contribute, please make sure to take a look at this guideline beforehand.

Please see our security policy to report any possible vulnerabilities or serious issues.

(back to top)

License

Distributed under the MIT License. See LICENSE.md for more information.

N.B. This project explicitly does not require its contributors to sign a Contributor License Agreement nor does it possess one.

(back to top)