1b877906bSopenharmony_ci<?xml version="1.0" encoding="UTF-8"?> 2b877906bSopenharmony_ci<protocol name="xdg_activation_v1"> 3b877906bSopenharmony_ci 4b877906bSopenharmony_ci <copyright> 5b877906bSopenharmony_ci Copyright © 2020 Aleix Pol Gonzalez <aleixpol@kde.org> 6b877906bSopenharmony_ci Copyright © 2020 Carlos Garnacho <carlosg@gnome.org> 7b877906bSopenharmony_ci 8b877906bSopenharmony_ci Permission is hereby granted, free of charge, to any person obtaining a 9b877906bSopenharmony_ci copy of this software and associated documentation files (the "Software"), 10b877906bSopenharmony_ci to deal in the Software without restriction, including without limitation 11b877906bSopenharmony_ci the rights to use, copy, modify, merge, publish, distribute, sublicense, 12b877906bSopenharmony_ci and/or sell copies of the Software, and to permit persons to whom the 13b877906bSopenharmony_ci Software is furnished to do so, subject to the following conditions: 14b877906bSopenharmony_ci 15b877906bSopenharmony_ci The above copyright notice and this permission notice (including the next 16b877906bSopenharmony_ci paragraph) shall be included in all copies or substantial portions of the 17b877906bSopenharmony_ci Software. 18b877906bSopenharmony_ci 19b877906bSopenharmony_ci THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 20b877906bSopenharmony_ci IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 21b877906bSopenharmony_ci FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 22b877906bSopenharmony_ci THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 23b877906bSopenharmony_ci LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 24b877906bSopenharmony_ci FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 25b877906bSopenharmony_ci DEALINGS IN THE SOFTWARE. 26b877906bSopenharmony_ci </copyright> 27b877906bSopenharmony_ci 28b877906bSopenharmony_ci <description summary="Protocol for requesting activation of surfaces"> 29b877906bSopenharmony_ci The way for a client to pass focus to another toplevel is as follows. 30b877906bSopenharmony_ci 31b877906bSopenharmony_ci The client that intends to activate another toplevel uses the 32b877906bSopenharmony_ci xdg_activation_v1.get_activation_token request to get an activation token. 33b877906bSopenharmony_ci This token is then forwarded to the client, which is supposed to activate 34b877906bSopenharmony_ci one of its surfaces, through a separate band of communication. 35b877906bSopenharmony_ci 36b877906bSopenharmony_ci One established way of doing this is through the XDG_ACTIVATION_TOKEN 37b877906bSopenharmony_ci environment variable of a newly launched child process. The child process 38b877906bSopenharmony_ci should unset the environment variable again right after reading it out in 39b877906bSopenharmony_ci order to avoid propagating it to other child processes. 40b877906bSopenharmony_ci 41b877906bSopenharmony_ci Another established way exists for Applications implementing the D-Bus 42b877906bSopenharmony_ci interface org.freedesktop.Application, which should get their token under 43b877906bSopenharmony_ci activation-token on their platform_data. 44b877906bSopenharmony_ci 45b877906bSopenharmony_ci In general activation tokens may be transferred across clients through 46b877906bSopenharmony_ci means not described in this protocol. 47b877906bSopenharmony_ci 48b877906bSopenharmony_ci The client to be activated will then pass the token 49b877906bSopenharmony_ci it received to the xdg_activation_v1.activate request. The compositor can 50b877906bSopenharmony_ci then use this token to decide how to react to the activation request. 51b877906bSopenharmony_ci 52b877906bSopenharmony_ci The token the activating client gets may be ineffective either already at 53b877906bSopenharmony_ci the time it receives it, for example if it was not focused, for focus 54b877906bSopenharmony_ci stealing prevention. The activating client will have no way to discover 55b877906bSopenharmony_ci the validity of the token, and may still forward it to the to be activated 56b877906bSopenharmony_ci client. 57b877906bSopenharmony_ci 58b877906bSopenharmony_ci The created activation token may optionally get information attached to it 59b877906bSopenharmony_ci that can be used by the compositor to identify the application that we 60b877906bSopenharmony_ci intend to activate. This can for example be used to display a visual hint 61b877906bSopenharmony_ci about what application is being started. 62b877906bSopenharmony_ci 63b877906bSopenharmony_ci Warning! The protocol described in this file is currently in the testing 64b877906bSopenharmony_ci phase. Backward compatible changes may be added together with the 65b877906bSopenharmony_ci corresponding interface version bump. Backward incompatible changes can 66b877906bSopenharmony_ci only be done by creating a new major version of the extension. 67b877906bSopenharmony_ci </description> 68b877906bSopenharmony_ci 69b877906bSopenharmony_ci <interface name="xdg_activation_v1" version="1"> 70b877906bSopenharmony_ci <description summary="interface for activating surfaces"> 71b877906bSopenharmony_ci A global interface used for informing the compositor about applications 72b877906bSopenharmony_ci being activated or started, or for applications to request to be 73b877906bSopenharmony_ci activated. 74b877906bSopenharmony_ci </description> 75b877906bSopenharmony_ci 76b877906bSopenharmony_ci <request name="destroy" type="destructor"> 77b877906bSopenharmony_ci <description summary="destroy the xdg_activation object"> 78b877906bSopenharmony_ci Notify the compositor that the xdg_activation object will no longer be 79b877906bSopenharmony_ci used. 80b877906bSopenharmony_ci 81b877906bSopenharmony_ci The child objects created via this interface are unaffected and should 82b877906bSopenharmony_ci be destroyed separately. 83b877906bSopenharmony_ci </description> 84b877906bSopenharmony_ci </request> 85b877906bSopenharmony_ci 86b877906bSopenharmony_ci <request name="get_activation_token"> 87b877906bSopenharmony_ci <description summary="requests a token"> 88b877906bSopenharmony_ci Creates an xdg_activation_token_v1 object that will provide 89b877906bSopenharmony_ci the initiating client with a unique token for this activation. This 90b877906bSopenharmony_ci token should be offered to the clients to be activated. 91b877906bSopenharmony_ci </description> 92b877906bSopenharmony_ci 93b877906bSopenharmony_ci <arg name="id" type="new_id" interface="xdg_activation_token_v1"/> 94b877906bSopenharmony_ci </request> 95b877906bSopenharmony_ci 96b877906bSopenharmony_ci <request name="activate"> 97b877906bSopenharmony_ci <description summary="notify new interaction being available"> 98b877906bSopenharmony_ci Requests surface activation. It's up to the compositor to display 99b877906bSopenharmony_ci this information as desired, for example by placing the surface above 100b877906bSopenharmony_ci the rest. 101b877906bSopenharmony_ci 102b877906bSopenharmony_ci The compositor may know who requested this by checking the activation 103b877906bSopenharmony_ci token and might decide not to follow through with the activation if it's 104b877906bSopenharmony_ci considered unwanted. 105b877906bSopenharmony_ci 106b877906bSopenharmony_ci Compositors can ignore unknown activation tokens when an invalid 107b877906bSopenharmony_ci token is passed. 108b877906bSopenharmony_ci </description> 109b877906bSopenharmony_ci <arg name="token" type="string" summary="the activation token of the initiating client"/> 110b877906bSopenharmony_ci <arg name="surface" type="object" interface="wl_surface" 111b877906bSopenharmony_ci summary="the wl_surface to activate"/> 112b877906bSopenharmony_ci </request> 113b877906bSopenharmony_ci </interface> 114b877906bSopenharmony_ci 115b877906bSopenharmony_ci <interface name="xdg_activation_token_v1" version="1"> 116b877906bSopenharmony_ci <description summary="an exported activation handle"> 117b877906bSopenharmony_ci An object for setting up a token and receiving a token handle that can 118b877906bSopenharmony_ci be passed as an activation token to another client. 119b877906bSopenharmony_ci 120b877906bSopenharmony_ci The object is created using the xdg_activation_v1.get_activation_token 121b877906bSopenharmony_ci request. This object should then be populated with the app_id, surface 122b877906bSopenharmony_ci and serial information and committed. The compositor shall then issue a 123b877906bSopenharmony_ci done event with the token. In case the request's parameters are invalid, 124b877906bSopenharmony_ci the compositor will provide an invalid token. 125b877906bSopenharmony_ci </description> 126b877906bSopenharmony_ci 127b877906bSopenharmony_ci <enum name="error"> 128b877906bSopenharmony_ci <entry name="already_used" value="0" 129b877906bSopenharmony_ci summary="The token has already been used previously"/> 130b877906bSopenharmony_ci </enum> 131b877906bSopenharmony_ci 132b877906bSopenharmony_ci <request name="set_serial"> 133b877906bSopenharmony_ci <description summary="specifies the seat and serial of the activating event"> 134b877906bSopenharmony_ci Provides information about the seat and serial event that requested the 135b877906bSopenharmony_ci token. 136b877906bSopenharmony_ci 137b877906bSopenharmony_ci The serial can come from an input or focus event. For instance, if a 138b877906bSopenharmony_ci click triggers the launch of a third-party client, the launcher client 139b877906bSopenharmony_ci should send a set_serial request with the serial and seat from the 140b877906bSopenharmony_ci wl_pointer.button event. 141b877906bSopenharmony_ci 142b877906bSopenharmony_ci Some compositors might refuse to activate toplevels when the token 143b877906bSopenharmony_ci doesn't have a valid and recent enough event serial. 144b877906bSopenharmony_ci 145b877906bSopenharmony_ci Must be sent before commit. This information is optional. 146b877906bSopenharmony_ci </description> 147b877906bSopenharmony_ci <arg name="serial" type="uint" 148b877906bSopenharmony_ci summary="the serial of the event that triggered the activation"/> 149b877906bSopenharmony_ci <arg name="seat" type="object" interface="wl_seat" 150b877906bSopenharmony_ci summary="the wl_seat of the event"/> 151b877906bSopenharmony_ci </request> 152b877906bSopenharmony_ci 153b877906bSopenharmony_ci <request name="set_app_id"> 154b877906bSopenharmony_ci <description summary="specifies the application being activated"> 155b877906bSopenharmony_ci The requesting client can specify an app_id to associate the token 156b877906bSopenharmony_ci being created with it. 157b877906bSopenharmony_ci 158b877906bSopenharmony_ci Must be sent before commit. This information is optional. 159b877906bSopenharmony_ci </description> 160b877906bSopenharmony_ci <arg name="app_id" type="string" 161b877906bSopenharmony_ci summary="the application id of the client being activated."/> 162b877906bSopenharmony_ci </request> 163b877906bSopenharmony_ci 164b877906bSopenharmony_ci <request name="set_surface"> 165b877906bSopenharmony_ci <description summary="specifies the surface requesting activation"> 166b877906bSopenharmony_ci This request sets the surface requesting the activation. Note, this is 167b877906bSopenharmony_ci different from the surface that will be activated. 168b877906bSopenharmony_ci 169b877906bSopenharmony_ci Some compositors might refuse to activate toplevels when the token 170b877906bSopenharmony_ci doesn't have a requesting surface. 171b877906bSopenharmony_ci 172b877906bSopenharmony_ci Must be sent before commit. This information is optional. 173b877906bSopenharmony_ci </description> 174b877906bSopenharmony_ci <arg name="surface" type="object" interface="wl_surface" 175b877906bSopenharmony_ci summary="the requesting surface"/> 176b877906bSopenharmony_ci </request> 177b877906bSopenharmony_ci 178b877906bSopenharmony_ci <request name="commit"> 179b877906bSopenharmony_ci <description summary="issues the token request"> 180b877906bSopenharmony_ci Requests an activation token based on the different parameters that 181b877906bSopenharmony_ci have been offered through set_serial, set_surface and set_app_id. 182b877906bSopenharmony_ci </description> 183b877906bSopenharmony_ci </request> 184b877906bSopenharmony_ci 185b877906bSopenharmony_ci <event name="done"> 186b877906bSopenharmony_ci <description summary="the exported activation token"> 187b877906bSopenharmony_ci The 'done' event contains the unique token of this activation request 188b877906bSopenharmony_ci and notifies that the provider is done. 189b877906bSopenharmony_ci </description> 190b877906bSopenharmony_ci <arg name="token" type="string" summary="the exported activation token"/> 191b877906bSopenharmony_ci </event> 192b877906bSopenharmony_ci 193b877906bSopenharmony_ci <request name="destroy" type="destructor"> 194b877906bSopenharmony_ci <description summary="destroy the xdg_activation_token_v1 object"> 195b877906bSopenharmony_ci Notify the compositor that the xdg_activation_token_v1 object will no 196b877906bSopenharmony_ci longer be used. The received token stays valid. 197b877906bSopenharmony_ci </description> 198b877906bSopenharmony_ci </request> 199b877906bSopenharmony_ci </interface> 200b877906bSopenharmony_ci</protocol> 201