OverKeys

A customizable, open-source on-screen keyboard visualizer for alternative layouts!

Download Release · Report Bug · Request Feature

Table of Contents

1. About The Project
2. Features
3. Getting Started
4. Configuration
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

OverKeysDemoLayers.mp4

OverKeys is an open-source on-screen keyboard designed for users to practice alternative keyboard layouts, such as Canary, Colemak, Dvorak, and many more. Built in Flutter, it allows full customizability, making it perfect for users learning or working with non-traditional layouts.

This project was initially developed to help with system-wide practice of the Canary layout, but has since evolved to support multiple layouts and customization options.

Samples

Aurora (On Dark Background)	Aurora (On Light Background)
Custom (On Dark Background)	Custom (On Light Background)
Catppuccin	Red Samurai
Split Matrix Style	Matrix Style

_{Note: The themes are not provided by default and were instead manually configured. Colors were based on the MonkeyType themes of the same name.}

(back to top)

Features

• Multi-layout support: The following layouts are currently natively supported.
  Layouts

  • QWERTY
  • Colemak
  • Dvorak
  • Canaria
  • Canary
  • Canary Matrix
  • Colemak DH
  • Colemak DH Matrix
  • Engram
  • Focal
  • Gallium (Col-Stag)
  • Gallium V2 (Row-Stag)
  • Graphite
  • Halmak
  • Hands Down
  • NERPS
  • Norman
  • Sturdy
  • Sturdy Angle (Staggered)
  • Workman
• Customizable styles: Change colors, fonts, sizes, offsets, and key styles to fit your preference.
• Always on top: Keep the keyboard on top of all windows for constant access.
• Auto-hide: The keyboard hides automatically when not in use.
• Keymap layouts: Supports keymap layouts such as staggered, matrix, and split matrix.
• Layer switching (Kanata): Connect to Kanata through TCP to dynamically display the active layer.
• User configurations: Easily add and use custom keyboard layouts through overkeys_config.json.
• Side-by-side layouts: Display alternative layouts alongside the default layout, which is useful for showing multiple languages at once. Note that key press highlighting is determined by the defaultLayout.
• Top row/Number row: Optional row above the main keyboard that can show numbers or other user-configurated keys.

(back to top)

Getting Started

Follow these instructions to set up OverKeys on your local machine.

Prerequisites

• Windows OS

Installation

1. Download the latest EXE installer.
2. Run the installer and follow the on-screen instructions.
3. Once installed, OverKeys will be available for use.

Configuration

To change the app settings, right-click the OverKeys icon in the system tray and select Preferences. A separate window will open, displaying the available settings.

Loading Your Own Layout

To load your own keyboard layout, follow these steps:

1. Access Configuration:

   • Right-click the OverKeys icon in the system tray
   • Select Preferences
   • Go to the General tab
   • Click Open Config option

2. Edit Configuration:

   • Edit the overkeys_config.json file that opens in your default text editor
   • Add your custom layouts as needed in the userLayouts section. Use the key symbols found in mappings.dart and key_code.dart as reference for key names and special characters that OverKeys recognize.
   • Set the defaultUserLayout property to specify which layout to use (can be one of your custom layouts or any supported layout)
   • Save the file
     • It is recommended to make a backup copy of overkeys_config.json, as testing has shown that it may occasionally revert to the default configuration unexpectedly

3. Apply Changes:

   • Restart OverKeys
   • Return to Preferences > General tab
   • Toggle on Use custom layout from config
   • Your custom layout should now be active

Layer Switching through Kanata TCP

Note: Since OverKeys uses Windows LLHOOK for key detection, this feature is only guaranteed to work with Kanata implementations that also use Windows LLHOOK. Integration has been tested and confirmed working with kanata_gui.exe.

Demos:

With Kanata Debug

OverKeys_Kanata_Debug.mp4

With Kanata Shortcut

OverKeys_Kanata_Shortcut.mp4

1. Access Configuration:

   • Right-click the OverKeys icon in the system tray
   • Select Preferences
   • Go to the General tab
   • Click Open Config option

2. Edit Configuration:

   • Edit the overkeys_config.json file that opens in your default text editor
   • Add your kanata layers as needed in the userLayouts section. Use the key symbols found in mappings.dart and key_code.dart as reference for key names and special characters that OverKeys recognize.
     • You may also add unsupported keys (e.g., COPY, PASTE). They would appear on the keyboard upon layer switching but won't be triggered due to not being supported (yet?)
   • Define the default layer you use in defaultUserLayout
   • Define the TCP address you want to use in kanataHost and kanataPort (defaults are 127.0.0.1 and 4039)
   • Save the file
     • It is recommended to make a backup copy of overkeys_config.json, as testing has shown that it may occasionally revert to the default configuration unexpectedly
   • Restart OverKeys

3. Kanata Configuration

   • When running Kanata, (assuming that the kanata.kbd is in the same directory as the kanata executable so no more -c flag needed) use the -p flag with the same address and port:

     kanata.exe -p ${kanataHost}:${kanataPort}

   • Tip: Create a shortcut for kanata_gui.exe and place it in the Windows Startup folder (C:\Users\%USERNAME%\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup). This allows Kanata to launch after OverKeys on system boot. Add the parameter -p 127.0.0.1:4039 (or your custom kanataHost:kanataPort) to the shortcut's target field in Properties. When your PC starts, both applications will open automatically and connect.

4. Apply Changes:

   • Return to Preferences > General tab
   • Toggle on Connect to Kanata
   • OverKeys should now be connected to Kanata
   • When you switch to any layer other than your defaultUserLayout, OverKeys will temporarily disable its auto-hide feature until you return to the default layer

Note: If you've previously enabled "Connect to Kanata" in a session, OverKeys will automatically attempt to connect the next time it opens. It's recommended to open OverKeys first, then launch Kanata, to avoid detecting double key presses (as OverKeys would otherwise detect both the defsrc layer key and the injected kanata key press).

(back to top)

Contributing

Contributions are what make the open-source community such an amazing place to learn and collaborate. Any contributions to OverKeys are greatly appreciated.

1. Fork the Project.
2. Create your Feature Branch (git checkout -b feat/amazing-feature).
3. Commit your Changes (git commit -m 'feat: add some amazing feature').
4. Push to the Branch (git push origin feat/amazing-feature).
5. Open a Pull Request.

Building

1. Install Flutter:

   • Follow the official Flutter installation guide to set up Flutter on your machine.

2. Install Git:

   • Download and install using the installer from the Git website.

   • Alternatively, if you have winget installed, you can use the following command in your terminal:

     winget install --id Git.Git -e --source winget

3. Clone the Repository:

   • Open a terminal and navigate to the folder where you want to clone the repository using the cd command. For example:

     cd path/to/your/folder

   • With Git installed, use the following command in your terminal:

     git clone https://github.com/conventoangelo/OverKeys.git

4. Build the Project Locally:

   • Open a terminal and navigate to the root directory of the project.

   • Run the following command to get the Flutter dependencies:

     flutter pub get

   • Run the app with the terminal open:

     flutter run -d windows

   • Alternatively, build the project by running:

     flutter build windows

   • Once the build is complete, you can find the executable file in ..\OverKeys\build\windows\x64\runner\Release.

(back to top)

License

Distributed under the GPL-3.0 License. See LICENSE file for more information.

(back to top)

Contact

Angelo Convento

GitHub: conventoangelo
Email: [email protected]

Project Link: https://github.com/conventoangelo/OverKeys

(back to top)

Acknowledgments

• win32 - Access common Win32 APIs directly from Dart using FFI — no C required!
• leanflutter.dev
  • window_manager - A plugin that allows Flutter desktop apps to resizing and repositioning the window.
  • tray_manager - A plugin that allows Flutter desktop apps to defines system tray.
  • launch_at_startup - A plugin that allows Flutter desktop apps to Auto launch on startup / login.
• desktop_multi_window - A flutter plugin that create and manager multi window in desktop.
• flex_color_picker - A highly customizable Flutter color picker.
• Best-README-Template - An awesome README template to jumpstart your projects!
• Alaine - for creating the beautiful OverKeys logo with love and care.

(back to top)