InputCaptureSession

class InputCaptureSession(**properties: Any)

Superclasses: Object

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

The 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 get_zones. These InputCaptureZone object represent the accessible desktop area for input capturing. InputCapturePointerBarrier objects can be set up on these zones to trigger input capture.

The InputCaptureSession wraps a Session object.

Methods

class InputCaptureSession

connect_to_eis() → 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() → None

Disables this input capture session.

enable() → None

Enables this input capture session. In the future, this client may receive input events.

get_restore_token() → str

Returns the restore token for this session or NULL if none exists. This token can be passed to 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 create_input_capture_session2 and only once start_finish has completed.

The token may change with every session.

get_session() → Session

Return the XdpSession for this InputCapture session.

get_zones() → list[InputCaptureZone]

Obtains the current set of InputCaptureZone objects.

The returned object is valid until the zones are invalidated by the zones_changed signal.

Unless the session is active, this function returns NULL.

release(activation_id: int) → None

Releases this input capture session without a suggested cursor position.

Parameters:

activation_id

release_at(activation_id: int, cursor_x_position: float, cursor_y_position: float) → None

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

Parameters:

• activation_id

• cursor_x_position – the suggested cursor x position once capture has been released

• cursor_y_position – the suggested cursor y position once capture has been released

async set_pointer_barriers(self, barriers: list[InputCapturePointerBarrier]) → list[InputCapturePointerBarrier]

This is the awaitable version of set_pointer_barriers().

Parameters:

barriers – the pointer barriers to apply

set_pointer_barriers(barriers: list[InputCapturePointerBarrier], cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, data: Any = None) → None

Sets the pointer barriers for this session. When the request is done, callback will be called. You can then call 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 is_active property is changed on that barrier. Failed barriers have the property set to a False value.

Parameters:

• barriers – the pointer barriers to apply

• cancellable

• callback

• data

set_pointer_barriers_finish(result: AsyncResult) → list[InputCapturePointerBarrier]

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

Parameters:

result – a AsyncResult

set_restore_token(restore_token: str) → None

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 create_input_capture_session2 and only before start has been called. It has no effect otherwise.

The restore token for the current session can be obtained with get_restore_token.

Parameters:

restore_token – a restore token from a previous session

set_session_persistence(persistence: InputCaptureSessionPersistence) → None

Requests session persistence from the portal. A persistent session can be restored using the restore token, see set_restore_token.

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

The default persistence is none.

Parameters:

persistence – the session persistence for this session

async start(self, parent: Parent | None, capabilities: InputCapability) → bool

This is the awaitable version of start().

Parameters:

• parent – parent window information

• capabilities – which kinds of capabilities to request

start(parent: Parent | None, capabilities: InputCapability, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, data: Any = None) → None

Start the input capture session.

When the request is done, callback will be called. You can then call start_finish to get the results.

Parameters:

• parent – parent window information

• capabilities – which kinds of capabilities to request

• cancellable – optional Cancellable

• callback – a callback to call when the request is done

• data – data to pass to callback

start_finish(result: AsyncResult) → bool

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

Parameters:

result – a AsyncResult

Signals

class InputCaptureSession.signals

activated(activation_id: int, options: Variant) → None

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

Parameters:

• activation_id – the unique activation_id to identify this input capture

• options – a GVariant with the signal options

deactivated(activation_id: int, options: Variant) → None

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

Parameters:

• activation_id – the unique activation_id to identify this input capture

• options – a GVariant with the signal options

disabled(options: Variant) → None

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

Parameters:

options – a GVariant with the signal options

zones_changed(options: Variant) → None

Emitted when an InputCapture session’s zones have changed. When this signal is emitted, all current zones will have their 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 get_zones() to retrieve the new zones.

Parameters:

options – a GVariant with the signal options