Xdp.Portal

g GObject.GInterface GObject.GInterface Gio.Initable Gio.Initable GObject.GInterface->Gio.Initable GObject.Object GObject.Object Xdp.Portal Xdp.Portal GObject.Object->Xdp.Portal Gio.Initable->Xdp.Portal

Subclasses:

None

Methods

Inherited:

GObject.Object (37), Gio.Initable (2)

Structs:

GObject.ObjectClass (5)

class

initable_new ()

class

new ()

class

running_under_flatpak ()

class

running_under_sandbox ()

class

running_under_snap ()

access_camera (parent, flags, cancellable, callback, *data)

access_camera_finish (result)

add_notification (id, notification, flags, cancellable, callback, *data)

add_notification_finish (result)

compose_email (parent, addresses, cc, bcc, subject, body, attachments, flags, cancellable, callback, *data)

compose_email_finish (result)

create_remote_desktop_session (devices, outputs, flags, cursor_mode, cancellable, callback, *data)

create_remote_desktop_session_finish (result)

create_screencast_session (outputs, flags, cursor_mode, persist_mode, restore_token, cancellable, callback, *data)

create_screencast_session_finish (result)

dynamic_launcher_get_desktop_entry (desktop_file_id)

dynamic_launcher_get_icon (desktop_file_id, out_icon_format, out_icon_size)

dynamic_launcher_install (token, desktop_file_id, desktop_entry)

dynamic_launcher_launch (desktop_file_id, activation_token)

dynamic_launcher_prepare_install (parent, name, icon_v, launcher_type, target, editable_name, editable_icon, cancellable, callback, *data)

dynamic_launcher_prepare_install_finish (result)

dynamic_launcher_request_install_token (name, icon_v)

dynamic_launcher_uninstall (desktop_file_id)

get_user_information (parent, reason, flags, cancellable, callback, *data)

get_user_information_finish (result)

is_camera_present ()

location_monitor_start (parent, distance_threshold, time_threshold, accuracy, flags, cancellable, callback, *data)

location_monitor_start_finish (result)

location_monitor_stop ()

open_directory (parent, uri, flags, cancellable, callback, *data)

open_directory_finish (result)

open_file (parent, title, filters, current_filter, choices, flags, cancellable, callback, *data)

open_file_finish (result)

open_pipewire_remote_for_camera ()

open_uri (parent, uri, flags, cancellable, callback, *data)

open_uri_finish (result)

pick_color (parent, cancellable, callback, *data)

pick_color_finish (result)

prepare_print (parent, title, settings, page_setup, flags, cancellable, callback, *data)

prepare_print_finish (result)

print_file (parent, title, token, file, flags, cancellable, callback, *data)

print_file_finish (result)

remove_notification (id)

request_background (parent, reason, commandline, flags, cancellable, callback, *user_data)

request_background_finish (result)

save_file (parent, title, current_name, current_folder, current_file, filters, current_filter, choices, flags, cancellable, callback, *data)

save_file_finish (result)

save_files (parent, title, current_name, current_folder, files, choices, flags, cancellable, callback, *data)

save_files_finish (result)

session_inhibit (parent, reason, flags, cancellable, callback, *data)

session_inhibit_finish (result)

session_monitor_query_end_response ()

session_monitor_start (parent, flags, cancellable, callback, *data)

session_monitor_start_finish (result)

session_monitor_stop ()

session_uninhibit (id)

set_background_status (status_message, cancellable, callback, *data)

set_background_status_finish (result)

set_wallpaper (parent, uri, flags, cancellable, callback, *data)

set_wallpaper_finish (result)

spawn (cwd, argv, fds, map_to, env, flags, sandbox_expose, sandbox_expose_ro, cancellable, callback, *data)

spawn_finish (result)

spawn_signal (pid, signal, to_process_group)

take_screenshot (parent, flags, cancellable, callback, *data)

take_screenshot_finish (result)

trash_file (path, cancellable, callback, *data)

trash_file_finish (result)

update_install (parent, flags, cancellable, callback, *data)

update_install_finish (result)

update_monitor_start (flags, cancellable, callback, *data)

update_monitor_start_finish (result)

update_monitor_stop ()

Virtual Methods

Inherited:

GObject.Object (7), Gio.Initable (1)

Properties

None

Signals

Inherited:

GObject.Object (1)

Name

Short Description

location-updated

Emitted when location monitoring is enabled and the location changes.

notification-action-invoked

Emitted when a non-exported action is activated on a notification.

session-state-changed

Emitted when session state monitoring is enabled and the state of the login session changes or the screensaver is activated or deactivated.

spawn-exited

Emitted when a process that was spawned with [method`Portal`.spawn] exits.

update-available

Emitted when updates monitoring is enabled and a new update is available.

update-progress

Emitted to indicate progress of an update installation.

Fields

Inherited:

GObject.Object (1)

Class Details

class Xdp.Portal(**kwargs)
Bases:

GObject.Object, Gio.Initable

Abstract:

No

Structure:

Xdp.PortalClass

Context for portal calls.

The Xdp.Portal object provides the main context object for the portal operations of libportal.

Typically, an application will create a single Xdp.Portal object with [ctor`Portal`.new] and use it throughout its lifetime.

classmethod initable_new()
Raises:

GLib.Error

Returns:

a newly created [class`Portal`] object or None on error

Return type:

Xdp.Portal or None

Creates a new [class`Portal`] object.

classmethod new()
Returns:

a newly created [class`Portal`] object

Return type:

Xdp.Portal

Creates a new [class`Portal`] object. If D-Bus is unavailable this API will abort. We recommend using Xdp.Portal.initable_new() to safely handle this failure.

classmethod running_under_flatpak()
Returns:

True if the current process is running under a Flatpak sandbox

Return type:

bool

Detects if running inside of a Flatpak or WebKit sandbox.

See also: [func`Portal`.running_under_sandbox].

classmethod running_under_sandbox()
Returns:

True if the current process should use portals to access resources on the host system, or False if either an error was encountered or the process is running unsandboxed

Return type:

bool

This function tries to determine if the current process is running under a sandbox that requires the use of portals.

If you need to check error conditions see [func`Portal`.running_under_snap].

Note that these functions are all cached and will always return the same result.

classmethod running_under_snap()
Raises:

GLib.Error

Returns:

True if the current process is running under a Snap sandbox, or False if either unsandboxed or an error was encountered in which case error will be set

Return type:

bool

Detects if you are running inside of a Snap sandbox.

See also: [func`Portal`.running_under_sandbox].

access_camera(parent, flags, cancellable, callback, *data)
Parameters:

Request access to a camera.

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

access_camera_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

TRUE if access to a camera was granted

Return type:

bool

Finishes a camera acess request.

Returns the result as a boolean.

If the access was granted, you can then call [method`Portal`.open_pipewire_remote_for_camera] to obtain a pipewire remote.

add_notification(id, notification, flags, cancellable, callback, *data)
Parameters:

Sends a desktop notification.

The following keys may be present in notification:

  • title s: a user-visible string to display as title

  • body s: a user-visible string to display as body

  • icon v: a serialized icon (in the format produced by [method`Gio`.Icon.serialize])

  • priority s: “low”, “normal”, “high” or “urgent”

  • default-action s: name of an action that will be activated when the user clicks on the notification

  • default-action-target v: target parameter to send along when activating the default action.

  • buttons aa{sv}: array of serialized buttons

Each serialized button is a dictionary with the following supported keys:

  • label s: user-visible lable for the button. Mandatory

  • action s: name of an action that will be activated when the user clicks on the button. Mandatory

  • target v: target parameter to send along when activating the button

Actions with a prefix of “app.” are assumed to be exported by the application and will be activated via the org.freedesktop.Application interface, others are activated by emitting the [signal`Portal`:py:func:::notification-action-invoked<Xdp.Portal.signals.notification_action_invoked>] signal.

It is the callers responsibility to ensure that the ID is unique among all notifications.

To withdraw a notification, use [method`Portal`.remove_notification].

add_notification_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

TRUE if the notification was added

Return type:

bool

Finishes the notification request.

Returns the result as a boolean.

compose_email(parent, addresses, cc, bcc, subject, body, attachments, flags, cancellable, callback, *data)
Parameters:

  • parent (Xdp.Parent or None) – parent window information

  • addresses ([str] or None) – the email addresses to send to

  • cc ([str] or None) – the email addresses to cc

  • bcc ([str] or None) – the email addresses to bcc

  • subject (str or None) – the subject for the email

  • body (str or None) – the body for the email

  • attachments ([str] or None) – an array of paths for files to attach

  • flags (Xdp.EmailFlags) – options for this call

  • 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

Presents a window that lets the user compose an email, with some pre-filled information.

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

