From 17032d510553bbc83574aafd2d35eafc0506e840 Mon Sep 17 00:00:00 2001 From: dcz Date: Thu, 4 Dec 2025 14:29:25 +0000 Subject: [PATCH 1/4] draft experimental desktop actions --- experimental/xx-desktop-actions/README | 4 + .../xx-desktop-actions-v1.xml | 191 ++++++++++++++++++ 2 files changed, 195 insertions(+) create mode 100644 experimental/xx-desktop-actions/README create mode 100644 experimental/xx-desktop-actions/xx-desktop-actions-v1.xml diff --git a/experimental/xx-desktop-actions/README b/experimental/xx-desktop-actions/README new file mode 100644 index 0000000..db5a363 --- /dev/null +++ b/experimental/xx-desktop-actions/README @@ -0,0 +1,4 @@ +Desktop actions protocol + +Maintainers: +Dorota Czaplejewicz \ No newline at end of file diff --git a/experimental/xx-desktop-actions/xx-desktop-actions-v1.xml b/experimental/xx-desktop-actions/xx-desktop-actions-v1.xml new file mode 100644 index 0000000..f053db6 --- /dev/null +++ b/experimental/xx-desktop-actions/xx-desktop-actions-v1.xml @@ -0,0 +1,191 @@ + + + + + Copyright 2018 Mike Blumenkrantz + Copyright 2018 Samsung Electronics Co., Ltd + Copyright 2018 Red Hat Inc. + Copyright 2025 DorotaC + + 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 (including the next + paragraph) 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. + + + + This protocol allows a client to advertise some actions it can perform, and lets the compositor trigger them directly. + + It aims to improve on the problem of shortcut shadowing: when + + That directness of triggering actions is the main point of this protocol. Traditionally, the way an action is triggered is a keyboard combinations or a mouse motion. That is then interpreted by the application. + In order to trigger such an action without a keyboard or a mouse, a keyboard or mouse must be emulated. That's an unnecessary difficulty affecting on-screen input methods. + An application supporting desktop-actions lets the input method trigger shortcuts without the emulation baggage. + + This protocol can be implemented on its own if the compositor wishes to trigger the actions directly. It can also be accompanied by an "input" protocol to let other applications trigger actions, similar to how input methods submit text. + + High-level overview of the interfaces: + + The desktop_actions_manager exposes the bind_to_input_method request which binds a wl_keyboard to an xx_input_method. + The resulting keyboard_filter object has the can be then used for intercepting keyboard events in accordance to input method needs. + + This document adheres to the RFC 2119 when using words like "must", + "should", "may", etc. + + Warning! The protocol described in this file is currently in the + experimental phase. Backwards incompatible major versions of the + protocol are to be expected. Exposing this protocol without an opt-in + mechanism is discouraged. + + + + + Advertise and trigger actions executed by a seat. + + The ability to input actions follows keyboard focus. + + The application may ignore events which arrive while it is not holding keyboard focus. + + + + + This enum is for actions that are very often seen in different kinds of applications, with shortcuts ingrained into a collective hacker memory so deep they are almost standardized. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Announces the actions available to trigger. + + Values set with this event are double-buffered. They will get applied + on the next .done event. + They get reset to the initial value on every keyboard .enter event. + + The initial value is an empty set: no actions are available. + + Values in the available_actions array come from the .universal_action enum. + + + + + + + + + + The compositor requested a universal action to be performed. + + Values set with this event are double-buffered. They must be applied + and reset to initial on the next .done event. + + The initial value of action is none. + + The application should not perform an action it didn't advertise in the most recent `available_actions`. + + + + + + + Destroys the desktop_actions object. + + + + + + + A factory for desktop actions objects. This object is a global singleton. + + + + + Creates a new desktop actions object for a given seat. + + + + + + + + Destroys the xx_desktop_actions_manager_v1 object. + + The xx_desktop_actions_v1 objects originating from it remain unaffected. + + + + From f1fc36e03f63de334d2bc5899ff7b8ce6bd1debb Mon Sep 17 00:00:00 2001 From: dcz Date: Thu, 4 Dec 2025 15:56:44 +0000 Subject: [PATCH 2/4] desktop actions: Add application-specific actions Modeled on xdg-desktop-portal Global Shortcuts spec. --- .../xx-desktop-actions-v1.xml | 118 ++++++++++++++++-- 1 file changed, 110 insertions(+), 8 deletions(-) diff --git a/experimental/xx-desktop-actions/xx-desktop-actions-v1.xml b/experimental/xx-desktop-actions/xx-desktop-actions-v1.xml index f053db6..8bf41df 100644 --- a/experimental/xx-desktop-actions/xx-desktop-actions-v1.xml +++ b/experimental/xx-desktop-actions/xx-desktop-actions-v1.xml @@ -27,15 +27,16 @@ DEALINGS IN THE SOFTWARE. + This protocol allows a client to advertise some actions it can perform, and lets the compositor trigger them directly. - It aims to improve on the problem of shortcut shadowing: when - That directness of triggering actions is the main point of this protocol. Traditionally, the way an action is triggered is a keyboard combinations or a mouse motion. That is then interpreted by the application. In order to trigger such an action without a keyboard or a mouse, a keyboard or mouse must be emulated. That's an unnecessary difficulty affecting on-screen input methods. An application supporting desktop-actions lets the input method trigger shortcuts without the emulation baggage. + This protocol also helps avoid clashing shortcuts by letting the compositor detect what the application expects and by assigning another shortcut if it knows of any collisions. + This protocol can be implemented on its own if the compositor wishes to trigger the actions directly. It can also be accompanied by an "input" protocol to let other applications trigger actions, similar to how input methods submit text. High-level overview of the interfaces: @@ -141,24 +142,125 @@ Values in the available_actions array come from the .universal_action enum. + + + + + + + Adds an application-specific actions to the available list. + + This adds an action to the compositor's "app_action" set. + + Values set with this event are double-buffered. They will get applied + on the next .done event. + The "app_action" set gets reset to the initial value on .done and on every keyboard .enter event. + + The initial value is an empty set: no actions are available. + + + + + + Suggestion to the compositor to assign a particular trigger. + + If the string is not empty, it takes the form {format}:{trigger}, where {trigger} is a string defined by {format}. + + Currently supported formats: + + "xdg", with trigger specified in https://specifications.freedesktop.org/shortcuts/latest/ . + + + + Formats not recognized by the compositor must be ignored. + + Multiple suggestions may be present. Multiple suggestions must be separated by newline characters. + + + + + + + Applies the values of available_actions and stores the "app_action" list. + + + The compositor requested a universal action to be performed. - - Values set with this event are double-buffered. They must be applied - and reset to initial on the next .done event. - - The initial value of action is none. - The application should not perform an action it didn't advertise in the most recent `available_actions`. + The application should ignore this request if it didn't advertise the action in the most recent `available_actions`. + + + + Notifies the application about the shortcut(s) the compositor will actually use to trigger the action. + + This is intended for the application to display user-readable hints in-application, e.g. when clicking "File" menu, there's "New Window: Ctrl+Shift+N". + + The compositor may assign multiple shortcuts to the action, see {number} in the description of the trigger argument. + + The application must ignore this request if it didn't advertise the handle in the most recently submitted "app_action" set. + + + + + The description follows the format: + {number}:{format}:{trigger} + where {number} is the ordinal number of the shortcut. + + An additional {format} is available: + + "text", where trigger is a textual, human-readable description. + + + + + + The compositor requested an app-specific action to be performed. + + The application must ignore this request if it didn't advertise the handle in the most recently submitted "app_action" set. + + + From 0d3bb59d23643a7caac10eb30f22abfb221e565b Mon Sep 17 00:00:00 2001 From: dcz Date: Fri, 5 Dec 2025 18:26:34 +0000 Subject: [PATCH 3/4] Who actually triggers the shortcut? --- .../xx-desktop-actions-v1.xml | 92 ++++++++++++++++--- 1 file changed, 81 insertions(+), 11 deletions(-) diff --git a/experimental/xx-desktop-actions/xx-desktop-actions-v1.xml b/experimental/xx-desktop-actions/xx-desktop-actions-v1.xml index 8bf41df..e93c2d7 100644 --- a/experimental/xx-desktop-actions/xx-desktop-actions-v1.xml +++ b/experimental/xx-desktop-actions/xx-desktop-actions-v1.xml @@ -133,8 +133,8 @@ Announces the actions available to trigger. - Values set with this event are double-buffered. They will get applied - on the next .done event. + Values set with this request are double-buffered. They will get applied + on the next .commit request. They get reset to the initial value on every keyboard .enter event. The initial value is an empty set: no actions are available. @@ -178,19 +178,23 @@ Adds an application-specific actions to the available list. - This adds an action to the compositor's "app_action" set. + Conceptually, this adds an action to the compositor's "app_action" set. Values set with this event are double-buffered. They will get applied - on the next .done event. - The "app_action" set gets reset to the initial value on .done and on every keyboard .enter event. + on the next .commit request. + The "app_action" set persists until the client exits. The initial value is an empty set: no actions are available. - + - Suggestion to the compositor to assign a particular trigger. + Describes the default trigger(s) for this action. + + The compositor should attempt to use this trigger. + + The empty string means the trigger has no keyboard shortcut. Upon receiving, the compositor may not assign one. If the string is not empty, it takes the form {format}:{trigger}, where {trigger} is a string defined by {format}. @@ -210,10 +214,18 @@ - - + + + The application no longer needs this action. + + This remove the shortcut from "app_action" list. + + + + + Applies the values of available_actions and stores the "app_action" list. @@ -230,17 +242,61 @@ + + + + + + + The compositor takes over the responsibility for triggering the keyboard action. + + This allows the compositor to resolve keyboard shortcut conflicts. + + The application must stop reacting to keyboard shortcuts triggering this action. + + If an "xkb" trigger is not provided, the client must discard the old shortcut. + + + + - Notifies the application about the shortcut(s) the compositor will actually use to trigger the action. + Notifies the application which shortcut(s) the compositor will actually use to trigger the action. This is intended for the application to display user-readable hints in-application, e.g. when clicking "File" menu, there's "New Window: Ctrl+Shift+N". The compositor may assign multiple shortcuts to the action, see {number} in the description of the trigger argument. - + + If the shortcut needs to be triggered for an input method or an automation, setting no flag is appropriate. + The application must ignore this request if it didn't advertise the handle in the most recently submitted "app_action" set. + + Sending this request always replaces the old value. + + The value persists until the client disconnects. + + + Once assigned, the compositor should save the assignments and use them the next time the client connects. + The description follows the format: @@ -250,14 +306,28 @@ An additional {format} is available: "text", where trigger is a textual, human-readable description. + + If this string is empty, the old shortcut remains unmodified. + + + This marks all unassigned actions with an empty trigger string and none flag.. + + In practice, any compositor which resolves shortcut conflicts is going to (re)assign all actions with a default shortcut, to make sure the application doesn't react to something already triggering an action on the compositor side. + + The compositor must send this in order for shortcut assignments to become active. + + + The compositor requested an app-specific action to be performed. The application must ignore this request if it didn't advertise the handle in the most recently submitted "app_action" set. + + The application must ignore this request if the compositor didn't assign the shortcuts using .assign_action_finish. From 7384a1b3ce83d199c96b22e42255447a12cb1885 Mon Sep 17 00:00:00 2001 From: dcz Date: Fri, 5 Dec 2025 18:44:54 +0000 Subject: [PATCH 4/4] how to deal with conflicts? input methods? --- .../xx-desktop-actions-v1.xml | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/experimental/xx-desktop-actions/xx-desktop-actions-v1.xml b/experimental/xx-desktop-actions/xx-desktop-actions-v1.xml index e93c2d7..94fda7b 100644 --- a/experimental/xx-desktop-actions/xx-desktop-actions-v1.xml +++ b/experimental/xx-desktop-actions/xx-desktop-actions-v1.xml @@ -268,6 +268,8 @@ This allows the compositor to resolve keyboard shortcut conflicts. + The client should use the assigned keyboard shortcut desctiption instead of its internal default. + The application must stop reacting to keyboard shortcuts triggering this action. If an "xkb" trigger is not provided, the client must discard the old shortcut. @@ -277,15 +279,13 @@ - Notifies the application which shortcut(s) the compositor will actually use to trigger the action. + Notifies the client which shortcut(s) the compositor will actually use to trigger the action. - This is intended for the application to display user-readable hints in-application, e.g. when clicking "File" menu, there's "New Window: Ctrl+Shift+N". + This is intended to disable conflicting shortcuts and for the client to display user-readable hints in-application, e.g. when clicking "File" menu, there's "New Window: Ctrl+Shift+N". The compositor may assign multiple shortcuts to the action, see {number} in the description of the trigger argument. - If the shortcut needs to be triggered for an input method or an automation, setting no flag is appropriate. - - The application must ignore this request if it didn't advertise the handle in the most recently submitted "app_action" set. + The client must ignore this request if it didn't advertise the handle in the most recently submitted "app_action" set. Sending this request always replaces the old value. @@ -294,9 +294,15 @@ It would be bad if our shortcut was stolen (by compositor itself? by a global shortcut?) while our window was out of focus. The user shouldn't need to check every time.--> Once assigned, the compositor should save the assignments and use them the next time the client connects. + + Examples: + + If the shortcut needs to be triggered for an input method or an automation, setting flags to none is appropriate. The compositor can then put a description in "text", which the client could display where appropriate. + + If the shortcut is assigned to get rid of a shortcut conflict, the compositor will want the replace_keyboard flag on all the conflicts to disable previous combos. The action then remains triggerable by an input method. - + The description follows the format: