controller-companion 0.4.0__tar.gz

controller_companion-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Johannes Gundlach
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

controller_companion-0.4.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.1
+Name: controller-companion
+Version: 0.4.0
+Summary: 
+Author: Johannes Gundlach
+Author-email: 24914225+Johannes11833@users.noreply.github.com
+Requires-Python: >=3.9,<3.14
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: pillow (>=11.0.0,<12.0.0)
+Requires-Dist: pyautogui (>=0.9.54,<0.10.0)
+Requires-Dist: pygame (>=2.6.1,<3.0.0)
+Requires-Dist: pystray (>=0.19.5,<0.20.0)
+Requires-Dist: requests (>=2.32.3,<3.0.0)
+Requires-Dist: rich (>=13.9.4,<14.0.0)
+Description-Content-Type: text/markdown
+
+# Controller Companion
+
+Easily map controller shortcuts to an action.
+The following actions are supported:
+- Kill a task by its name.
+- Execute a keyboard shortcut.
+- Execute an arbitrary console command.
+
+## Features
+- GUI and CLI options available
+- Supports a wide variety of controllers (those supported by [pygame](https://www.pygame.org))
+- Runs on Windows, Linux and Mac
+- Auto start on system boot (windows only for now)
+- GUI app can be compiled as a standalone executable (using [PyInstaller](https://pyinstaller.org)
+
+## How to run
+- CLI and GUI versions are accessible through [poetry](https://python-poetry.org/)
+- CLI:
+    - Multiple mappings can be created.
+    - One or multiple input controller key combination that triggers an action can be defined using --input. The keys of one individual input combination are separated by commas, while each distinct input combination is separated by a space. 
+    - One or multiple actions can be defined using either `--task-kill`, `--console` or `--shortcut`. These actions will be mapped to the previously defined controller --input key combinations in the order `--task-kill`, `--console` and finally `--shortcut`
+    - Example with 2 mappings: 
+    ```console
+    poetry run controller_companion --input A,B Back,Left --console explorer.exe --shortcut alt+f4
+    ```
+    will result in the following mapping:
+    ```console
+    Controller<A,B> --> Action<name: Run command "explorer.exe", target: explorer.exe, type: CONSOLE_COMMAND>
+    Controller<Back,Left> --> Action<name: Shortcut "alt+f4", target: alt+f4, type: KEYBOARD_SHORTCUT>
+    ```
+
+    - Run `poetry run controller_companion --help` to see all available arguments
+
+## Build Executable
+With [poetry](https://python-poetry.org/) installed, run the following command to build the executable using [PyInstaller](https://pyinstaller.org):
+```console 
+poetry run build
+```
+
+## Screenshots
+### Main Window
+![demo](demo/app.png)
+### Create a new shortcut 
+![demo](demo/add_new_shortcut.png)
+

controller_companion-0.4.0/README.md

@@ -0,0 +1,44 @@
+# Controller Companion
+
+Easily map controller shortcuts to an action.
+The following actions are supported:
+- Kill a task by its name.
+- Execute a keyboard shortcut.
+- Execute an arbitrary console command.
+
+## Features
+- GUI and CLI options available
+- Supports a wide variety of controllers (those supported by [pygame](https://www.pygame.org))
+- Runs on Windows, Linux and Mac
+- Auto start on system boot (windows only for now)
+- GUI app can be compiled as a standalone executable (using [PyInstaller](https://pyinstaller.org)
+
+## How to run
+- CLI and GUI versions are accessible through [poetry](https://python-poetry.org/)
+- CLI:
+    - Multiple mappings can be created.
+    - One or multiple input controller key combination that triggers an action can be defined using --input. The keys of one individual input combination are separated by commas, while each distinct input combination is separated by a space. 
+    - One or multiple actions can be defined using either `--task-kill`, `--console` or `--shortcut`. These actions will be mapped to the previously defined controller --input key combinations in the order `--task-kill`, `--console` and finally `--shortcut`
+    - Example with 2 mappings: 
+    ```console
+    poetry run controller_companion --input A,B Back,Left --console explorer.exe --shortcut alt+f4
+    ```
+    will result in the following mapping:
+    ```console
+    Controller<A,B> --> Action<name: Run command "explorer.exe", target: explorer.exe, type: CONSOLE_COMMAND>
+    Controller<Back,Left> --> Action<name: Shortcut "alt+f4", target: alt+f4, type: KEYBOARD_SHORTCUT>
+    ```
+
+    - Run `poetry run controller_companion --help` to see all available arguments
+
+## Build Executable
+With [poetry](https://python-poetry.org/) installed, run the following command to build the executable using [PyInstaller](https://pyinstaller.org):
+```console 
+poetry run build
+```
+
+## Screenshots
+### Main Window
+![demo](demo/app.png)
+### Create a new shortcut 
+![demo](demo/add_new_shortcut.png)

controller_companion-0.4.0/controller_companion/__init__.py

@@ -0,0 +1,4 @@
+from importlib.metadata import version
+
+
+VERSION = f'v{version("controller-companion")}'

controller_companion-0.4.0/controller_companion/app/app.py

@@ -0,0 +1,304 @@
+import argparse
+import json
+import os
+from pathlib import Path
+import threading
+import tkinter as tk
+from tkinter import Menu, messagebox
+import webbrowser
+import requests
+import platform
+from tkinter import ttk
+import pystray
+from PIL import Image
+import controller_companion
+from controller_companion.logs import logger
+from controller_companion.mapping import Mapping
+from controller_companion.app import resources
+from controller_companion.app.popup_about import AboutScreen
+from controller_companion.app.popup_create_action import CreateActionPopup
+import controller_companion.controller_observer as controller_observer
+
+
+class ControllerCompanion(tk.Tk):
+    def __init__(self, launch_minimized=False):
+        super().__init__()
+
+        self.title("Controller Companion")
+        self.iconbitmap(resources.APP_ICON_ICO)
+        self.geometry("550x280")
+        self.protocol("WM_DELETE_WINDOW", self.minimize_to_tray)
+        self.app_path = Path.home() / "Documents" / "Controller Companion"
+        self.settings_file = self.app_path / "settings.json"
+
+        # load settings
+        self.settings = self.load_settings()
+
+        # --------------------------------- add menu --------------------------------- #
+        menu = Menu(self)
+        self.config(menu=menu)
+
+        # File Menu
+        filemenu_ = Menu(menu, tearoff=False)
+        menu.add_cascade(label="File", menu=filemenu_)
+        filemenu_.add_command(
+            label="Add mapping", command=self.open_add_actions, accelerator="Ctrl+N"
+        )
+        filemenu_.add_command(
+            label="Delete mapping",
+            command=self.delete_action,
+            accelerator="Del",
+        )
+        open_config = lambda: os.startfile(self.settings_file)
+        filemenu_.add_command(
+            label="Open config file",
+            command=open_config,
+            accelerator="Ctrl+C",
+        )
+        self.bind_all("<Delete>", self.delete_action)
+        self.bind_all("<Control-n>", self.open_add_actions)
+        self.bind_all("<Control-q>", self.quit_window)
+        self.bind_all("<Control-c>", lambda _: open_config())
+        filemenu_.add_separator()
+        filemenu_.add_command(
+            label="Quit",
+            command=self.quit_window,
+            accelerator="Ctrl+Q",
+        )
+
+        # Settings Menu
+        settings_ = Menu(menu, tearoff=0)
+        self.var_settings_minimize_on_close = tk.IntVar()
+        self.var_settings_auto_start = tk.IntVar()
+        self.var_settings_minimize_on_close.set(self.settings["minimize_on_exit"])
+        self.var_settings_auto_start.set(self.settings["auto_start"])
+        menu.add_cascade(label="Settings", menu=settings_)
+        settings_.add_checkbutton(
+            label="Minimize to system tray",
+            onvalue=1,
+            offvalue=0,
+            variable=self.var_settings_minimize_on_close,
+            command=self.save_settings,
+        )
+
+        if resources.is_frozen():
+            # only display auto start option if this is an executable
+            settings_.add_checkbutton(
+                label="Auto Start",
+                onvalue=1,
+                offvalue=0,
+                variable=self.var_settings_auto_start,
+                command=self.toggle_autostart,
+            )
+
+        # Help Menu
+        help_ = Menu(menu, tearoff=0)
+        menu.add_cascade(label="Help", menu=help_)
+        help_.add_command(label="Check for Updates", command=self.check_for_updates)
+        help_.add_command(label="About", command=lambda: AboutScreen(self))
+
+        # ---------------------------------------------------------------------------- #
+
+        tk.Label(self, text="Defined Mappings").pack(fill=tk.X)
+        self.treeview = ttk.Treeview(columns=("shortcut", "target"), height=7)
+        self.treeview.heading("#0", text="Name")
+        self.treeview.heading("shortcut", text="Shortcut")
+        self.treeview.heading("target", text="Target")
+        for mapping in self.defined_actions:
+            self.treeview.insert(
+                "",
+                tk.END,
+                text=mapping.name,
+                values=(
+                    mapping.controller_state.describe(),
+                    mapping.target,
+                ),
+            )
+        self.treeview.pack(expand=True, fill=tk.BOTH)
+
+        # --------------------------- connected controllers -------------------------- #
+
+        tk.Label(self, text="Connected Controllers").pack(fill=tk.X)
+        self.var_connected_controllers = tk.Variable()
+        listbox_controllers = tk.Listbox(
+            self,
+            listvariable=self.var_connected_controllers,
+            selectmode=tk.EXTENDED,
+        )
+        listbox_controllers.pack(expand=True, fill=tk.BOTH)
+
+        # -------------------- start the joystick observer thread -------------------- #
+        self.thread = threading.Thread(
+            target=controller_observer.start_observer,
+            daemon=True,
+            args=[
+                self.defined_actions,
+            ],
+            kwargs={
+                "debug": self.settings.get("debug", 0) == 1,
+                "controller_callback": lambda update: self.var_connected_controllers.set(
+                    [f"       {c.name}" for c in update]
+                ),
+            },
+        )
+        self.thread.start()
+        # ---------------------------------------------------------------------------- #
+
+        if launch_minimized:
+            # use after to make initial controller connected callback work
+            # otherwise, we would get a RuntimeError: main thread is not in main loop
+            # when executing the controller_callback above.
+            self.after(100, self.minimize_to_tray, [True])
+
+    def minimize_to_tray(self, is_launch: bool = False):
+        if self.var_settings_minimize_on_close.get() == 0 and not is_launch:
+            # exit the app instead as minimize to system tray is disabled
+            self.quit_window()
+            return
+
+        self.withdraw()
+        image = Image.open(resources.APP_ICON_ICO)
+        menu = (
+            pystray.MenuItem("Show", self.show_window),
+            pystray.MenuItem("Quit", self.quit_window_from_icon),
+        )
+        icon = pystray.Icon("name", image, "Controller Companion", menu)
+        icon.run()
+
+    def quit_window_from_icon(self, icon=None):
+        if icon is not None:
+            icon.stop()
+        self.quit_window()
+
+    def quit_window(self, _=None):
+        self.thread.do_run = False
+        self.thread.join()
+        print("Thread ended")
+        self.destroy()
+
+    def show_window(self, icon):
+        icon.stop()
+        self.after(0, self.deiconify)
+
+    def open_add_actions(self, _=None):
+        p = CreateActionPopup(self)
+        result = p.result
+        if result is not None:
+            self.defined_actions.append(result)
+            self.treeview.insert(
+                "",
+                tk.END,
+                text=result.name,
+                values=(
+                    result.controller_state.describe(),
+                    result.target,
+                ),
+                image=tk.PhotoImage(file=resources.APP_ICON_PNG),
+            )
+            self.save_settings()
+
+    def delete_action(self, _=None):
+        selection = self.treeview.selection()
+        for item in selection:
+            delete_idx = self.treeview.index(item)
+            self.treeview.delete(item)
+            self.defined_actions.pop(delete_idx)
+
+        if len(selection) > 0:
+            self.save_settings()
+
+    def load_settings(self):
+        settings = {
+            "minimize_on_exit": 1,
+            "auto_start": 0,
+            "debug": 0,
+        }
+
+        if self.settings_file.is_file():
+            settings.update(json.loads(self.settings_file.read_text()))
+            self.defined_actions = [Mapping.from_dict(d) for d in settings["actions"]]
+        else:
+            self.defined_actions = []
+
+        return settings
+
+    def save_settings(self):
+        # update the settings dict
+        self.settings.update(
+            {
+                "minimize_on_exit": self.var_settings_minimize_on_close.get(),
+                "auto_start": self.var_settings_auto_start.get(),
+                "actions": [item.to_dict() for item in self.defined_actions],
+            }
+        )
+        self.settings_file.parent.mkdir(exist_ok=True, parents=True)
+        self.settings_file.write_text(json.dumps(self.settings, indent=4))
+
+        print(f"Saved settings to: {self.settings_file}")
+
+    def toggle_autostart(self):
+        executable = resources.get_executable_path()
+        autostart = self.var_settings_auto_start.get() == 1
+
+        if platform.system() == "Windows":
+            bat_file = Path(
+                Path.home(),
+                "AppData/Roaming/Microsoft/Windows/Start Menu/Programs/Startup/controller_companion.bat",
+            )
+            if autostart:
+                bat_file.write_text(f'start "" "{executable.absolute()}" "-m"')
+            else:
+                bat_file.unlink(missing_ok=True)
+
+        self.save_settings()
+
+    def check_for_updates(self):
+        response = requests.get(
+            "https://api.github.com/repos/Johannes11833/controller-companion/releases/latest"
+        )
+        latest_version = response.json()["name"]
+        installed_version = controller_companion.VERSION
+
+        if latest_version == installed_version:
+            messagebox.showinfo(
+                "Up to date",
+                "The latest version of Controller Companion is installed.",
+                parent=self,
+            )
+        else:
+            url = (
+                "https://github.com/Johannes11833/controller-companion/releases/latest"
+            )
+            logger.info(
+                f"A new update is available: {installed_version} -> {latest_version}. URL: {url}"
+            )
+            open_website = messagebox.askyesno(
+                f"Update available: {latest_version}",
+                f"A new update is available for Controller Companion:\ninstalled: Go to download page now?",
+                parent=self,
+            )
+            if open_website:
+                webbrowser.open_new_tab(
+                    url,
+                )
+
+
+def cli():
+    parser = argparse.ArgumentParser(
+        description="Lauch the Controller Companion UI App."
+    )
+    parser.add_argument(
+        "-m",
+        "--minimized",
+        help="Launch minimized.",
+        action="store_true",
+        default=False,
+    )
+    args = parser.parse_args()
+
+    app = ControllerCompanion(launch_minimized=args.minimized)
+    app.mainloop()
+
+
+if __name__ == "__main__":
+    cli()

controller_companion-0.4.0/controller_companion/app/popup_about.py

@@ -0,0 +1,49 @@
+import tkinter as tk
+from tkinter import ttk
+import webbrowser
+from PIL import Image, ImageTk
+
+from controller_companion import VERSION
+from controller_companion.app import resources
+
+
+class AboutScreen(tk.Toplevel):
+    def __init__(self, master, **kwargs):
+        super().__init__(master, **kwargs)
+        self.title("About")
+        self.iconbitmap(resources.APP_ICON_ICO)
+        self.resizable(False, False)
+
+        frame1 = tk.Frame(master=self, width=50, padx=10, pady=10)
+        frame1.pack(fill=tk.Y, side=tk.LEFT)
+        frame2 = tk.Frame(master=self, padx=10, pady=10)
+        frame2.pack(fill=tk.Y, side=tk.LEFT)
+
+        # Display it within a label.
+        image = ImageTk.PhotoImage(Image.open(resources.APP_ICON_PNG))
+        label = ttk.Label(frame1, image=image, width=50)
+        label.pack(side=tk.LEFT)
+
+        tk.Label(
+            frame2,
+            text=f"Controller Companion {VERSION}",
+            font=("Helvetica", 12, "bold"),
+        ).pack(side=tk.TOP, anchor="w")
+        tk.Label(frame2, text=f"Made by Johannes Gundlach").pack(
+            side=tk.TOP, anchor="w"
+        )
+        link = tk.Label(
+            frame2,
+            text="https://github.com/Johannes11833/controller-companion",
+            fg="blue",
+            cursor="hand2",
+        )
+        link.pack(side=tk.TOP, anchor="w")
+        link.bind("<Button-1>", lambda _: self.callback(link.cget("text")))
+
+        self.mainloop()
+
+    def callback(self, url):
+        webbrowser.open_new_tab(
+            url,
+        )

controller_companion-0.4.0/controller_companion/app/popup_create_action.py

@@ -0,0 +1,240 @@
+import tkinter as tk
+from tkinter import (
+    Checkbutton,
+    Event,
+    IntVar,
+    Radiobutton,
+    StringVar,
+    ttk,
+)
+from tkinter import messagebox
+from controller_companion.logs import logger
+
+from controller_companion.mapping import Mapping, ActionType
+from controller_companion.app import resources
+from controller_companion.app.widgets.placeholder_entry import PlaceholderEntry
+from controller_companion.controller_state import (
+    ControllerState,
+    button_mapper,
+    d_pad_mapper,
+)
+
+
+class CreateActionPopup(tk.Toplevel):
+    """modal window requires a master"""
+
+    def __init__(self, master, **kwargs):
+        super().__init__(master, **kwargs)
+
+        self.iconbitmap(resources.APP_ICON_ICO)
+
+        self.var_buttons = {}
+        self.var_d_pad = IntVar()
+        self.var_action_type = StringVar()
+        self.var_command = StringVar()
+        self.result = None
+
+        frame_inputs = ttk.LabelFrame(
+            master=self, height=50, text="Controller Shortcut"
+        )
+        frame_inputs.pack(fill=tk.X, side=tk.TOP, expand=True, padx=10, pady=(10, 5))
+
+        frame_buttons = tk.Frame(master=frame_inputs, height=50, padx=5)
+        frame_buttons.pack(fill=tk.X, side=tk.TOP, expand=True)
+
+        frame_d_pad = tk.Frame(master=frame_inputs, height=50, padx=5)
+        frame_d_pad.pack(fill=tk.X, side=tk.TOP, expand=True)
+
+        frame_action = ttk.LabelFrame(
+            master=self, height=50, text="Action", padding=(0, 5, 5, 5)
+        )
+        frame_action.pack(fill=tk.X, side=tk.TOP, expand=True, padx=10, pady=5)
+
+        frame_save = ttk.LabelFrame(
+            master=self, height=50, text="Save", padding=(0, 5, 0, 5)
+        )
+        frame_save.pack(fill=tk.X, side=tk.TOP, expand=True, padx=10, pady=(5, 10))
+
+        tk.Label(frame_buttons, text="Buttons", anchor="w").grid(
+            row=0, column=0, sticky="W"
+        )
+        for column, button in enumerate(button_mapper.keys()):
+            self.var_buttons[button] = IntVar()
+            check = Checkbutton(
+                frame_buttons,
+                text=button,
+                variable=self.var_buttons[button],
+                anchor="w",
+            )
+            check.grid(row=1, column=column)
+
+        tk.Label(frame_d_pad, text="D-Pad", anchor="w").grid(
+            row=0, column=0, sticky="W"
+        )
+        self.var_d_pad.set(-1)
+        for column, d_pad_state in enumerate(d_pad_mapper.keys()):
+            check = Radiobutton(
+                frame_d_pad,
+                text=d_pad_state,
+                variable=self.var_d_pad,
+                value=column,
+                anchor="w",
+            )
+            check.grid(row=1, column=column)
+
+        tk.Label(
+            frame_action,
+            text="Type:",
+            padx=5,
+        ).grid(row=1, column=0)
+        combo = ttk.Combobox(
+            frame_action,
+            values=[e.value for e in ActionType],
+            state="readonly",
+            textvariable=self.var_action_type,
+        )
+        combo.bind("<<ComboboxSelected>>", self.action_type_changed)
+        self.var_action_type.set(ActionType.TASK_KILL_BY_NAME.value)
+        combo.grid(row=1, column=1)
+
+        tk.Label(
+            frame_action,
+            text="Target:",
+            padx=5,
+        ).grid(row=1, column=2)
+        self.entry_target_command = PlaceholderEntry(
+            frame_action,
+            textvariable=self.var_command,
+        )
+        frame_action.columnconfigure(3, weight=1)
+        self.entry_target_command.grid(row=1, column=3, sticky="nsew")
+
+        save_label = tk.Label(frame_save, text="Name:", padx=5)
+        save_label.grid(row=0, column=0, padx=5)
+        self.entry_name = PlaceholderEntry(
+            frame_save,
+            placeholder="name of the shortcut",
+            width=30,
+        )
+        self.entry_name.grid(row=0, column=1, padx=5)
+        tk.Button(frame_save, text="Save", command=self.on_save).grid(
+            row=0, column=2, padx=5
+        )
+        self.action_type_changed()
+
+        self.pressed_keys = set()
+        self.bind("<KeyPress>", self.on_key_press)
+
+        # The following commands keep the popup on top.
+        # Remove these if you want a program with 2 responding windows.
+        # These commands must be at the end of __init__
+        self.transient(master)  # set to be on top of the main window
+        self.grab_set()  # hijack all commands from the master (clicks on the main window are ignored)
+        master.wait_window(
+            self
+        )  # pause anything on the main window until this one closes
+
+    def on_save(self):
+
+        selected_buttons = []
+        target = self.var_command.get()
+        name = self.entry_name.get()
+
+        for btn, var in self.var_buttons.items():
+            if var.get() == 1:
+                selected_buttons.append(button_mapper[btn])
+
+        selected_d_pad_index = self.var_d_pad.get()
+        if selected_d_pad_index == -1:
+            d_pad_action = (0, 0)
+        else:
+            d_pad_action = list(d_pad_mapper.values())[selected_d_pad_index]
+
+        error = None
+        if len(selected_buttons) == 0 and d_pad_action == (0, 0):
+            error = "No controller shortcut was selected!"
+        elif target == "" or target == self.entry_target_command.placeholder:
+            error = "No target command was specified!"
+        elif name == "" or name == self.entry_name.placeholder:
+            error = "The name of the shortcut was not set!"
+        if error:
+            messagebox.showerror("Error", error)
+            return
+
+        state = ControllerState(
+            active_buttons=selected_buttons, d_pad_state=d_pad_action
+        )  # save the return value to an instance variable.
+        self.result = Mapping(
+            action_type=ActionType(self.var_action_type.get()),
+            target=target,
+            controller_state=state,
+            name=name,
+        )
+
+        self.destroy()
+
+    def action_type_changed(self, _=None):
+        self.action_type = ActionType(self.var_action_type.get())
+
+        if self.action_type == ActionType.TASK_KILL_BY_NAME:
+            self.entry_target_command.set_placeholder(
+                "name of task to kill (e.g. explorer.exe)"
+            )
+        elif self.action_type == ActionType.KEYBOARD_SHORTCUT:
+            self.pressed_keys.clear()
+            self.entry_target_command.set_placeholder("click here, then enter shortcut")
+        else:
+            self.entry_target_command.set_placeholder(
+                "custom arbitrary console command"
+            )
+
+    def on_key_press(self, event: Event):
+        valid_keys = Mapping.get_valid_keyboard_keys()
+        if self.action_type == ActionType.KEYBOARD_SHORTCUT:
+            key = event.char if event.char in valid_keys else event.keysym
+            key = (
+                key.lower()
+                .replace("_l", "")
+                .replace("_r", "")
+                .replace("control", "ctrl")
+                .replace("prior", "pageup")
+                .replace("next", "pagedown")
+            )
+            # XF86AudioLowerVolume
+            if "audiolower" in key:
+                key = "volumedown"
+            # XF86AudioRaiseVolume
+            elif "audioraise" in key:
+                key = "volumeup"
+            # XF86AudioMute
+            elif "audiomute" in key:
+                key = "volumemute"
+            elif key == "\t":
+                key = "tab"
+
+            if not key in valid_keys:
+                logger.warning(f"Unknown key event {event}")
+                return
+
+            if self.entry_target_command.focused:
+                if key in ["escape", "backspace"]:
+                    self.pressed_keys.clear()
+                elif key != "+":
+                    self.pressed_keys.add(key)
+
+                # sort keys
+                sorted_keys = list(self.pressed_keys)
+                ranks = ["ctrl", "win", "command", "alt", "shift"]
+                # 24 f keys supported by PyAutoGUI
+                f_keys = [f"f{i}" for i in range(1, 25)]
+                ranks.extend(f_keys)
+                sorted_keys.sort(
+                    key=lambda k: (
+                        str(ranks.index(k))
+                        if k in ranks
+                        else f"_{list(self.pressed_keys).index(k)}"
+                    )
+                )
+
+                self.entry_target_command.set_text("+".join(sorted_keys))
+                return "break"

controller_companion-0.4.0/controller_companion/app/resources.py

@@ -0,0 +1,32 @@
+from pathlib import Path
+import sys
+from typing import Union
+
+
+def __get_resource_path(relative_path: Union[Path, str]) -> Path:
+    """Get correct path to resource, works for dev and for executables.
+
+    Args:
+        relative_path (str): Path relative to the project root.
+
+    Returns:
+        Path: Full path to the requested resource.
+    """
+    # for executables, _MEIPASS is set, in dev mode we will use the repo root.
+    base_path = getattr(sys, "_MEIPASS", "")
+    return Path(base_path, relative_path)
+
+
+def is_frozen() -> bool:
+    if getattr(sys, "frozen", False):
+        # we are running in a bundle
+        return True
+    return False
+
+
+def get_executable_path() -> Path:
+    return Path(sys.executable)
+
+
+APP_ICON_ICO = __get_resource_path("controller_companion/res/app.ico")
+APP_ICON_PNG = __get_resource_path("controller_companion/res/app.png")

controller_companion-0.4.0/controller_companion/app/widgets/placeholder_entry.py

@@ -0,0 +1,37 @@
+import tkinter as tk
+
+
+class PlaceholderEntry(tk.Entry):
+
+    def __init__(self, master=None, placeholder: str = "", **kwargs):
+        super().__init__(master, **kwargs)
+        self.placeholder = placeholder
+        self.insert(0, self.placeholder)
+        self.configure(foreground="gray")
+        self.bind("<FocusIn>", self.__on_entry_click)
+        self.bind("<FocusOut>", self.__on_focus_out)
+        self.focused = False
+
+    def __on_entry_click(self, _=None):
+        if self.get() == self.placeholder:
+            self.delete(0, tk.END)
+            self.configure(foreground="black")
+        self.focused = True
+
+    def __on_focus_out(self, _=None):
+        if self.get() == "":
+            self.insert(0, self.placeholder)
+            self.configure(foreground="gray")
+        self.focused = False
+
+    def set_placeholder(self, placeholder: str):
+        if self.get() == self.placeholder:
+            self.delete(0, tk.END)
+            self.insert(0, placeholder)
+
+        self.placeholder = placeholder
+
+    def set_text(self, text: str):
+        self.delete(0, tk.END)
+        self.insert(0, text)
+        self.__on_entry_click()

controller_companion-0.4.0/controller_companion/controller.py

@@ -0,0 +1,10 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class Controller:
+    name: str
+    guid: str
+    power_level: str
+    instance_id: str
+    initialized: bool

controller_companion-0.4.0/controller_companion/controller_observer.py

@@ -0,0 +1,301 @@
+import argparse
+import os
+import threading
+import traceback
+from typing import Callable, Dict, List
+
+
+import controller_companion
+from controller_companion.logs import logger
+from controller_companion import logs
+
+# import pygame, hide welcome message
+os.environ["PYGAME_HIDE_SUPPORT_PROMPT"] = "yes"
+import pygame
+from rich.table import Table
+from rich.console import Console
+
+
+from controller_companion.mapping import Mapping, ActionType
+from controller_companion.controller import Controller
+from controller_companion.controller_state import (
+    ControllerState,
+    button_mapper,
+    d_pad_mapper,
+)
+
+
+VALID_KEYBOARD_KEYS = list(button_mapper.keys()) + list(d_pad_mapper.keys())
+do_run = True
+
+
+def start_observer(
+    defined_actions: List[Mapping],
+    debug: bool = False,
+    controller_callback: Callable[[List[Controller]], None] = None,
+    restart_delay_ms: int = 1000,
+):
+
+    if debug:
+        logs.set_log_level(logs.DEBUG)
+    else:
+        logs.set_log_level(logs.INFO)
+
+    # ------------------- print the defined mappings in a table ------------------ #
+    if len(defined_actions) > 0:
+        table = Table(title="Defined Mappings")
+        table.add_column("Name", justify="left", style="blue", header_style="blue")
+        table.add_column(
+            "Shortcut", justify="left", style="magenta", header_style="magenta"
+        )
+        table.add_column("Action", justify="left", style="green", header_style="green")
+
+        for mapping in defined_actions:
+            table.add_row(
+                mapping.name,
+                mapping.controller_state.describe(),
+                mapping.target,
+            )
+        Console().log(table)
+    else:
+        logger.info("No mappings have been defined.")
+    # ---------------------------------------------------------------------------- #
+
+    logger.info("Listening to controller inputs.")
+
+    try:
+        __process_pygame_events(
+            defined_actions=defined_actions,
+            controller_callback=controller_callback,
+        )
+    except Exception:
+        logger.error(
+            f"An exception occurred inside __process_pygame_events:\n{traceback.format_exc()}"
+        )
+        logger.info(f"restarting controller observation in {restart_delay_ms}s")
+        pygame.time.wait(restart_delay_ms)
+        return start_observer(
+            defined_actions=defined_actions,
+            debug=debug,
+            controller_callback=controller_callback,
+            restart_delay_ms=restart_delay_ms,
+        )
+
+    pygame.quit()
+
+
+def __process_pygame_events(
+    defined_actions: Dict[str, Mapping] = {},
+    controller_callback: Callable[[List[Controller]], None] = None,
+):
+    pygame.init()
+    pygame.joystick.init()
+
+    t = threading.current_thread()
+
+    # Initialize all detected joysticks
+    # Apparently with more than one controller connected this is required for all controllers to raise button/ d-pad events
+    # even though they will also raise an pygame.JOYDEVICEADDED event right from the start.
+    for i in range(pygame.joystick.get_count()):
+        pygame.joystick.Joystick(i).init()
+
+    controllers: Dict[int, pygame.joystick.JoystickType] = {}
+    controller_states: Dict[int, ControllerState] = {}
+
+    while getattr(t, "do_run", True):
+        for event in pygame.event.get():
+            instance_id = event.dict.get("instance_id", None)
+
+            if event.type in [pygame.JOYBUTTONDOWN, pygame.JOYBUTTONUP]:
+                button = event.dict["button"]
+
+                active_buttons = controller_states[instance_id].active_buttons
+                if event.type == pygame.JOYBUTTONDOWN:
+                    active_buttons.append(button)
+                else:
+                    active_buttons.remove(button)
+            elif event.type == pygame.JOYHATMOTION:
+                controller_states[instance_id].d_pad_state = event.dict["value"]
+            elif event.type in [pygame.JOYDEVICEADDED, pygame.JOYDEVICEREMOVED]:
+                if event.type == pygame.JOYDEVICEADDED:
+                    logger.info(f"Controller connected: {event}")
+                    c = pygame.joystick.Joystick(event.device_index)
+                    c.init()
+                    instance_id = c.get_instance_id()
+                    name = c.get_name()
+
+                    controllers[instance_id] = Controller(
+                        # on windows the controller name is wrapped inside "Controller()" when connected via USB
+                        name=name.removeprefix("Controller (").removesuffix(")"),
+                        guid=c.get_guid(),
+                        power_level=c.get_power_level(),
+                        instance_id=c.get_instance_id(),
+                        initialized=c.get_init(),
+                    )
+                    controller_states[instance_id] = ControllerState()
+                else:
+                    logger.info(f"Controller removed: {event}")
+                    controllers.pop(instance_id)
+                    controller_states.pop(instance_id)
+
+                if controller_callback:
+                    # call the callback through a thread so it does not keep the observer waiting (e.g. app in background)
+                    threading.Thread(
+                        target=controller_callback, args=[list(controllers.values())]
+                    ).start()
+            else:
+                # skip all other events. this way only relevant updates are processed below.
+                # this is relevant as e.g. thumbstick updates spam lots of updates
+                continue
+            __check_for_mappings(controller_states, defined_actions)
+
+            logger.debug(f"Controller state changed: {controller_states}")
+        pygame.time.wait(250)
+
+
+def __check_for_mappings(
+    controller_states: Dict[int, ControllerState],
+    defined_actions: List[Mapping],
+):
+    """Checks if one of the current controller states matches a defined mapping.
+
+    Args:
+        controller_states (Dict[int, ControllerState]): Dict of all current controller states where the key is the instance-id.
+        defined_actions (List[Mapping]): List of defined mappings.
+    """
+    for instance_id, state in controller_states.items():
+        for action in defined_actions:
+            if action.controller_state.describe() == state.describe():
+                logger.info(f"Mapping detected: {action} on controller {instance_id}")
+                action.execute()
+
+
+def cli():
+    parser = argparse.ArgumentParser(description="Controller Companion.")
+    parser.add_argument(
+        "-t",
+        "--task_kill",
+        help="Kill tasks by their name.",
+        nargs="+",
+        type=str,
+        default=[],
+    )
+    parser.add_argument(
+        "-c",
+        "--console",
+        help="Execute console commands.",
+        nargs="+",
+        type=str,
+        default=[],
+    )
+    parser.add_argument(
+        "-s",
+        "--shortcut",
+        help='Keyboard shortcut, where each shortcut is defined by a number of keys separated by "+" (e.g. "alt+f4").',
+        nargs="+",
+        type=str,
+        default=[],
+    )
+    parser.add_argument(
+        "-i",
+        "--input",
+        help="Input controller button combination.",
+        nargs="+",
+        type=str,
+    )
+    parser.add_argument(
+        "--valid-keys",
+        help="List all valid keys.",
+        action="store_true",
+        default=False,
+    )
+    parser.add_argument(
+        "-d",
+        "--debug",
+        help="Enable debug messages.",
+        action="store_true",
+        default=False,
+    )
+    parser.add_argument(
+        "-v",
+        "--version",
+        help="Print the installed version of this library.",
+        action="store_true",
+        default=False,
+    )
+    args = parser.parse_args()
+    debug = args.debug
+    defined_actions = []
+
+    if args.version:
+        print("Installed version:", controller_companion.VERSION)
+        return
+    elif args.valid_keys:
+        print(
+            f"The following keys are valid inputs that can be used with the --shortcut argument:\n{Mapping.get_valid_keyboard_keys()}"
+        )
+        return
+
+    if args.input is not None:
+        if len(args.input) != (
+            len(args.task_kill) + len(args.console) + len(args.shortcut)
+        ):
+            raise Exception(
+                "Length of --mapping needs to match with combined sum of commands provided to --task_kill, --console and --shortcut"
+            )
+
+        states = []
+        for m in args.input:
+            keys = m.split(",")
+            buttons = []
+            d_pad = (0, 0)
+            for input in keys:
+                if input in button_mapper:
+                    buttons.append(button_mapper[input])
+                elif input in d_pad_mapper:
+                    d_pad = d_pad_mapper[input]
+                else:
+                    raise Exception(
+                        f"key {input} is not a valid input. Valid options are {VALID_KEYBOARD_KEYS}"
+                    )
+            states.append(ControllerState(buttons, d_pad))
+
+        state_counter = 0
+        for t in args.task_kill:
+            defined_actions.append(
+                Mapping(
+                    ActionType.TASK_KILL_BY_NAME,
+                    target=t,
+                    name=f'Kill "{t}"',
+                    controller_state=states[state_counter],
+                )
+            )
+            state_counter += 1
+
+        for c in args.console:
+            defined_actions.append(
+                Mapping(
+                    ActionType.CONSOLE_COMMAND,
+                    target=c,
+                    name=f'Run command "{c}"',
+                    controller_state=states[state_counter],
+                )
+            )
+            state_counter += 1
+
+        for s in args.shortcut:
+            defined_actions.append(
+                Mapping(
+                    ActionType.KEYBOARD_SHORTCUT,
+                    target=s,
+                    name=f'Shortcut "{s}"',
+                    controller_state=states[state_counter],
+                )
+            )
+            state_counter += 1
+
+    start_observer(defined_actions=defined_actions, debug=debug)
+
+
+if __name__ == "__main__":
+    cli()

controller_companion-0.4.0/controller_companion/controller_state.py

@@ -0,0 +1,74 @@
+from typing import Dict, List, Optional, Tuple
+
+
+button_mapper = {
+    "A": 0,
+    "B": 1,
+    "X": 2,
+    "Y": 3,
+    "LB": 4,
+    "RB": 5,
+    "Back": 6,
+    "Start": 7,
+    "L-Stick": 8,
+    "R-Stick": 9,
+    "X-Box": 10,
+}
+button_mapper_inv = {v: k for k, v in button_mapper.items()}
+
+d_pad_mapper = {
+    "Left": (-1, 0),
+    "Right": (1, 0),
+    "Up": (0, 1),
+    "Down": (0, -1),
+    "Left-Down": (-1, -1),
+    "Left-Up": (-1, 1),
+    "Right-Up": (1, 1),
+    "Right-Down": (1, -1),
+}
+d_pad_mapper_inv = {v: k for k, v in d_pad_mapper.items()}
+
+
+class ControllerState:
+
+    def __init__(
+        self,
+        active_buttons: Optional[List[int]] = None,
+        d_pad_state: Tuple[int, int] = (0, 0),
+    ):
+        self.active_buttons: List[int] = active_buttons if active_buttons else []
+        self.d_pad_state: Tuple[int, int] = d_pad_state
+
+    def __repr__(self):
+        return self.__str__()
+
+    def __str__(self):
+        self.active_buttons.sort()
+        return f"<ControllerState active_buttons: {self.active_buttons}, d_pad_action: {self.d_pad_state}>"
+
+    def describe(self) -> str:
+        self.active_buttons.sort()
+        s = ",".join([button_mapper_inv[button] for button in self.active_buttons])
+        d_pad_action_description = d_pad_mapper_inv.get(self.d_pad_state, None)
+        s += (
+            "," + d_pad_action_description
+            if d_pad_action_description is not None
+            else ""
+        )
+
+        return f'<{s.removeprefix(",")}>'
+
+    def to_dict(self):
+        return {
+            "active_buttons": self.active_buttons,
+            "d_pad_state": self.d_pad_state,
+        }
+
+    @classmethod
+    def from_dict(cls, dict: Dict):
+
+        return cls(
+            active_buttons=dict["active_buttons"],
+            # tuples become lists during json conversion
+            d_pad_state=tuple(dict["d_pad_state"]),
+        )

controller_companion-0.4.0/controller_companion/logs.py

@@ -0,0 +1,15 @@
+import logging
+from rich.logging import RichHandler
+
+DEBUG = logging.DEBUG
+INFO = logging.INFO
+WARNING = logging.WARNING
+ERROR = logging.ERROR
+
+FORMAT = "%(message)s"
+logging.basicConfig(format=FORMAT, datefmt="[%X]", handlers=[RichHandler()])
+logger = logging.getLogger(__name__)
+
+
+def set_log_level(level):
+    logger.setLevel(level)

controller_companion-0.4.0/controller_companion/mapping.py

@@ -0,0 +1,67 @@
+from enum import Enum
+import subprocess
+from typing import Dict, List
+import pyautogui
+from controller_companion.controller_state import ControllerState
+
+
+class ActionType(Enum):
+    TASK_KILL_BY_NAME = "Kill by Name"
+    CONSOLE_COMMAND = "Console Command"
+    KEYBOARD_SHORTCUT = "Keyboard Shortcut"
+
+
+class Mapping:
+
+    def __init__(
+        self,
+        action_type: ActionType,
+        target: str,
+        controller_state: ControllerState,
+        name: str,
+    ):
+        self.name = name
+        self.action_type = action_type
+        self.target = target
+        self.controller_state = controller_state
+
+    def execute(self):
+        if self.action_type == ActionType.TASK_KILL_BY_NAME:
+            subprocess.run(["taskkill", "/im", self.target])
+        elif self.action_type == ActionType.KEYBOARD_SHORTCUT:
+            keys = self.target.split("+")
+
+            invalid_keys = [k for k in keys if not pyautogui.isValidKey(k)]
+            if invalid_keys:
+                print(
+                    f"Invalid keys provided as keyboard shortcuts! The following keys are invalid: {invalid_keys}"
+                )
+                return
+
+            pyautogui.hotkey(keys)
+        else:
+            subprocess.run(self.target)
+
+    def __str__(self):
+        return f"Controller{self.controller_state.describe()} --> Action<name: {self.name}, target: {self.target}, type: {self.action_type.name}>"
+
+    def to_dict(self):
+        return {
+            "name": self.name,
+            "action_type": self.action_type.name,
+            "target": self.target,
+            "controller_state": self.controller_state.to_dict(),
+        }
+
+    @classmethod
+    def from_dict(cls, dict: Dict):
+
+        return cls(
+            name=dict["name"],
+            target=dict["target"],
+            action_type=ActionType[dict["action_type"]],
+            controller_state=ControllerState.from_dict(dict["controller_state"]),
+        )
+
+    def get_valid_keyboard_keys() -> List[str]:
+        return pyautogui.KEYBOARD_KEYS

controller_companion-0.4.0/controller_companion/pyinstaller.py

@@ -0,0 +1,33 @@
+import platform
+import shutil
+import PyInstaller.__main__
+from pathlib import Path
+
+from controller_companion import VERSION
+from controller_companion.app import resources
+
+HERE = Path(__file__).parent.absolute()
+path_to_main = str(HERE / "app/app.py")
+
+
+def install():
+
+    PyInstaller.__main__.run(
+        [
+            path_to_main,
+            "--name",
+            "controller-companion",
+            "--windowed",
+            "--add-data",
+            "controller_companion/res:controller_companion/res",
+            "--icon",
+            str(resources.APP_ICON_ICO),
+            # remove question to override an existing output folder
+            "--noconfirm",
+        ]
+    )
+
+    # zip the pyinstaller output as an artifact
+    os_name = platform.system().replace("Darwin", "Mac").lower()
+    output_path = f"dist/controller-companion-{VERSION}-{os_name}"
+    shutil.make_archive(output_path, "zip", "dist/controller-companion")

controller_companion-0.4.0/pyproject.toml

@@ -0,0 +1,31 @@
+[tool.poetry]
+name = "controller-companion"
+version = "0.4.0"
+description = ""
+authors = [
+    "Johannes Gundlach <24914225+Johannes11833@users.noreply.github.com>",
+]
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = ">=3.9,<3.14"
+pygame = "^2.6.1"
+pystray = "^0.19.5"
+pillow = "^11.0.0"
+pyautogui = "^0.9.54"
+requests = "^2.32.3"
+rich = "^13.9.4"
+
+
+[tool.poetry.group.dev.dependencies]
+pyinstaller = "^6.11.1"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+
+[tool.poetry.scripts]
+controller_companion = "controller_companion.controller_observer:cli"
+controller_companion_ui = "controller_companion.app.app:cli"
+build = "controller_companion.pyinstaller:install"