compose_email_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

TRUE if the request was handled successfully

Return type:

bool

Finishes the compose-email request.

create_remote_desktop_session(devices, outputs, flags, cursor_mode, cancellable, callback, *data)
Parameters:

Creates a session for remote desktop.

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

create_remote_desktop_session_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

a [class`Session`]

Return type:

Xdp.Session

Finishes the create-remote-desktop request, and returns a [class`Session`].

create_screencast_session(outputs, flags, cursor_mode, persist_mode, restore_token, cancellable, callback, *data)
Parameters:

Creates a session for a screencast.

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

create_screencast_session_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

a [class`Session`]

Return type:

Xdp.Session

Finishes the create-screencast request, and returns a [class`Session`].

dynamic_launcher_get_desktop_entry(desktop_file_id)
Parameters:

desktop_file_id (str) – the .desktop file name

Raises:

GLib.Error

Returns:

the contents of the desktop file, or None with error set

Return type:

str

This function gets the contents of a .desktop file that was previously installed by the dynamic launcher portal.

The desktop_file_id must be prefixed with the caller’s app ID followed by a “.” and suffixed with “.desktop”.

dynamic_launcher_get_icon(desktop_file_id, out_icon_format, out_icon_size)
Parameters:

  • desktop_file_id (str) – the .desktop file name

  • out_icon_format (str or None) – return location for icon format string, one of “png”, “jpeg”, “svg”

  • out_icon_size (int or None) – return location for icon size

Raises:

GLib.Error

Returns:

the icon in a format recognized by Gio.Icon.deserialize(), or None with error set

Return type:

GLib.Variant

This function gets the icon associated with a .desktop file that was previously installed by the dynamic launcher portal.

The desktop_file_id must be prefixed with the caller’s app ID followed by a “.” and suffixed with “.desktop”.

dynamic_launcher_install(token, desktop_file_id, desktop_entry)
Parameters:

  • token (str) – a token acquired via a [method`Portal`.dynamic_launcher_request_install_token] or [method`Portal`.dynamic_launcher_prepare_install] call

  • desktop_file_id (str) – the .desktop file name to be used

  • desktop_entry (str) – the key-file to be used for the contents of the .desktop file

Raises:

GLib.Error

Returns:

True if the installation was successful, False with error set otherwise

Return type:

bool

This function completes installation of a launcher so that the icon and name given in previous method calls will show up in the desktop environment’s menu.

The desktop_file_id must be prefixed with the caller’s app ID followed by a “.” and suffixed with “.desktop”.

The desktop_entry data need not include Icon= or Name= entries since these will be added by the portal, and the Exec= entry will be rewritten to call the application with e.g. “flatpak run” depending on the sandbox status of the app.

dynamic_launcher_launch(desktop_file_id, activation_token)
Parameters:

  • desktop_file_id (str) –

  • activation_token (str) –

Raises:

GLib.Error

Return type:

bool

dynamic_launcher_prepare_install(parent, name, icon_v, launcher_type, target, editable_name, editable_icon, cancellable, callback, *data)
Parameters:

  • parent (Xdp.Parent or None) – parent window information

  • name (str) – the name for the launcher

  • icon_v (GLib.Variant) – a Gio.BytesIcon as returned by Gio.Icon.serialize(). Must be a png or jpeg no larger than 512x512, or an svg

  • launcher_type (Xdp.LauncherType) – the type of the launcher

  • target (str or None) – the URL if the launcher is for a web app, or None

  • editable_name (bool) – if True, the user will be able to edit the name of the launcher

  • editable_icon (bool) – if True, the user will be able to edit the icon of the launcher, if the implementation supports this

  • 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

Presents a dialog to the user so they can confirm they want to install a launcher to their desktop.

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

dynamic_launcher_prepare_install_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

a [struct`GLib`.Variant] dictionary with launcher information

Return type:

GLib.Variant

Finishes the prepare-install-launcher request, and returns [struct`GLib`.Variant] dictionary with the following information:

  • name s: the name chosen by the user (or the provided name if the editable_name option was not set)

  • token s: a token that can by used in a [method`Portal`.dynamic_launcher_install] call to complete the installation

dynamic_launcher_request_install_token(name, icon_v)
Parameters:
Raises:

GLib.Error

Returns:

a token that can be passed to [method`Portal`.dynamic_launcher_install], or None with error set

Return type:

str

