commit d4134ccb0dcf66e05ad0d1364a0f6a166839181b Author: dualfroz Date: Wed Aug 5 19:46:37 2026 +0200 docs: add project README diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..43ae0e2 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +__pycache__/ +*.py[cod] diff --git a/README.md b/README.md new file mode 100644 index 0000000..a025daf --- /dev/null +++ b/README.md @@ -0,0 +1,140 @@ +# cinnamon-tweaks + +Two small GTK 3 desktop utilities for the Cinnamon desktop environment, each +one built around the same frustration: a setting you change often enough to +resent how many clicks it takes to reach through Cinnamon Settings. + +| Tool | Replaces | Interface | +| --- | --- | --- | +| [`shortcut-manager`](#shortcut-manager) | Settings → Keyboard → Shortcuts → Custom Shortcuts | GTK window, menu launcher | +| [`panel-tweaks`](#panel-tweaks) | Settings → Panel | GTK window, menu launcher | + +Neither tool invents its own storage. Both read and write exactly the same +gsettings/dconf keys Cinnamon itself uses, so every change is live immediately, +survives logout, and shows up in Cinnamon Settings as if you had made it there. +Nothing needs to be restarted and no daemon runs in the background. + +They install independently — take one, both, or neither. + +## Requirements + +- Cinnamon (the tools read `org.cinnamon.*` gsettings schemas, so they will not + do anything useful on GNOME, KDE or anything else) +- Python 3 +- PyGObject with GTK 3 +- `dconf` command-line tool — used by `shortcut-manager` to discover orphaned + shortcut slots and to delete shortcuts cleanly. Optional; the tool degrades + gracefully if it is missing. + +On Linux Mint and other Debian derivatives: + +```bash +sudo apt install python3-gi gir1.2-gtk-3.0 dconf-cli +``` + +--- + +## shortcut-manager + +A window that lists every custom keyboard shortcut registered on your desktop +and lets you add, edit and delete them. + +### Features + +- **One list of everything.** Name, key combo and command for every custom + shortcut, in one sortable table. +- **Capture instead of type.** The shortcut field records the next combination + you press rather than asking you to spell out `T`. Escape or + Backspace clears it. +- **Conflict warnings.** Before you save, the dialog tells you if the + combination is already taken — by another custom shortcut, or by a built-in + one. It checks the Cinnamon desktop, window manager, media-key, Muffin and + GNOME window-manager schemas. +- **Command presets.** The new-shortcut dialog offers quick-fill commands for + a terminal, file manager, screen lock, screenshot tools, volume mute, browser + and text editor. Only presets whose binary is actually installed are offered, + so the list never suggests a command that would fail. +- **No orphans.** New shortcuts claim the lowest free `customN` slot, taking + into account slots left behind in dconf by other tools, and deleting a + shortcut resets its dconf path rather than just unlisting it. + +### Installing + +```bash +cd shortcut-manager +./install.sh +``` + +Copies the app into `~/.local/share/cinnamon-shortcut-manager` and adds a +"Custom Shortcuts" launcher to your applications menu under Settings. + +To run it without installing: + +```bash +python3 shortcut-manager/shortcut_manager.py +``` + +### Where the settings live + +Cinnamon stores custom shortcuts as a relocatable schema. Each one lives at +`/org/cinnamon/desktop/keybindings/custom-keybindings/customN/` with `name`, +`command` and `binding` keys, and the list of active ids sits in `custom-list` +under `org.cinnamon.desktop.keybindings`. This tool writes precisely those, so +anything it creates is indistinguishable from a shortcut made by hand. + +--- + +## panel-tweaks + +A window with the handful of panel settings worth a one-click toggle. + +### Features + +- **Auto-hide** the panel on or off. +- **Edit mode** on or off — the mode that lets you drag applets around the + panel. +- **Panel height** on a slider, from 20 to 80 pixels, applied live as you drag. +- **Applet list** for the panel, with a checkbox to enable or disable each one. + +### Installing + +```bash +cd panel-tweaks +./install.sh +``` + +Copies the app into `~/.local/share/cinnamon-panel-tweaks` and adds a "Panel +Tweaks" launcher to your applications menu under Settings. + +To run it without installing: + +```bash +python3 panel-tweaks/panel_tweaks.py +``` + +### Limitations worth knowing + +- **It only manages one panel.** If you have several panels configured, the tool + operates on the first one listed in `panels-enabled` and ignores the rest. +- **Disabling an applet is one-way within a session.** Unchecking an applet + removes it from `enabled-applets` immediately. You can re-check the box while + the window is still open, but once you close and reopen the tool the applet is + no longer in the list, and you will need Cinnamon Settings to bring it back. +- It deliberately does not try to be a layout editor or an applet manager. + That is Cinnamon Settings' job; this is a shortcut to the knobs used often. + +### Where the settings live + +All under the `org.cinnamon` schema: `panels-enabled`, `panels-autohide`, +`panels-height`, `panel-edit-mode` and `enabled-applets`. + +--- + +## Tested on + +Linux Mint 22.2 with Cinnamon, on an X11 session. Both tools depend on Cinnamon +schemas specifically and are not expected to work on other desktops. + +## Licence + +No licence has been chosen yet.