Skip to content

feat: Actions Ring for the MX Master 4 - #183

Open
schultz-dev0 wants to merge 7 commits into
mmaher88:masterfrom
schultz-dev0:feature/actions-ring
Open

schultz-dev0 wants to merge 7 commits into
mmaher88:masterfrom
schultz-dev0:feature/actions-ring

Conversation

@schultz-dev0

Copy link
Copy Markdown

Added the actions ring for the MX Master 4, reverse engineered (sorta) the Actions Ring from Options+

  • Ring overlay, should work on any Wayland system but not tested, needs to be tested outside of hyprland. Hyprland cursor lookup via hyprctl and if not available then go to first pointer move. Submenus work, hold to select and haptic pulse via HID++ 0x19b0
  • App profiles with a full page editor (changed the UI code, it's still rough, didn't want to mess with it TOO much)
  • Haptics page, feedback strength, thumb panel press force per device at 0x19C0
  • Fix, profile wasn't reapplied after a reconnect suspend because the device wasn't selected yet.

This builds on #171.

All tests pass, tested on MX Master 4 over Bolt on Hyprland

Merge is a little dangerous, I thought the project was abandoned so just forked for personal use.

Please carefully review all code, raise any major issues to me, I can fix whatever needs to be fixed or changed for compatibility etc.

A second launch used to fail the instance lock and exit silently while the first instance sat hidden. It now asks the running instance to show its window and exits 0. Without a tray, closing the window quits instead of hiding.
Closing the window destroys the UI and keeps devices, profiles, the tray and the single-instance server running, with or without a tray. Launching again rebuilds the window. --minimized starts without building it at all. Add --quit and a Quit button in Settings so the app can be ended without a tray.
A radial menu at the cursor, opened by the MX Master 4 haptic button (CID 0x01A0) or logitune --show-ring. Slots are per profile and use the existing action types or a submenu; hover and select play haptic pulses through a new 0x19B0 capability. Hold the trigger past 500 ms and release to select. The overlay uses LayerShellQt when available and asks Hyprland for the cursor position, falling back to the first pointer movement. Colours follow the app theme, overridable with ~/.config/Logitune/actions-ring-theme.json.
… adjuster

Replace the form-style ring editor with a page built around a live ring preview and an action library: drag an action onto a bubble (or select a bubble and click one), swap bubbles, add submenu children, undo/redo, per-application rings from the profile strip, and the ring size under the cog. Labels sit beside their bubbles; submenu children's labels go outward.

New actions: Custom command (any shell command, run through sh, with its own name and icon) and Volume, an adjuster you hover and scroll on the ring (click mutes). Adjusters store up/down/read/press commands in the slot and read the level only after each change finishes.

Icons can be Nerd Font glyphs, theme icon names, or image files including animated GIFs, picked from a themed in-app browser with thumbnails. Open URL adds https:// when the address has no scheme. ActionModel.get() and ProfileModel.wmClassAt() replace raw role numbers in QML.
…inary

Ring.qml and RingPreview.qml imported RingGeometry.js by relative path. That clashed with "import Logitune" in an installed build, where the module exists only inside the binary (qrc), and the ring overlay failed to load; local builds worked because Qt also found the module folder on disk next to the binary. The three geometry helpers now live in the two files that use them.
A Haptics page for mice that report HID++ 0x19B0 (haptics) or 0x19C0 (force-sensing button): turn feedback on or off, set its strength, and set how hard the MX Master 4's thumb panel must be pressed. Both are settings of the mouse, not of an application profile; they're saved per device in devices/<serial>/panel.conf and reapplied on every connect. Sliders write when released.

Also move the MX Master 4 haptic button's callout between Forward and Back, where it no longer overlaps Back, and add the QML modules the ring editor now needs (folderlistmodel, QtCore) to the Debian dependency lists.
PhysicalDevice announced transportSetupComplete before stateChanged. On a reconnect the device model only reselects the device on stateChanged, so the profile was reapplied with nothing selected and skipped: button diversions (the Actions Ring trigger included), DPI and SmartShift were lost after every suspend or power cycle. Emit stateChanged first, and log when a reapply is skipped.
@schultz-dev0

Copy link
Copy Markdown
Author
screenshot-popup-1794262105767510075 screenshot-popup-1794262137325075268

Has support for gifs, websites, commands etc.

@Dexarim

Dexarim commented Nov 15, 2026

Copy link
Copy Markdown

Hi @schultz-dev0 — thanks for sharing this. I’m working on the Action Ring in the split PR series #178 and #182, following the maintainer’s review feedback. Your implementation overlaps substantially, and the Hyprland cursor source, submenus, hold-to-select behavior, HID++ haptics, adjusters, and full-page editor are especially valuable.

Would you be open to coordinating and having us adapt/reuse those parts in the split series, with clear attribution/co-authorship, instead of maintaining two competing implementations? To fit the existing review requirements, we would likely need to put Hyprland cursor lookup and placement behind IDesktopIntegration, preserve the per-device routing introduced in #174, and store the ring as individual INI keys rather than the ActionsRing/slots JSON blob.

If that sounds good, which commits or components do you think are safest to extract first, and would you prefer cherry-picks or separate follow-up PRs?

@schultz-dev0

Copy link
Copy Markdown
Author

Yeah the hyprland cursor look up was my lazy workaround, it needs to be put behind your cursor spotter. You're best off just taking whichever features from mine you like and cheerry picking them into #178 and #182. I don't mind how you handle it at all.

I will say you should preserve my method of interaction and my submenu interaction. Took me a while to get it right by comparing the options+ and logitune through a VM.

So just a breakdown of what you should keep, its all in Ring.qml:

  • Each slots hover are is much bigger than the drawn button itself so that precise movement is not needed to select an icon. The center has a small deadzone, I would probabably tweak that deadzone, I had a few issues quickly closing the menu.
  • Once a submenu is open anything more than 30% of the way from the main ring to the outer ring belongs to the submenu (again this is basically extracted from options+).
  • Holding the button past 500ms and releasing selects whatever you hovered over. clicking a parent only keeps it's submenu open, clicking an adjuster runs it's press command (this is specific to my system kinda, like clicking on the volume adjuster will mute/unmute)

Notes:

  • Don't import RingGeometry.js by relative pasth because it breaks in installed builds where logitune only exists in qrc.
  • The ring editor needs the folderlistmodel and QtCore QML modules, I put em in the Debian deps list.

IMPORTANT:

  • Custom commands and adjuster actions run arbitrary shell commands through sh stored in the slot, that needs a security oriented look because like, this is a potential vulnerability, there are no limits as to what code it can run.

Other:

  • Haptics page uses HID++ 0x19B0 haptics and 0x19C0 force sensing for MX Master 4 thumb panel, it's stored per device in devices//panel.conf and reapplied on connect, sometimes it may not reapply if you have another mouse plugged in, also worth a look. It's actually a bug on master too btw.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants