desktop_actions_experimental_v1
This protocol allows a client to advertise some actions it can perform, and lets the compositor trigger them directly.
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:
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.
xx_desktop_actions_v1
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.
set_available_universal_actions(available_actions: array)
Argument | Type | Description |
|---|---|---|
| available_actions | array | available actions |
Announces the actions available to trigger.
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.
Values in the available_actions array come from the .universal_action enum.
add_available_app_action(name: string, handle: uint, existing_trigger: string)
Argument | Type | Description |
|---|---|---|
| name | string | Human-readable description |
| handle | uint | Handle to trigger the action |
| existing_trigger | string | Optional trigger description 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}. 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. |
Adds an application-specific actions to the available list.
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 .commit request. The "app_action" set persists until the client exits.
The initial value is an empty set: no actions are available.
universal_action { cut, copy, paste, paste_unformatted, paste_formatted, input_next, input_previous, document_new, document_open, document_reload, document_save, document_save_as, document_close, document_previous, document_next, document_share, search, search_previous, search_next, undo, redo, confirm, reject, fullscreen_toggle, fullscreen_enter, fullscreen_leave, magnify_reset, magnify_bigger, magnify_smaller, navigate_back, navigate_forward, start, pause, stop, details, remove_selected, select_all, select_none, select, print, insert, menu, help, break }
Argument | Value | Description |
|---|---|---|
| cut | 0 | Cut into clipboard |
| copy | 0 | Copy into clipboard |
| paste | 0 | Paste from clipboard |
| paste_unformatted | 0 | Paste from clipboard, specifically without formatting |
| paste_formatted | 0 | Paste from clipboard, specifically trying to retain formatting |
| input_next | 0 | Focus next intractive element |
| input_previous | 0 | Focus previous interactive element |
| document_new | 0 | New document |
| document_open | 0 | Select a document to open |
| document_reload | 0 | Reload current document |
| document_save | 0 | Save current document |
| document_save_as | 0 | Save current document into a new copy |
| document_close | 0 | Close current document |
| document_previous | 0 | Switch to previous document |
| document_next | 0 | Switch to next document |
| document_share | 0 | share current |
| search | 0 | Begin search |
| search_previous | 0 | Go to previous search result |
| search_next | 0 | Go to next search result |
| undo | 0 | Undo previous action |
| redo | 0 | Repeat following action |
| confirm | 0 | Ok, confirm, accept, yes |
| reject | 0 | Reject, cancel, no |
| fullscreen_toggle | 0 | Toggle fullscreen mode |
| fullscreen_enter | 0 | Enter fullscreen mode |
| fullscreen_leave | 0 | Enter fullscreen mode |
| magnify_reset | 0 | Use default magnification level |
| magnify_bigger | 0 | Zoom in |
| magnify_smaller | 0 | Zoom out |
| navigate_back | 0 | Select previous view or go back in hierarchy |
| navigate_forward | 0 | Select next view, go forward in hierarchy, follow current link |
| start | 0 | Start activity, execute, run |
| pause | 0 | Stop activity, allowing to resume |
| stop | 0 | Stop activity, without possibility to resume |
| details | 0 | Display details, document properties |
| remove_selected | 0 | Remove or delete selected item(s) |
| select_all | 0 | Select all items |
| select_none | 0 | Clear selection |
| select | 0 | Select, mark item(s) |
| 0 | Print document | |
| insert | 0 | Insert, insert here |
| menu | 0 | menu |
| help | 0 | View help |
| break | 0 | break |
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.
Compositor Support
Copyright
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.