Click, scroll, and drag with your keyboard

Navigate GUIs without a mouse by typing hints in combination with modifier keys.

• click once (jk)
• click multiple times (2jk)
• right click (SHIFT + jk)
• drag (ALT + jk)
  • Note for wayland users: Due to how different wayland compositors handle overlay windows, dragging might not always work for your compositor.
• hover (CTRL + jk)
• scroll/move the mouse using vim key bindings (h,j,k,l)

Don't like the keybindings? That's ok, you can change them.

Installing

System Requirements

1. You will need to have some sort of compositing setup so that you can properly overlay hints over windows with the correct level of transparency. Otherwise, the overlay will just cover the entire screen; not allowing you to see what is under the overlay.

2. You will need to enable accessibility for your system. If you use a Desktop Environment, this might already be enabled by default. If you find that hints does not work or works for some apps and not others add the following to /etc/environment

ACCESSIBILITY_ENABLED=1
GTK_MODULES=gail:atk-bridge
OOO_FORCE_DESKTOP=gnome
GNOME_ACCESSIBILITY=1
QT_ACCESSIBILITY=1
QT_LINUX_ACCESSIBILITY_ALWAYS_ON=1

3. Install hints:

Below you will find installation instructions for some popular linux distros. The commands below assume that you're running wayland if your XDG_SESSION_TYPE variable is set to wayland. If that's the case you will install the wayland dependencies. Otherwise, the x11 dependencies will be installed. The setup is as follows:

• Install the python/system dependencies (including pipx).
• Setup pipx.
• Use pipx to install hints.

Ubuntu

Note: At the time of writing these docs, the ydotool package available for Ubuntu does not include a service, so if you want to use a service, install it from source instead

sudo apt update && \
    sudo apt install git ydotool libgirepository1.0-dev gcc libcairo2-dev pkg-config python3-dev gir1.2-gtk-4.0 pipx && \
    [ $XDG_SESSION_TYPE = "wayland" ] && sudo apt install gtk-layer-shell grim && \
    pipx ensurepath && \
    pipx install git+https://github.com/AlfredoSequeida/hints.git

Fedora

sudo dnf install git ydotool gcc gobject-introspection-devel cairo-gobject-devel pkg-config python3-devel gtk4 pipx && \
    [ $XDG_SESSION_TYPE = "wayland" ] && sudo dnf install gtk-layer-shell grim && \
    pipx ensurepath && \
    pipx install git+https://github.com/AlfredoSequeida/hints.git

Arch

sudo pacman -Sy && \
    sudo pacman -S git ydotool python cairo pkgconf gobject-introspection gtk4 python-pipx && \
    [ $XDG_SESSION_TYPE = "wayland" ] && sudo pacman -S gtk-layer-shell grim || sudo pacman -S libwnck3 && \
    pipx ensurepath && \
    pipx install git+https://github.com/AlfredoSequeida/hints.git

Finally, source your shell config or restart your terminal.

Setup

1. Follow the setup instructions for your window system here.
2. At this point, hints should be installed, you can verify this by running hints in your shell. If you still don't see any hints, the application you're testing could need a bit of extra setup. Please see the Help,-hints-doesn't-work-with-X-application page in the wiki.

Documentation

For a guide on configuring and using hints, please see the Wiki.

Contributing

The easiest ways to contribute are to:

• Become a sponsor. Hints is a passion project that I really wanted for myself and I am working on it in my spare time. I chose to make it free and open source so that others can benefit. If you find it valuable, donating is a nice way to say thanks. You can donate any amount you want.
• Report bugs. If you notice something is not working as expected or have an idea on how to make hints better, open up an issue. This helps everyone out.
• If you can code, feel free to commit some code! You can see if any issues need solutions or you can create a new feature. If you do want to create a new feature, it's a good idea to create an issue first so we can align on why this feature is needed and if it has a possibility of being merged.

Development

If you want to help develop hints, first setup your environment:

1. Create a virtual environment for the project.

python3 -m venv venv

2. Activate your virtual environment for development. This will differ based on OS/shell. See the table here for instructions.

3. Install hints as an editable package (from the repositorie's root directory):

pip install -e .

At this point, hints should be installed locally in the virtual environment, you can run hints in your shell to launch it. Any edits you make to the source code will automatically update the installation. For future development work, you can simply re-enable the virtual environment (step 2).

Development tips

• If you are making updates that impact hints, you will most likely need to test displaying hints and might find yourself executing hints but not being quick enough to switch to a window to see hints. To get around this, you can execute hints with a short pause in your shell: sleep 0.5; hints. This way you can have time to switch to a window and see any errors / logs in your shell.
• If hints is consuming all keyboard inputs and you're trapped: switch to a virtual terminal with e.g. CTRL+ALT+F2, login, and run killall hints. You can then exit with exit and switch back to the the previous session (most likely 1): CTRL+ALT+F1