-
-
Notifications
You must be signed in to change notification settings - Fork 183
/
org.freedesktop.impl.portal.InputCapture.xml
388 lines (311 loc) · 16.3 KB
/
org.freedesktop.impl.portal.InputCapture.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
<?xml version="1.0"?>
<!--
Copyright (C) 2022 Red Hat, Inc.
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library. If not, see <http://www.gnu.org/licenses/>.
-->
<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
<!--
org.freedesktop.impl.portal.InputCapture:
@short_description: Capture input portal backend interface
The Capture Input portal allows clients to capture input from local
devices. This portal is mostly a 1:1 mapping of the
:ref:`org.freedesktop.portal.InputCapture` portal, see that portal's
documentation for details on methods, signals and arguments.
This documentation describes version 1 of this interface.
-->
<interface name="org.freedesktop.impl.portal.InputCapture">
<!--
CreateSession:
@handle: Object path for the :ref:`org.freedesktop.impl.portal.Request` object representing this call
@session_handle: Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session being created
@app_id: App id of the application
@parent_window: Identifier for the application window, see :doc:`window-identifiers`
@options: Vardict with optional further information
@response: Numeric response
@results: Vardict with the results of the call
Create a capture input session.
Supported keys in the @options vardict include:
* ``capabilities`` (``u``)
Bitmask of requested capabilities, see the
SupportedCapabilities property. This value is required.
The following results get returned in the @results vardict:
* ``session_id`` (``s``)
The session id. A string representing the created capture input session.
* ``capabilities`` (``u``)
The capabilities available to this session. This is always a
subset of the requested capabilities.
-->
<method name="CreateSession">
<arg type="o" name="handle" direction="in"/>
<arg type="o" name="session_handle" direction="in"/>
<arg type="s" name="app_id" direction="in"/>
<arg type="s" name="parent_window" direction="in"/>
<annotation name="org.qtproject.QtDBus.QtTypeName.In3" value="QVariantMap"/>
<arg type="a{sv}" name="options" direction="in"/>
<arg type="u" name="response" direction="out"/>
<annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
<arg type="a{sv}" name="results" direction="out"/>
</method>
<!--
GetZones:
@handle: Object path for the :ref:`org.freedesktop.impl.portal.Request` object representing this call
@session_handle: Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session
@app_id: App id of the application
@options: Vardict with optional further information
@response: Numeric response
@results: Vardict with the results of the call
Return the current zones for this session.
The following results get returned in the @results vardict:
* ``zones`` (``a(uuii)``)
An array of zones with width, height, x-offset, y-offset.
* ``zone_set`` (``u``)
The zone_set ID required in
org.freedesktop.impl.portal.InputCapture.SetPointerBarriers().
-->
<method name="GetZones">
<arg type="o" name="handle" direction="in"/>
<arg type="o" name="session_handle" direction="in"/>
<arg type="s" name="app_id" direction="in"/>
<annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
<arg type="a{sv}" name="options" direction="in"/>
<arg type="u" name="response" direction="out"/>
<annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
<arg type="a{sv}" name="results" direction="out"/>
</method>
<!--
SetPointerBarriers:
@handle: Object path for the :ref:`org.freedesktop.impl.portal.Request` object representing this call
@session_handle: Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session
@app_id: App id of the application
@options: Vardict with optional further information
@barriers: An array of vardicts, each specifying one barrier
@zone_set: A unique ID referring to the zone set
@response: Numeric response
@results: Vardict with the results of the call
Set up zero or more pointer barriers.
Supported keys in the @barriers vardicts include:
* ``barrier_id`` (``u``)
The non-zero id of this barrier. This id is used in the
#org.freedesktop.portal.impl.InputCapture::Activated signal to inform
which barrier triggered input capture.
* ``position`` (``(iiii)``)
The x1/y1 x2/y2 position of the pointer barrier. A horizontal
pointer barrier must have y1 == y2, a vertical pointer barrier
must have x1 == x2. Diagonal pointer barriers are not supported.
The following results get returned in the @results vardict:
* ``failed_barriers`` (``au``)
An array of barrier_ids of pointer barriers that have been denied. The
id matches the barrier_id of the entries in the @barriers argument.
-->
<method name="SetPointerBarriers">
<arg type="o" name="handle" direction="in"/>
<arg type="o" name="session_handle" direction="in"/>
<arg type="s" name="app_id" direction="in"/>
<annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
<arg type="a{sv}" name="options" direction="in"/>
<arg type="aa{sv}" name="barriers" direction="in"/>
<arg type="u" name="zone_set" direction="in"/>
<arg type="u" name="response" direction="out"/>
<annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
<arg type="a{sv}" name="results" direction="out"/>
</method>
<!--
Enable:
@session_handle: Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session
@app_id: App id of the application
@options: Vardict with optional further information
Enable input capturing.
-->
<method name="Enable">
<arg type="o" name="session_handle" direction="in"/>
<arg type="s" name="app_id" direction="in"/>
<annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
<arg type="a{sv}" name="options" direction="in"/>
<arg type="u" name="response" direction="out"/>
<annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
<arg type="a{sv}" name="results" direction="out"/>
</method>
<!--
Disable:
@session_handle: Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session
@app_id: App id of the application
@options: Vardict with optional further information
Disable input capturing.
-->
<method name="Disable">
<arg type="o" name="session_handle" direction="in"/>
<arg type="s" name="app_id" direction="in"/>
<annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
<arg type="a{sv}" name="options" direction="in"/>
<arg type="u" name="response" direction="out"/>
<annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
<arg type="a{sv}" name="results" direction="out"/>
</method>
<!--
Release:
@session_handle: Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session
@app_id: App id of the application
@options: Vardict with optional further information
Release ongoing input capturing.
Supported keys in the @options vardict include:
* ``activation_id`` (``u``)
The same activation_id number as in the
#org.freedesktop.impl.portal.InputCapture::Activated signal.
* ``cursor_position`` (``(dd)``)
The suggested cursor position within the Zones available in
this session.
This is a suggestion to the compositor to place the cursor in
the correct position to allow for fluent movement between virtual
screens. The compositor is not required to honor this suggestion.
-->
<method name="Release">
<arg type="o" name="session_handle" direction="in"/>
<arg type="s" name="app_id" direction="in"/>
<annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
<arg type="a{sv}" name="options" direction="in"/>
<arg type="u" name="response" direction="out"/>
<annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
<arg type="a{sv}" name="results" direction="out"/>
</method>
<!--
ConnectToEIS:
@session_handle: Object path for the :ref:`org.freedesktop.portal.Session` object
@app_id: App id of the application
@options: Vardict with optional further information
@fd: A file descriptor to an EIS implementation that can be passed to a passive libei context
Set up the connection to an EIS implementation. Once input capturing starts,
input events are sent via the EI protocol between the compositor and the application.
This call must be invoked before :ref:`org.freedesktop.portal.InputCapture.Enable`.
A session only needs to set this up once, the EIS implementation is not affected by
calls to Disable() and :ref:`org.freedesktop.portal.InputCapture.Enable` -
the same context can be re-used until the session is closed.
-->
<method name="ConnectToEIS">
<annotation name="org.gtk.GDBus.C.UnixFD" value="true"/>
<arg type="o" name="session_handle" direction="in"/>
<arg type="s" name="app_id" direction="in"/>
<annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
<arg type="a{sv}" name="options" direction="in"/>
<arg type="h" name="fd" direction="out"/>
</method>
<!--
Disabled:
@session_handle: Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session
@options: Vardict with optional further information
The Disabled signal is emitted when the application will no longer
receive captured input. If input capturing is currently ongoing, the
#org.freedesktop.impl.portal.InputCapture::Deactivated signal is emitted
before this signal.
-->
<signal name="Disabled">
<arg type="o" name="session_handle" direction="out"/>
<arg type="a{sv}" name="options" direction="out"/>
</signal>
<!--
Activated:
@session_handle: Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session
@options: Vardict with optional further information
The Activated signal is emitted when input capture starts and input events
are about to be sent to the application.
This signal is only emitted after a prior call
to org.freedesktop.impl.portal.InputCapture.Enable().
Supported keys in the @options vardict include:
* ``activation_id`` (``u``)
A number that can be used to synchronize with the
transport-layer. This number has no intrinsic meaning but
is guaranteed to increase by an unspecified amount on each call.
In particular: if the compositor sends an activation_id of N as
part of this request it will also set the sequence in EIS'
start_emulating event the same value N on the EIS connection
before the first event from a device is sent.
This allows an application to have a synchronization point and
attribute an event sequence to the portal interaction.
Applications must be able to handle the activation_id number wrapping
around. Implementations of this portal must to increase the
activation_id number by an sensible amount to allow for wrapping
detection.
* ``cursor_position`` (``(dd)``)
The current cursor position. Note that this position may be
outside the Zones available to this session - this indicates
movement larger than a single pixel.
For example, a fast movement against a barrier on the right edge
of a screen may logically put the cursor dozens of pixels into
the (non-existing) screen on the other side of the barrier.
It is the application's responsibility to adjust the cursor
position as necessary.
* ``barrier_id`` (``u``)
The barrier id of the barrier that triggered. If the value is
nonzero, it matches the barrier id as specified in
org.freedesktop.impl.portal.InputCapture.SetPointerBarriers().
If the id is zero, the pointer barrier could be determined.
If the id is missing, the input capture was not triggered by a
pointer barrier.
Where more than one pointer barrier are triggered by the same
movement it is up to the compositor to choose one barrier (or use
a barrier id of zero).
-->
<signal name="Activated">
<arg type="o" name="session_handle" direction="out"/>
<arg type="a{sv}" name="options" direction="out"/>
</signal>
<!--
Deactivated:
@session_handle: Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session
@options: Vardict with optional further information
The Deactivated signal is emitted when input capture stopped and input events
are no longer sent to the application. To prevent future input
capture, an application must call :ref:`org.freedesktop.portal.InputCapture.Disable`.
Supported keys in the @options vardict include:
* ``activation_id`` (``u``)
The same activation_id as in the corresponding
#org.freedesktop.impl.portal.InputCapture::Activated signal.
* ``cursor_position`` (``(dd)``)
The current cursor position. Note that this position may be
outside the Zones available to this session - this indicates
movement larger than a single pixel.
For example, a fast movement against a barrier on the right edge
of a screen may logically put the cursor dozens of pixels into
the (non-existing) screen on the other side of the barrier.
It is the application's responsibility to adjust the cursor
position as necessary.
-->
<signal name="Deactivated">
<arg type="o" name="session_handle" direction="out"/>
<arg type="a{sv}" name="options" direction="out"/>
</signal>
<!--
ZonesChanged:
@session_handle: Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session
@options: Vardict with optional further information
The ZonesChanged signal is emitted when one or more of the zones
available **to this session** change. An application should immediately call
:ref:`org.freedesktop.portal.InputCapture.GetZones` to update its state of the zones.
-->
<signal name="ZonesChanged">
<arg type="o" name="session_handle" direction="out"/>
<arg type="a{sv}" name="options" direction="out"/>
</signal>
<!--
SupportedCapabilities:
A bitmask of supported capabilities. This list is constant, it is not the list of
capabilities currently available but rather which capabilies are
implemented by the portal.
Applications must ignore unknown capabilities.
Currently defined types are:
- ``1``: KEYBOARD
- ``2``: POINTER
- ``4``: TOUCHSCREEN
-->
<property name="SupportedCapabilities" type="u" access="read"/>
<property name="version" type="u" access="read"/>
</interface>
</node>