Requests a token which can be passed to [method`Portal`.dynamic_launcher_install] to complete installation of the launcher without user interaction.

This function only works when the caller’s app ID is in the allowlist for the portal backend being used. It’s intended for software centers such as GNOME Software or KDE Discover.

dynamic_launcher_uninstall(desktop_file_id)
Parameters:

desktop_file_id (str) – the .desktop file name

Raises:

GLib.Error

Returns:

True if the uninstallation was successful, False with error set otherwise

Return type:

bool

This function uninstalls a launcher that was previously installed using the dynamic launcher portal, resulting in the .desktop file and icon being deleted.

The desktop_file_id must be prefixed with the caller’s app ID followed by a “.” and suffixed with “.desktop”.

get_user_information(parent, reason, flags, cancellable, callback, *data)
Parameters:

Gets information about the user.

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

get_user_information_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

a [struct`GLib`.Variant] dictionary with user information

Return type:

GLib.Variant

Finishes the get-user-information request.

Returns the result in the form of a [struct`GLib`.Variant] dictionary containing the following fields:

  • id s: the user ID

  • name s: the users real name

  • image s: the uri of an image file for the users avatar picture

is_camera_present()
Returns:

TRUE if the system has cameras

Return type:

bool

Returns whether any camera are present.

location_monitor_start(parent, distance_threshold, time_threshold, accuracy, flags, cancellable, callback, *data)
Parameters:

Makes XdpPortal start monitoring location changes.

When the location changes, the [signal`Portal`:py:func:::location-updated<Xdp.Portal.signals.location_updated>]. signal is emitted.

Use [method`Portal`.location_monitor_stop] to stop monitoring.

Note that [class`Portal`] only maintains a single location monitor at a time. If you want to change the distance_threshold, time_threshold or accuracy of the current monitor, you first have to call [method`Portal`.location_monitor_stop] to stop monitoring.

location_monitor_start_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

TRUE if the request succeeded

Return type:

bool

Finishes a location-monitor request.

Returns result in the form of boolean.

location_monitor_stop()

Stops location monitoring that was started with [method`Portal`.location_monitor_start].

open_directory(parent, uri, flags, cancellable, callback, *data)
Parameters:

Opens the directory containing the file specified by the uri.

which must be a file: uri pointing to a file that the application has access to.

open_directory_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

TRUE if the call succeeded

Return type:

bool

Finishes the open-directory request.

Returns the result in the form of a boolean.

open_file(parent, title, filters, current_filter, choices, flags, cancellable, callback, *data)
Parameters:

Asks the user to open one or more files.

The format for the filters argument is a(sa(us)). Each item in the array specifies a single filter to offer to the user. The first string is a user-visible name for the filter. The a(us) specifies a list of filter strings, which can be either a glob pattern (indicated by 0) or a mimetype (indicated by 1).

Example: [('Images', [(0, '*.ico'), (1, 'image/png')]), ('Text', [(0, '*.txt')])]

The format for the choices argument is a(ssa(ss)s). For each element, the first string is an ID that will be returned with the response, te second string is a user-visible label. The a(ss) is the list of choices, each being a is an ID and a user-visible label. The final string is the initial selection, or "", to let the portal decide which choice will be initially selected. None of the strings, except for the initial selection, should be empty.

As a special case, passing an empty array for the list of choices indicates a boolean choice that is typically displayed as a check button, using "true" and "false" as the choices.

Example: [('encoding', 'Encoding', [('utf8', 'Unicode (UTF-8)'), ('latin15', 'Western')], 'latin15'), ('reencode', 'Reencode', [], 'false')]

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

open_file_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

a [struct`GLib`.Variant] dictionary with the results

Return type:

GLib.Variant

Finishes the open-file request

Returns the result in the form of a [struct`GLib`.Variant] dictionary containing the following fields:

  • uris as: an array of strings containing the uris of selected files

  • choices a(ss): an array of pairs of strings, the first string being the ID of a combobox that was passed into this call, the second string being the selected option.

open_pipewire_remote_for_camera()
Returns:

the file descriptor

Return type:

int

Opens a file descriptor to the pipewire remote where the camera nodes are available.

The file descriptor should be used to create a pw_core object, by using pw_context_connect_fd(). Only the camera nodes will be available from this pipewire node.

open_uri(parent, uri, flags, cancellable, callback, *data)
Parameters:

Opens uri with an external handler.

open_uri_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

TRUE if the call succeeded

Return type:

bool

