# KeyHint
**_Utility to display keyboard shortcuts or other hints based on the active window on
Linux._**
<p align="center"><br>
<img alt="Tests passing" src="https://github.com/dynobo/keyhint/workflows/Test/badge.svg">
<a href="https://github.com/dynobo/keyhint/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg"></a>
<a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/Code%20style-black-%23000000"></a>
<a href='https://coveralls.io/github/dynobo/keyhint'><img src='https://coveralls.io/repos/github/dynobo/keyhint/badge.svg' alt='Coverage Status' /></a>
</p>
## Prerequisites
- Python 3.11+
- GTK 4.6+ (shipped since Ubuntu 22.04) + related dev packages:
```sh
sudo apt-get install \
libgirepository1.0-dev \
libcairo2-dev \
python3-gi \
gobject-introspection \
libgtk-4-dev
```
- Wayland & Gnome: The
[Gnome Extension "Window-Calls"](https://extensions.gnome.org/extension/4724/window-calls/)
is required to auto-select the cheatsheet based on the current active application.
## Installation
- `pipx install keyhint` (recommended, requires [pipx](https://pipx.pypa.io/))
- _or_ `pip install keyhint`
## Usage
- Configure a **global hotkey** (e.g. `Ctrl + F1`) **via your system settings** to
launch `keyhint`.
- If KeyHint is launched via hotkey, it detects the current active application and shows
the appropriate hints. (This feature won't work reliably when KeyHint ist started via
Menu or Launcher.)
## CLI Options
```
Application Options:
-c, --cheatsheet=SHEET-ID Show cheatsheet with this ID on startup
-v, --verbose Verbose log output for debugging
```
## Cheatsheet Configuration
The content which KeyHint displays is configured using [`toml`](https://toml.io/en/)
configuration files.
KeyHint reads those files from two locations:
1. The [built-in directory](https://github.com/dynobo/keyhint/tree/main/keyhint/config)
1. The user directory, usually located in `~/.config/keyhint`
### How Keyhint selects the cheatsheet to show
- The cheatsheet to be displayed on startup are selected by comparing the value of
`regex_wmclass` with the wm_class of the active window and the value of `regex_title`
with the title of the active window.
- The potential cheatsheets are processed alphabetically by filename, the first file
that matches both wm_class and title are getting displayed.
- Both of `regex_` values are interpreted as **case in-sensitive regular expressions**.
- Check "Debug Info" in the application menu to get insights about the active window and
the selected cheatsheet file.
### Customize or add cheatsheets
- To **change built-in** cheatsheets, copy
[the corresponding .toml-file](https://github.com/dynobo/keyhint/tree/main/src/keyhint/config)
into the config directory. Make your changes in a text editor. As long as you don't
change the `id` it will overwrite the defaults.
- To **create new** cheatsheets, I suggest you start with
[one of the existing .toml-file](https://github.com/dynobo/keyhint/tree/main/src/keyhint/config):
- Place it in the config directory and give it a good file name.
- Change the value `id` to something unique.
- Adjust `regex_wmclass` and `regex_title` so it will be selected based on the active
window. (See [Tips](#tips))
- Add the `shortcuts` & `label` to a `section`.
- If you think your cheatsheet might be useful for others, please consider opening a
pull request or an issue!
- You can always **reset cheatsheets** to the shipped version by deleting the
corresponding `.toml` files from the config folder.
- You can **include shortcuts from other cheatsheets** by adding
`include = ["<Cheatsheet ID>"]`
### Examples
#### Hide existing cheatsheets
To hide a cheatsheet, e.g. the
[built-in](https://github.com/dynobo/keyhint/blob/main/keyhint/config/tilix.toml) one
with the ID `tilix`, create a new file `~/.config/keyhint/tilix.toml` with the content:
```toml
id = "tilix"
hidden = true
```
#### Extend existing cheatsheets
To add keybindings to an existing cheatsheet, e.g. the
[built-in](https://github.com/dynobo/keyhint/blob/main/keyhint/config/firefox.toml) one
with the ID `firefox`, create a new file `~/.config/keyhint/firefox.toml` which only
contains the ID and the additional bindings:
```toml
id = "firefox"
[section]
[section."My Personal Favorites"] # New section
"Ctrl + Shift + Tab" = "Show all Tabs"
# ...
```
#### Add new cheatsheet which never gets auto-selected
To add a new cheatsheet, which never gets automatically selected and displayed by
KeyHint, but remains accessible through KeyHint's cheatsheet dropdown, create a file
`~/.config/keyhint/my-app.toml`:
```toml
id = "my-app"
url = "url-to-my-apps-keybindings"
[match]
regex_wmclass = "a^" # Patter which never matches
regex_title = "a^"
[section]
[section.General]
"Ctrl + C" = "Copy"
# ...
```
#### Different cheatsheets for different Websites
For showing different browser-cheatsheets depending on the current website, you might
want to use a browser extension like
"[Add URL To Window Title](https://addons.mozilla.org/en-US/firefox/addon/add-url-to-window-title/)"
and configure the `[match]` section to look for the url in the title. E.g.
`~/.config/keyhint/github.toml`
```toml
id = "github.com"
[match]
regex_wmclass = "Firefox"
regex_title = ".*github\\.com.*" # URL added by browser extensions to window title
[section]
[section.Repositories]
gc = "Goto code tab"
# ...
```
## Contribute
I'm happy about any contribution! Especially I would appreciate submissions to improve
the
[shipped cheatsheets](https://github.com/dynobo/keyhint/tree/main/src/keyhint/config).
(The current set are the cheatsheets I personally use).
## Design Principles
- **Don't run as service**<br>It shouldn't consume resources in the background, even if
this leads to slightly slower start-up time.
- **No network connection**<br>Everything should run locally without any network
communication.
- **Dependencies**<br>The fewer dependencies, the better.
## Certification
Raw data
{
"_id": null,
"home_page": null,
"name": "keyhint",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "cheatsheet, helper, hints, keybindings, shortcuts",
"author": null,
"author_email": "dynobo <dynobo@mailbox.org>",
"download_url": "https://files.pythonhosted.org/packages/94/a7/62854183b14a960478edc7f70ce0836e0d6ffc332a22c6b36560bee1726f/keyhint-0.5.0.tar.gz",
"platform": null,
"description": "# KeyHint\n\n**_Utility to display keyboard shortcuts or other hints based on the active window on\nLinux._**\n\n<p align=\"center\"><br>\n<img alt=\"Tests passing\" src=\"https://github.com/dynobo/keyhint/workflows/Test/badge.svg\">\n<a href=\"https://github.com/dynobo/keyhint/blob/main/LICENSE\"><img alt=\"License: MIT\" src=\"https://img.shields.io/badge/License-MIT-blue.svg\"></a>\n<a href=\"https://github.com/psf/black\"><img alt=\"Code style: black\" src=\"https://img.shields.io/badge/Code%20style-black-%23000000\"></a>\n<a href='https://coveralls.io/github/dynobo/keyhint'><img src='https://coveralls.io/repos/github/dynobo/keyhint/badge.svg' alt='Coverage Status' /></a>\n</p>\n\n\n\n## Prerequisites\n\n- Python 3.11+\n- GTK 4.6+ (shipped since Ubuntu 22.04) + related dev packages:\n ```sh\n sudo apt-get install \\\n libgirepository1.0-dev \\\n libcairo2-dev \\\n python3-gi \\\n gobject-introspection \\\n libgtk-4-dev\n ```\n- Wayland & Gnome: The\n [Gnome Extension \"Window-Calls\"](https://extensions.gnome.org/extension/4724/window-calls/)\n is required to auto-select the cheatsheet based on the current active application.\n\n## Installation\n\n- `pipx install keyhint` (recommended, requires [pipx](https://pipx.pypa.io/))\n- _or_ `pip install keyhint`\n\n## Usage\n\n- Configure a **global hotkey** (e.g. `Ctrl + F1`) **via your system settings** to\n launch `keyhint`.\n- If KeyHint is launched via hotkey, it detects the current active application and shows\n the appropriate hints. (This feature won't work reliably when KeyHint ist started via\n Menu or Launcher.)\n\n## CLI Options\n\n```\nApplication Options:\n -c, --cheatsheet=SHEET-ID Show cheatsheet with this ID on startup\n -v, --verbose Verbose log output for debugging\n```\n\n## Cheatsheet Configuration\n\nThe content which KeyHint displays is configured using [`toml`](https://toml.io/en/)\nconfiguration files.\n\nKeyHint reads those files from two locations:\n\n1. The [built-in directory](https://github.com/dynobo/keyhint/tree/main/keyhint/config)\n1. The user directory, usually located in `~/.config/keyhint`\n\n### How Keyhint selects the cheatsheet to show\n\n- The cheatsheet to be displayed on startup are selected by comparing the value of\n `regex_wmclass` with the wm_class of the active window and the value of `regex_title`\n with the title of the active window.\n- The potential cheatsheets are processed alphabetically by filename, the first file\n that matches both wm_class and title are getting displayed.\n- Both of `regex_` values are interpreted as **case in-sensitive regular expressions**.\n- Check \"Debug Info\" in the application menu to get insights about the active window and\n the selected cheatsheet file.\n\n### Customize or add cheatsheets\n\n- To **change built-in** cheatsheets, copy\n [the corresponding .toml-file](https://github.com/dynobo/keyhint/tree/main/src/keyhint/config)\n into the config directory. Make your changes in a text editor. As long as you don't\n change the `id` it will overwrite the defaults.\n- To **create new** cheatsheets, I suggest you start with\n [one of the existing .toml-file](https://github.com/dynobo/keyhint/tree/main/src/keyhint/config):\n - Place it in the config directory and give it a good file name.\n - Change the value `id` to something unique.\n - Adjust `regex_wmclass` and `regex_title` so it will be selected based on the active\n window. (See [Tips](#tips))\n - Add the `shortcuts` & `label` to a `section`.\n - If you think your cheatsheet might be useful for others, please consider opening a\n pull request or an issue!\n- You can always **reset cheatsheets** to the shipped version by deleting the\n corresponding `.toml` files from the config folder.\n- You can **include shortcuts from other cheatsheets** by adding\n `include = [\"<Cheatsheet ID>\"]`\n\n### Examples\n\n#### Hide existing cheatsheets\n\nTo hide a cheatsheet, e.g. the\n[built-in](https://github.com/dynobo/keyhint/blob/main/keyhint/config/tilix.toml) one\nwith the ID `tilix`, create a new file `~/.config/keyhint/tilix.toml` with the content:\n\n```toml\nid = \"tilix\"\nhidden = true\n```\n\n#### Extend existing cheatsheets\n\nTo add keybindings to an existing cheatsheet, e.g. the\n[built-in](https://github.com/dynobo/keyhint/blob/main/keyhint/config/firefox.toml) one\nwith the ID `firefox`, create a new file `~/.config/keyhint/firefox.toml` which only\ncontains the ID and the additional bindings:\n\n```toml\nid = \"firefox\"\n\n[section]\n[section.\"My Personal Favorites\"] # New section\n\"Ctrl + Shift + Tab\" = \"Show all Tabs\"\n# ...\n```\n\n#### Add new cheatsheet which never gets auto-selected\n\nTo add a new cheatsheet, which never gets automatically selected and displayed by\nKeyHint, but remains accessible through KeyHint's cheatsheet dropdown, create a file\n`~/.config/keyhint/my-app.toml`:\n\n```toml\nid = \"my-app\"\nurl = \"url-to-my-apps-keybindings\"\n\n[match]\nregex_wmclass = \"a^\" # Patter which never matches\nregex_title = \"a^\"\n\n[section]\n[section.General]\n\"Ctrl + C\" = \"Copy\"\n# ...\n\n```\n\n#### Different cheatsheets for different Websites\n\nFor showing different browser-cheatsheets depending on the current website, you might\nwant to use a browser extension like\n\"[Add URL To Window Title](https://addons.mozilla.org/en-US/firefox/addon/add-url-to-window-title/)\"\nand configure the `[match]` section to look for the url in the title. E.g.\n`~/.config/keyhint/github.toml`\n\n```toml\nid = \"github.com\"\n\n[match]\nregex_wmclass = \"Firefox\"\nregex_title = \".*github\\\\.com.*\" # URL added by browser extensions to window title\n\n[section]\n[section.Repositories]\ngc = \"Goto code tab\"\n# ...\n```\n\n## Contribute\n\nI'm happy about any contribution! Especially I would appreciate submissions to improve\nthe\n[shipped cheatsheets](https://github.com/dynobo/keyhint/tree/main/src/keyhint/config).\n(The current set are the cheatsheets I personally use).\n\n## Design Principles\n\n- **Don't run as service**<br>It shouldn't consume resources in the background, even if\n this leads to slightly slower start-up time.\n- **No network connection**<br>Everything should run locally without any network\n communication.\n- **Dependencies**<br>The fewer dependencies, the better.\n\n## Certification\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Cheat-sheets for shortcuts & commands at your fingertips.",
"version": "0.5.0",
"project_urls": {
"Documentation": "https://github.com/dynobo/keyhint#readme",
"Issues": "https://github.com/dynobo/keyhint/issues",
"Source": "https://github.com/dynobo/keyhint"
},
"split_keywords": [
"cheatsheet",
" helper",
" hints",
" keybindings",
" shortcuts"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fb6a60b08be4312c35306b84130e6403954fbcc5ede6d2022f94659fb13291f9",
"md5": "4d79549b8046b4c7592f5e749a36f0f3",
"sha256": "37c61b9a9ec581ff28c924be772a7eeb112319edcd2e26657899726143b94bef"
},
"downloads": -1,
"filename": "keyhint-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4d79549b8046b4c7592f5e749a36f0f3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 664835,
"upload_time": "2024-04-23T16:37:03",
"upload_time_iso_8601": "2024-04-23T16:37:03.983483Z",
"url": "https://files.pythonhosted.org/packages/fb/6a/60b08be4312c35306b84130e6403954fbcc5ede6d2022f94659fb13291f9/keyhint-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "94a762854183b14a960478edc7f70ce0836e0d6ffc332a22c6b36560bee1726f",
"md5": "3a61907e4352fd719531fca54be2c1c3",
"sha256": "d8b8086da18795c9467399ce46b658c86183d0831dfbd877f99c6352b3c5314b"
},
"downloads": -1,
"filename": "keyhint-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "3a61907e4352fd719531fca54be2c1c3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 661283,
"upload_time": "2024-04-23T16:37:07",
"upload_time_iso_8601": "2024-04-23T16:37:07.869270Z",
"url": "https://files.pythonhosted.org/packages/94/a7/62854183b14a960478edc7f70ce0836e0d6ffc332a22c6b36560bee1726f/keyhint-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-23 16:37:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dynobo",
"github_project": "keyhint#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "keyhint"
}
JSON
