Xdp.InputCaptureSession¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

	`connect_to_eis` ()
	`disable` ()
	`enable` ()
	`get_restore_token` ()
	`get_session` ()
	`get_zones` ()
	`release` (activation_id)
	`release_at` (activation_id, cursor_x_position, cursor_y_position)
	`set_pointer_barriers` (barriers, cancellable, callback, *data)
	`set_pointer_barriers_finish` (result)
	`set_restore_token` (restore_token)
	`set_session_persistence` (persistence)
	`start` (parent, capabilities, cancellable, callback, *data)
	`start_finish` (result)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

None

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`activated`	Emitted when an InputCapture session activates and sends events.
`deactivated`	Emitted when an InputCapture session deactivates and no longer sends events.
`disabled`	Emitted when an InputCapture session is disabled.
`zones-changed`	Emitted when an InputCapture session’s zones have changed.

Fields¶

Inherited:: GObject.Object (1)

Class Details¶

class Xdp.InputCaptureSession(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: Xdp.InputCaptureSessionClass

A representation of a long-lived input capture portal interaction.

The [class`InputCaptureSession`] object is used to represent portal interactions with the input capture desktop portal that extend over multiple portal calls. Usually a caller creates an input capture session, requests the available zones and sets up pointer barriers on those zones before enabling the session.

To find available zones, call [method`InputCaptureSession`.get_zones]. These [class`InputCaptureZone`] object represent the accessible desktop area for input capturing. [class`InputCapturePointerBarrier`] objects can be set up on these zones to trigger input capture.

The [class`InputCaptureSession`] wraps a [class`Session`] object.

connect_to_eis()¶

Raises:: GLib.Error
Returns:: a socket to the EIS implementation for this input capture session or a negative errno on failure.
Return type:: int

Connect this session to an EIS implementation and return the fd. This fd can be passed into ei_setup_backend_fd(). See the libei documentation for details.

This is a sync DBus invocation.

disable()¶: Disables this input capture session.

enable()¶: Enables this input capture session. In the future, this client may receive input events.

get_restore_token()¶

Returns:: the restore token or None
Return type:: str

Returns the restore token for this session or None if none exists. This token can be passed to [method`InputCaptureSession`.set_restore_token] for a future session to restore this session, possibly skipping interactive permission dialogs.

This method only returns a token for a session created with [method`Portal`.create_input_capture_session2] and only once [method`InputCaptureSession`.start_finish] has completed.

The token may change with every session.

get_session()¶

Returns:: a [class`Session`] object
Return type:: Xdp.Session

Return the [class`XdpSession`] for this InputCapture session.

get_zones()¶

Returns:: the available zones. The caller must keep a reference to the list or the elements if used outside the immediate scope.
Return type:: [Xdp.InputCaptureZone]

Obtains the current set of [class`InputCaptureZone`] objects.

The returned object is valid until the zones are invalidated by the [signal`InputCaptureSession`:py:func:::zones-changed<Xdp.InputCaptureSession.signals.zones_changed>] signal.

Unless the session is active, this function returns NULL.

release(activation_id)¶

Parameters:: activation_id (int) –

Releases this input capture session without a suggested cursor position.

release_at(activation_id, cursor_x_position, cursor_y_position)¶

Parameters:

activation_id (int) –
cursor_x_position (float) – the suggested cursor x position once capture has been released
cursor_y_position (float) – the suggested cursor y position once capture has been released

Releases this input capture session with a suggested cursor position. Note that the implementation is not required to honour this position.

set_pointer_barriers(barriers, cancellable, callback, *data)¶

Parameters:

barriers ([Xdp.InputCapturePointerBarrier]) – the pointer barriers to apply
cancellable (Gio.Cancellable or None) –
callback (Gio.AsyncReadyCallback or None) –
data (object or None) –

Sets the pointer barriers for this session. When the request is done, callback will be called. You can then call [method`InputCaptureSession`.set_pointer_barriers_finish] to get the results. The result of this request is the list of pointer barriers that failed to apply - barriers not present in the returned list are active.

Once the pointer barrier is applied (i.e. the reply to the DBus Request has been received), the the [property`InputCapturePointerBarrier`:py:data::is-active<Xdp.InputCaptureSession.props.is_active>] property is changed on that barrier. Failed barriers have the property set to a False value.

set_pointer_barriers_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]
Raises:: GLib.Error
Returns:: a list of failed pointer barriers
Return type:: [Xdp.InputCapturePointerBarrier]

Finishes the set-pointer-barriers request, and returns a GLib.List with the pointer barriers that failed to apply and should be cleaned up by the caller.

set_restore_token(restore_token)¶

Parameters:: restore_token (str) – a restore token from a previous session

Sets the restore token for the session about to be started. This instructs the portal to restore the previous session identified by this token.

This method can only be called for a session created with [method`Portal`.create_input_capture_session2] and only before [method`InputCaptureSession`.start] has been called. It has no effect otherwise.

The restore token for the current session can be obtained with [method`InputCaptureSession`.get_restore_token].

set_session_persistence(persistence)¶

Parameters:: persistence (Xdp.InputCaptureSessionPersistence) – the session persistence for this session

Requests session persistence from the portal. A persistent session can be restored using the restore token, see [method`InputCaptureSession`.set_restore_token].

This method can only be called for a session created with [method`Portal`.create_input_capture_session2] and only before [method`InputCaptureSession`.start] has been called. It has no effect otherwise.

The default persistence is none.

start(parent, capabilities, cancellable, callback, *data)¶

Parameters:

parent (Xdp.Parent or None) – parent window information
capabilities (Xdp.InputCapability) – which kinds of capabilities to request
cancellable (Gio.Cancellable or None) – optional [class`Gio`.Cancellable]
callback (Gio.AsyncReadyCallback or None) – a callback to call when the request is done
data (object or None) – data to pass to callback

Start the input capture session.

When the request is done, callback will be called. You can then call [method`InputCaptureSession`.start_finish] to get the results.

start_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]
Raises:: GLib.Error
Returns:: True on success.
Return type:: bool

Finishes the InputCapture Start request, and returns True if it was successful.

Signal Details¶

Xdp.InputCaptureSession.signals.activated(input_capture_session, activation_id, options)¶

Signal Name:

activated

Flags:

RUN_CLEANUP, NO_RECURSE, NO_HOOKS

Parameters:

input_capture_session (Xdp.InputCaptureSession) – The object which received the signal
activation_id (int) – the unique activation_id to identify this input capture
options (GLib.Variant) – a GLib.Variant with the signal options

Emitted when an InputCapture session activates and sends events. When this signal is emitted, events will appear on the transport layer.

Xdp.InputCaptureSession.signals.deactivated(input_capture_session, activation_id, options)¶

Signal Name:

deactivated

Flags:

RUN_CLEANUP, NO_RECURSE, NO_HOOKS

Parameters:

input_capture_session (Xdp.InputCaptureSession) – The object which received the signal
activation_id (int) – the unique activation_id to identify this input capture
options (GLib.Variant) – a GLib.Variant with the signal options

Emitted when an InputCapture session deactivates and no longer sends events.

Xdp.InputCaptureSession.signals.disabled(input_capture_session, options)¶

Signal Name:

disabled

Flags:

RUN_CLEANUP, NO_RECURSE, NO_HOOKS

Parameters:

input_capture_session (Xdp.InputCaptureSession) – The object which received the signal
options (GLib.Variant) – a GLib.Variant with the signal options

Emitted when an InputCapture session is disabled. This signal is emitted when capturing was disabled by the server.

Xdp.InputCaptureSession.signals.zones_changed(input_capture_session, options)¶

Signal Name:

zones-changed

Flags:

RUN_CLEANUP, NO_RECURSE, NO_HOOKS

Parameters:

input_capture_session (Xdp.InputCaptureSession) – The object which received the signal
options (GLib.Variant) – a GLib.Variant with the signal options

Emitted when an InputCapture session’s zones have changed. When this signal is emitted, all current zones will have their [property`InputCaptureZone`:py:data::is-valid<Xdp.InputCaptureSession.props.is_valid>] property set to False and all internal references to those zones have been released. This signal is sent after libportal has fetched the updated zones, a caller should call Xdp.InputCaptureSession.get_zones() to retrieve the new zones.