Finishes the open-uri request.

Returns the result in the form of a boolean.

pick_color(parent, cancellable, callback, *data)
Parameters:

Lets the user pick a color from the screen.

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

pick_color_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

GLib.Variant containing the color

Return type:

GLib.Variant

Finishes a pick-color request.

Returns the result in the form of a GLib.Variant of the form (ddd), containing red, green and blue components in the range [0,1].

prepare_print(parent, title, settings, page_setup, flags, cancellable, callback, *data)
Parameters:

Presents a print dialog to the user and returns print settings and page setup.

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

prepare_print_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

a [struct`GLib`.Variant] dictionary with print information

Return type:

GLib.Variant

Finishes the prepare-print request.

Returns a [struct`GLib`.Variant] dictionary with the following information:

  • settings a{sv}: print settings as set up by the user in the print dialog

  • page-setup `a{sv}: page setup as set up by the user in the print dialog

  • token u: a token that can by used in a [method`Portal`.print_file] call to avoid the print dialog

print_file(parent, title, token, file, flags, cancellable, callback, *data)
Parameters:

  • parent (Xdp.Parent or None) – parent window information

  • title (str) – tile for the print dialog

  • token (int) – token that was returned by a previous [method`Portal`.prepare_print] call, or 0

  • file (str) – path of the document to print

  • flags (Xdp.PrintFlags) – options for this call

  • 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

Prints a file.

If a valid token is present in the options, then this call will print with the settings from the Print call that the token refers to. If no token is present, then a print dialog will be presented to the user.

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

print_file_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

TRUE if the request was successful

Return type:

bool

Finishes the print request.

remove_notification(id)
Parameters:

id (str) – the ID of an notification

Withdraws a desktop notification.

request_background(parent, reason, commandline, flags, cancellable, callback, *user_data)
Parameters:

Requests background permissions.

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

request_background_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

TRUE if successful.

Return type:

bool

Finishes the request.

Returns TRUE if successful.

save_file(parent, title, current_name, current_folder, current_file, filters, current_filter, choices, flags, cancellable, callback, *data)
Parameters:

  • parent (Xdp.Parent or None) – parent window information

  • title (str) – title for the file chooser dialog

  • current_name (str or None) – suggested filename

  • current_folder (str or None) – suggested folder to save the file in

  • current_file (str or None) – the current file (when saving an existing file)

  • filters (GLib.Variant or None) – a [struct`GLib`.Variant] describing file filters

  • current_filter (GLib.Variant or None) – a [struct`GLib`.Variant] describing the current file filter

  • choices (GLib.Variant or None) – a [struct`GLib`.Variant] describing extra widgets

  • flags (Xdp.SaveFileFlags) – options for this call

  • 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

Asks the user for a location to save a file.

The format for the filters argument is the same as for [method`Portal`.open_file].

The format for the choices argument is the same as for [method`Portal`.open_file].

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

save_file_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

a [struct`GLib`.Variant] dictionary with the results

Return type:

GLib.Variant

Finishes the save-file request.

Returns the result in the form of a [struct`GLib`.Variant] dictionary containing the following fields:

  • uris (as): an array of strings containing the uri of the selected file

  • choices a(ss): an array of pairs of strings, the first string being the ID of a combobox that was passed into this call, the second string being the selected option.

save_files(parent, title, current_name, current_folder, files, choices, flags, cancellable, callback, *data)
Parameters:

Asks for a folder as a location to save one or more files.

The names of the files will be used as-is and appended to the selected folder’s path in the list of returned files. If the selected folder already contains a file with one of the given names, the portal may prompt or take some other action to construct a unique file name and return that instead.

The format for the choices argument is the same as for [method`Portal`.open_file].

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

save_files_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

a [struct`GLib`.Variant] dictionary with the results

Return type:

GLib.Variant

Finishes the save-files request.

Returns the result in the form of a [struct`GLib`.Variant] dictionary containing the following fields:

  • uris (as): an array of strings containing the uri corresponding to each file passed to the save-files request, in the same order. Note that the file names may have changed, for example if a file with the same name in the selected folder already exists.

  • choices a(ss): an array of pairs of strings, the first string being the ID of a combobox that was passed into this call, the second string being the selected option.

session_inhibit(parent, reason, flags, cancellable, callback, *data)
Parameters:

Inhibits various session status changes.

To obtain an ID that can be used to undo the inhibition, use [method`Portal`.session_inhibit_finish] in the callback.

To remove an active inhibitor, call [method`Portal`.session_uninhibit] with the same ID.

session_inhibit_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

the ID of the inhibition, or -1 if there was an error

Return type:

int

Finishes the inhbit request.

Returns the ID of the inhibition as a positive integer. The ID can be passed to [method`Portal`.session_uninhibit] to undo the inhibition.

session_monitor_query_end_response()

This method should be called within one second of receiving a [signal`Portal`:py:func:::session-state-changed<Xdp.Portal.signals.session_state_changed>] signal with the ‘Query End’ state, to acknowledge that they have handled the state change.

Possible ways to handle the state change are either to call [method`Portal`.session_inhibit] to prevent the session from ending, or to save your state and get ready for the session to end.

session_monitor_start(parent, flags, cancellable, callback, *data)
Parameters:

Makes [class`Portal`] start monitoring the login session state.

When the state changes, the [signal`Portal`:py:func:::session-state-changed<Xdp.Portal.signals.session_state_changed>] signal is emitted.

Use [method`Portal`.session_monitor_stop] to stop monitoring.

session_monitor_start_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

TRUE if the request succeeded

Return type:

bool

Finishes a session-monitor request.

Returns the result in the form of boolean.

session_monitor_stop()

Stops session state monitoring that was started with [method`Portal`.session_monitor_start].

session_uninhibit(id)
Parameters:

id (int) – unique ID for an active inhibition

Removes an inhibitor that was created by a call to [method`Portal`.session_inhibit].

set_background_status(status_message, cancellable, callback, *data)
Parameters:

Sets the status information of the application, for when it’s running in background.

set_background_status_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

True if successfully set status, False otherwise

Return type:

bool

Finishes setting the background status of the application.

set_wallpaper(parent, uri, flags, cancellable, callback, *data)
Parameters:

Sets a desktop background image, given by a uri.

set_wallpaper_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

TRUE if the call succeeded

Return type:

bool

Finishes the open-uri request.

Returns the result in the form of a boolean.

spawn(cwd, argv, fds, map_to, env, flags, sandbox_expose, sandbox_expose_ro, cancellable, callback, *data)
Parameters:

  • cwd (str) – the cwd for the new process

  • argv ([str]) – the argv for the new process

  • fds ([int] or None) – an array of open fds to pass to the new process, or NULL

  • map_to ([int] or None) – an array of integers to map the fds to, or NULL. Must be the same length as fds

  • env ([str] or None) – an array of KEY=VALUE environment settings, or NULL

  • flags (Xdp.SpawnFlags) – flags influencing the spawn operation

  • sandbox_expose ([str] or None) – paths to expose rw in the new sandbox, or NULL

  • sandbox_expose_ro ([str] or None) – paths to expose ro in the new sandbox, or NULL

  • 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

Creates a new copy of the applications sandbox, and runs a process in, with the given arguments.

The learn when the spawned process exits, connect to the [signal`Portal`:py:func:::spawn-exited<Xdp.Portal.signals.spawn_exited>] signal.

spawn_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

the pid of the spawned process.

Return type:

int

Finishes the spawn request.

Returns the pid of the newly spawned process.

spawn_signal(pid, signal, to_process_group)
Parameters:

  • pid (int) – the pid of the process to send a signal to

  • signal (int) – the Unix signal to send (see signal(7))

  • to_process_group (bool) – whether to send the signal to the process group of the process

Sends a Unix signal to a process that has been spawned by [method`Portal`.spawn].

take_screenshot(parent, flags, cancellable, callback, *data)
Parameters:

Takes a screenshot.

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

take_screenshot_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

URI pointing to an image file

Return type:

str or None

Finishes a screenshot request.

Returns the result in the form of a URI pointing to an image file.

trash_file(path, cancellable, callback, *data)
Parameters:

Sends the file at path to the trash can.

trash_file_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

TRUE if the call succeeded

Return type:

bool

Finishes the trash-file request.

Returns the result in the form of a boolean.

update_install(parent, flags, cancellable, callback, *data)
Parameters:

Installs an available software update.

This should be called in response to a [signal`Portal`:py:func:::update-available<Xdp.Portal.signals.update_available>] signal.

During the update installation, the [signal`Portal`:py:func:::update-progress<Xdp.Portal.signals.update_progress>] signal will be emitted to provide progress information.

update_install_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

TRUE if the update is being installed

Return type:

bool

Finishes an update-installation request.

Returns the result in the form of boolean.

Note that the update may not be completely installed by the time this function is called. You need to listen to the [signal`Portal`:py:func:::update-progress<Xdp.Portal.signals.update_progress>] signal to learn when the installation is complete.

update_monitor_start(flags, cancellable, callback, *data)
Parameters:

Makes XdpPortal start monitoring for available software updates.

When a new update is available, the [signal`Portal`:py:func:::update-available<Xdp.Portal.signals.update_available>]. signal is emitted.

Use [method`Portal`.update_monitor_stop] to stop monitoring.

update_monitor_start_finish(result)
Parameters:

result (Gio.AsyncResult) – a [iface`Gio`.AsyncResult]

Raises:

GLib.Error

Returns:

TRUE if the request succeeded

Return type:

bool

Finishes an update-monitor request.

Returns the result in the form of boolean.

update_monitor_stop()

Stops update monitoring that was started with [method`Portal`.update_monitor_start].

Signal Details

Xdp.Portal.signals.location_updated(portal, latitude, longitude, altitude, accuracy, speed, heading, description, timestamp_s, timestamp_ms)
Signal Name:

location-updated

Flags:

RUN_FIRST

Parameters:

  • portal (Xdp.Portal) – The object which received the signal

  • latitude (float) – the latitude, in degrees

  • longitude (float) – the longitude, in degrees

  • altitude (float) – the altitude, in meters

  • accuracy (float) – the accuracy, in meters

  • speed (float) – the speed, in meters per second

  • heading (float) – the heading, in degrees

  • description (str) – the description

  • timestamp_s (int) – the timestamp seconds since the Unix epoch

  • timestamp_ms (int) – the microseconds fraction of the timestamp

Emitted when location monitoring is enabled and the location changes.

Xdp.Portal.signals.notification_action_invoked(portal, id, action, parameter)
Signal Name:

notification-action-invoked

Flags:

RUN_FIRST

Parameters:

  • portal (Xdp.Portal) – The object which received the signal

  • id (str) – the notification ID

  • action (str) – the action name

  • parameter (GLib.Variant or None) – the target parameter for the action

Emitted when a non-exported action is activated on a notification.

Xdp.Portal.signals.session_state_changed(portal, screensaver_active, session_state)
Signal Name:

session-state-changed

Flags:

RUN_FIRST

Parameters:

  • portal (Xdp.Portal) – The object which received the signal

  • screensaver_active (bool) – whether the screensaver is active

  • session_state (Xdp.LoginSessionState) – the current state of the login session

Emitted when session state monitoring is enabled and the state of the login session changes or the screensaver is activated or deactivated.

Xdp.Portal.signals.spawn_exited(portal, pid, exit_status)
Signal Name:

spawn-exited

Flags:

RUN_FIRST

Parameters:

  • portal (Xdp.Portal) – The object which received the signal

  • pid (int) – the pid of the process

  • exit_status (int) – the exit status of the process

Emitted when a process that was spawned with [method`Portal`.spawn] exits.

Xdp.Portal.signals.update_available(portal, running_commit, local_commit, remote_commit)
Signal Name:

update-available

Flags:

RUN_FIRST

Parameters:

  • portal (Xdp.Portal) – The object which received the signal

  • running_commit (str) – the commit that the sandbox is running with

  • local_commit (str) – the commit that is currently deployed. Restarting the app will use this commit

  • remote_commit (str) – the commit that is available as an update. Updating the app will deloy this commit

Emitted when updates monitoring is enabled and a new update is available.

It is only sent once with the same information, but it can be sent many times if new updates appear.

Xdp.Portal.signals.update_progress(portal, n_ops, op, progress, status, error, error_message)
Signal Name:

update-progress

Flags:

RUN_FIRST

Parameters:

  • portal (Xdp.Portal) – The object which received the signal

  • n_ops (int) – the number of operations that the update consists of

  • op (int) – the position of the currently active operation

  • progress (int) – the progress of the currently active operation, as a number between 0 and 100

  • status (Xdp.UpdateStatus) – the overall status of the update

  • error (str) – the error name if the status is ‘failed’

  • error_message (str) – the error message if the status is ‘failed’

Emitted to indicate progress of an update installation.

It is undefined exactly how often it is sent, but it will be emitted at least once at the end with a non-zero status. For each successful operation in the update, we’re also guaranteed to send exactly one signal with progress 100.