{"id":13451631,"url":"https://github.com/p-e-w/plotinus","last_synced_at":"2025-04-04T11:13:40.028Z","repository":{"id":150094295,"uuid":"73613088","full_name":"p-e-w/plotinus","owner":"p-e-w","description":"A searchable command palette in every modern GTK+ application","archived":false,"fork":false,"pushed_at":"2021-05-24T17:14:00.000Z","size":55,"stargazers_count":1022,"open_issues_count":16,"forks_count":22,"subscribers_count":25,"default_branch":"master","last_synced_at":"2025-03-28T10:07:35.961Z","etag":null,"topics":["command-palette","gnome","gtk","gtk3","linux","linux-desktop"],"latest_commit_sha":null,"homepage":null,"language":"Vala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/p-e-w.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2016-11-13T12:02:18.000Z","updated_at":"2025-03-23T00:11:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"39f4a818-d395-4733-89c5-ae1825598606","html_url":"https://github.com/p-e-w/plotinus","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p-e-w%2Fplotinus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p-e-w%2Fplotinus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p-e-w%2Fplotinus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p-e-w%2Fplotinus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/p-e-w","download_url":"https://codeload.github.com/p-e-w/plotinus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247166168,"owners_count":20894654,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["command-palette","gnome","gtk","gtk3","linux","linux-desktop"],"created_at":"2024-07-31T07:00:57.434Z","updated_at":"2025-04-04T11:13:40.005Z","avatar_url":"https://github.com/p-e-w.png","language":"Vala","readme":"\u003e Only a compound can be beautiful, never anything devoid of parts; and only a whole;\u003cbr\u003e\n\u003e the several parts will have beauty, not in themselves,\u003cbr\u003e\n\u003e but only as working together to give a comely total.\u003cbr\u003e\n\u003e Yet beauty in an aggregate demands beauty in details:\u003cbr\u003e\n\u003e it cannot be constructed out of ugliness; its law must run throughout.\n\n– [Plotinus](https://en.wikipedia.org/wiki/Plotinus), *First Ennead*\n\n\n\u003ch1 align=\"center\"\u003ePlotinus\u003c/h1\u003e\n\u003ch3 align=\"center\"\u003eA searchable command palette in every modern GTK+ application\u003c/h3\u003e\n\u003cbr\u003e\n\nHave you used Sublime Text's or Atom's \"Command Palette\"? It's a list of everything those editors can do that opens at the press of a key and finds the action you are looking for just by typing a few letters. It's raw power at your fingertips.\n\nPlotinus brings that power ***to every application on your system*** (that is, to those that use the GTK+ 3 toolkit). It automatically extracts all available commands by introspecting a running application, instantly adapting to UI changes and showing only relevant actions. Using Plotinus requires *no modifications* to the application itself!\n\nJust press \u003ckbd\u003eCtrl+Shift+P\u003c/kbd\u003e ([configurable](#configuration)) and you're in business – it feels so natural you'll soon wonder how you ever lived without it.\n\n![Nautilus screencast](https://cloud.githubusercontent.com/assets/2702526/20246717/454a1a9a-a9e3-11e6-8b19-4db092348793.gif)\n\n![gedit screencast](https://cloud.githubusercontent.com/assets/2702526/20246718/5397bed6-a9e3-11e6-8023-aa9a318820e3.gif)\n\n\n## Installation\n\n### Prerequisites\n\nTo build Plotinus from source, you need Git, CMake, Vala, and the GTK+ 3 development files. All of these are easily obtained on most modern Linux distributions:\n\n#### Fedora / RHEL / etc.\n\n```\nsudo dnf install git cmake vala gtk3-devel\n```\n\n#### Ubuntu / Mint / Elementary / etc.\n\n```\nsudo apt-get install git cmake valac libgtk-3-dev\n```\n\n### Building\n\n```\ngit clone https://github.com/p-e-w/plotinus.git\ncd plotinus\nmkdir build\ncd build\ncmake ..\nmake\nsudo make install\n```\n\n### Enabling Plotinus in applications\n\nBecause of the complexity and clumsiness surrounding Linux environment variables, Plotinus is currently not enabled automatically. The easiest way to enable Plotinus for all applications on the system is to add the line\n\n```\nGTK3_MODULES=[libpath]\n```\n\nto `/etc/environment`, where `[libpath]` is the *full, absolute* path of `libplotinus.so`, which can be found using the command\n\n```\nwhereis -b libplotinus\n```\n\nAlternatively, you can try Plotinus with individual applications by running them with\n\n```\nGTK3_MODULES=[libpath] application\n```\n\nfrom a terminal.\n\n\n## Configuration\n\nPlotinus can be configured both globally and per application. Application settings take precedence over global settings. In the commands below, `[application]` can be either\n\n* `default`, in which case the setting is applied globally, or\n* the path of an application executable, without the leading slash and with all other slashes replaced by periods (e.g. `/usr/bin/gedit` -\u003e `usr.bin.gedit`).\n\nNote that the relevant path is the path of the *process executable*, which is not always identical to the executable being launched. For example, all GNOME JavaScript applications run the process `/usr/bin/gjs`.\n\n### Enabling/disabling the command palette\n\n```\ngsettings set com.worldwidemann.plotinus:/com/worldwidemann/plotinus/[application]/ enabled [true/false]\n```\n\n### Changing the keyboard shortcut\n\n```\ngsettings set com.worldwidemann.plotinus:/com/worldwidemann/plotinus/[application]/ hotkeys '[keys]'\n```\n\n`[keys]` must be an array of strings in the format expected by [`gtk_accelerator_parse`](https://developer.gnome.org/gtk3/stable/gtk3-Keyboard-Accelerators.html#gtk-accelerator-parse), e.g. `[\"\u003cPrimary\u003e\u003cShift\u003eP\", \"\u003cPrimary\u003eP\"]`. Each shortcut in the array opens the command palette.\n\n### Enabling/disabling D-Bus window registration\n\n```\ngsettings set com.worldwidemann.plotinus:/com/worldwidemann/plotinus/[application]/ dbus-enabled [true/false]\n```\n\nSee the following section for details.\n\n\n## D-Bus API\n\nPlotinus provides a simple but complete [D-Bus](https://www.freedesktop.org/wiki/Software/dbus/) API for developers who want to use its functionality from their own software. The API consists of two methods, exposed on the session bus at `com.worldwidemann.plotinus`:\n\n* `GetCommands(window_path) -\u003e (bus_name, command_paths)`\u003cbr\u003eTakes the object path of a GTK+ window (which can e.g. be obtained from a Mutter window via [`meta_window_get_gtk_window_object_path`](https://developer.gnome.org/meta/stable/MetaWindow.html#meta-window-get-gtk-window-object-path)) and returns an array of object paths referencing commands extracted from that window, as well as the name of the bus on which they are registered.\u003cbr\u003eThe mechanism behind this method is somewhat similar to [Ubuntu's AppMenu Registrar](https://github.com/tetzank/qmenu_hud/blob/master/com.canonical.AppMenu.Registrar.xml), but more lightweight and compatible with Wayland. Window registration [must be enabled](#enablingdisabling-dbus-window-registration) before using this method.\n\n* `ShowCommandPalette(commands) -\u003e (bus_name, command_palette_path)`\u003cbr\u003eTakes an array of commands (structs of the form `(path, label, accelerators)`) and opens a command palette window displaying those commands. The returned object path references a control object registered on the returned bus name which provides signals on user interaction with the window.\n\nCalls to these methods are processed by the **Plotinus D-Bus service,** which can be started with\n\n```\nplotinus\n```\n\n### Examples\n\nThe following examples demonstrate how to use the D-Bus API from Python. They require [pydbus](https://github.com/LEW21/pydbus) to be installed and the Plotinus D-Bus service to be running.\n\n#### Application remote control\n\n```python\n#!/usr/bin/env python\n\nimport sys\nfrom pydbus import SessionBus\n\nbus = SessionBus()\nplotinus = bus.get(\"com.worldwidemann.plotinus\")\n\nbus_name, command_paths = plotinus.GetCommands(sys.argv[1])\ncommands = [bus.get(bus_name, command_path) for command_path in command_paths]\n\nfor i, command in enumerate(commands):\n  print(\"[%d] %s -\u003e %s\" % (i, \" -\u003e \".join(command.Path), command.Label))\n\nindex = raw_input(\"Number of command to execute: \")\n\nif index:\n  commands[int(index)].Execute()\n```\n\nBefore running this example, enable window registration with\n\n```\ngsettings set com.worldwidemann.plotinus:/com/worldwidemann/plotinus/default/ dbus-enabled true\n```\n\nThen, run an application (e.g. gedit) with [Plotinus enabled](#enabling-plotinus-in-applications). Now run the script with the window object path as an argument, i.e.\n\n```\n./application_remote_control.py /org/gnome/gedit/window/1\n```\n\n#### Application launcher\n\nBased on [this Argos plugin](https://github.com/p-e-w/argos#launcherpy), uses Plotinus' command palette to display a list of applications available on the system.\n\n```python\n#!/usr/bin/env python\n\nimport os, re\nfrom pydbus import SessionBus\nfrom gi.repository import GLib, Gio\n\napplications = {}\n\nfor app_info in Gio.AppInfo.get_all():\n  categories = app_info.get_categories()\n  if categories is None:\n    continue\n  # Remove \"%U\" and \"%F\" placeholders\n  command_line = re.sub(\"%\\\\w\", \"\", app_info.get_commandline()).strip()\n  app = (app_info.get_name(), command_line)\n  for category in categories.split(\";\"):\n    if category not in [\"GNOME\", \"GTK\", \"\"]:\n      if category not in applications:\n        applications[category] = []\n      applications[category].append(app)\n      break\n\ncommands = []\ncommand_lines = []\n\nfor category, apps in sorted(applications.items()):\n  for app in sorted(apps):\n    commands.append(([category], app[0], []))\n    command_lines.append(app[1])\n\nbus = SessionBus()\nplotinus = bus.get(\"com.worldwidemann.plotinus\")\n\nbus_name, command_palette_path = plotinus.ShowCommandPalette(commands)\ncommand_palette = bus.get(bus_name, command_palette_path)\n\nloop = GLib.MainLoop()\n\ndef command_executed(index):\n  os.system(command_lines[index])\n\ncommand_palette.CommandExecuted.connect(command_executed)\n\ndef closed():\n  # Wait for CommandExecuted signal\n  GLib.timeout_add(500, loop.quit)\n\ncommand_palette.Closed.connect(closed)\n\nloop.run()\n```\n\n\n## Acknowledgments\n\nDocumentation on GTK+ modules is essentially nonexisting. Without [gtkparasite](https://github.com/chipx86/gtkparasite) and [gnome-globalmenu](https://github.com/gnome-globalmenu/gnome-globalmenu) to learn from, it would have been a lot harder to get this project off the ground.\n\nThe CMake modules are copied verbatim from Elementary's [pantheon-installer](https://github.com/elementary/pantheon-installer) repository.\n\nVala is still the greatest thing ever to happen to Linux Desktop development.\n\n\n## Contributing\n\nContributors are always welcome. However, **please file an issue describing what you intend to add before opening a pull request,** *especially* for new features! I have a clear vision of what I want (and do not want) Plotinus to be, so discussing potential additions might help you avoid duplication and wasted work.\n\nBy contributing, you agree to release your changes under the same license as the rest of the project (see below).\n\n\n## License\n\nCopyright \u0026copy; 2016-2017 Philipp Emanuel Weidmann (\u003cpew@worldwidemann.com\u003e)\n\nReleased under the terms of the [GNU General Public License, version 3](https://gnu.org/licenses/gpl.html)\n","funding_links":[],"categories":["Vala","Applications","Libraries"],"sub_categories":["Productivity","GTK+"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fp-e-w%2Fplotinus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fp-e-w%2Fplotinus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fp-e-w%2Fplotinus/lists"}