Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/AlfredoSequeida/hints
Hints lets you navigate GUI applications in Linux without your mouse by displaying "hints" you can type on your keyboard to interact with GUI elements.
https://github.com/AlfredoSequeida/hints
linux vim vimium wayland x11
Last synced: 11 days ago
JSON representation
Hints lets you navigate GUI applications in Linux without your mouse by displaying "hints" you can type on your keyboard to interact with GUI elements.
- Host: GitHub
- URL: https://github.com/AlfredoSequeida/hints
- Owner: AlfredoSequeida
- Created: 2024-10-30T03:12:45.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2024-12-27T05:09:50.000Z (15 days ago)
- Last Synced: 2024-12-27T06:18:04.856Z (15 days ago)
- Topics: linux, vim, vimium, wayland, x11
- Language: Python
- Homepage:
- Size: 120 KB
- Stars: 4
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
Awesome Lists containing this project
- my-awesome-github-stars - AlfredoSequeida/hints - Hints lets you navigate GUI applications in Linux without your mouse by displaying "hints" you can type on your keyboard to interact with GUI elements. (Python)
README
# 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)
- 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
Note: Currently hints only works on Linux X11.
1. You will need to have some sort of [compositing](https://wiki.archlinux.org/title/Xorg#Composite) 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
```
Note: If you are seeing hints all over the place instead of right on top of elements please read the [backends section in the wiki configuration guide](https://github.com/AlfredoSequeida/hints/wiki/Configuration-guide#backends) to understand why. This might mean that you have not enabled accessibility, there is something else you need to do for the application you are drawing hints for, or that the current application does not support the atspi backend.
3. Install hints:
Below you will find installation instructions for some popular linux distros bases. The setup is as follows:
- Install the python/system dependencies (including [pipx](https://pipx.pypa.io/stable/installation/)).
- Setup pipx.
- Use pipx to install hints.
Ubuntu
```
sudo apt update && \
sudo apt install git libgirepository1.0-dev gcc libcairo2-dev pkg-config python3-dev gir1.2-gtk-4.0 pipx && \
pipx ensurepath && \
pipx install git+https://github.com/AlfredoSequeida/hints.git
```
Fedora
```
sudo dnf install git gcc gobject-introspection-devel cairo-gobject-devel pkg-config python3-devel gtk4 pipx && \
pipx ensurepath && \
pipx install git+https://github.com/AlfredoSequeida/hints.git
```
Arch
```
sudo pacman -Sy && \
sudo pacman -S git python cairo pkgconf gobject-introspection gtk4 libwnck3 python-pipx && \
pipx ensurepath && \
pipx install git+https://github.com/AlfredoSequeida/hints.git
```
Finally, source your shell config or restart your terminal.
## Setup
At this point, hints should be installed, you can verify this by running `hints` in your shell. You will want to bind a keyboard shortcut to `hints` so you don't have to keep typing in a command to open it. This will depend on your OS/ window manager / desktop environment.
Here is an example of a binding on i3 by editing `.conf/i3/config`:
```
bindsym $mod+i exec hints
```
This will bind mod + i to launch hints. To stop showing hints (quit hints), press the Esc key on your keyboard.
Hints also has a scroll mode to scroll, which can also be bound to a key combination. For example:
```
bindsym $mod+y exec hints --mode scroll
```
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](https://github.com/AlfredoSequeida/hints/wiki/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](https://github.com/AlfredoSequeida/hints/wiki).
# Contributing
The easiest ways to contribute are to:
- [Become a sponsor](https://github.com/sponsors/AlfredoSequeida). Hints is a passion project that I really wanted for myself and I am working on it on 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](https://github.com/AlfredoSequeida/hints/issues/new). 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](https://docs.python.org/3/library/venv.html#how-venvs-work) 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 on Xorg and you're trapped: switch to a virtual terminal with e.g. `Ctrl+Alt+F2`, login, and run `killall hints`