:right-sidebar: True Portal =================================================================== .. currentmodule:: gi.repository.Xdp .. class:: Portal(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` Implemented Interfaces: :class:`~gi.repository.Gio.Initable` Context for portal calls. The XdpPortal object provides the main context object for the portal operations of libportal. Typically, an application will create a single XdpPortal object with :obj:`~gi.repository.Portal.new` and use it throughout its lifetime. Constructors ------------ .. rst-class:: interim-class .. class:: Portal :no-index: .. classmethod:: initable_new() -> ~gi.repository.Xdp.Portal | None Creates a new :obj:`~gi.repository.Xdp.Portal` object. .. versionadded:: 0.7 .. classmethod:: new() -> ~gi.repository.Xdp.Portal Creates a new :obj:`~gi.repository.Xdp.Portal` object. If D-Bus is unavailable this API will abort. We recommend using :func:`~gi.repository.Xdp.Portal.initable_new` to safely handle this failure. Methods ------- .. rst-class:: interim-class .. class:: Portal :no-index: .. method:: access_camera(parent: ~gi.repository.Xdp.Parent | None, flags: ~gi.repository.Xdp.CameraFlags, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None Request access to a camera. When the request is done, ``callback`` will be called. You can then call :obj:`~gi.repository.Portal.access_camera_finish` to get the results. :param parent: parent window information :param flags: options for this call :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: access_camera_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes a camera acess request. Returns the result as a boolean. If the access was granted, you can then call :obj:`~gi.repository.Portal.open_pipewire_remote_for_camera` to obtain a pipewire remote. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: add_notification(id: str, notification: ~gi.repository.GLib.Variant, flags: ~gi.repository.Xdp.NotificationFlags, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None 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 :obj:`~gi.repository.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 :obj:`~gi.repository.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 :obj:`~gi.repository.Portal.remove_notification`\. :param id: unique ID for the notification :param notification: a :obj:`~gi.repository.GLib.Variant` dictionary with the content of the notification :param flags: options for this call :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: add_notification_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes the notification request. Returns the result as a boolean. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: compose_email(parent: ~gi.repository.Xdp.Parent | None, addresses: list[str] | None, cc: list[str] | None, bcc: list[str] | None, subject: str | None, body: str | None, attachments: list[str] | None, flags: ~gi.repository.Xdp.EmailFlags, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None 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 :obj:`~gi.repository.Portal.compose_email_finish` to get the results. :param parent: parent window information :param addresses: the email addresses to send to :param cc: the email addresses to cc :param bcc: the email addresses to bcc :param subject: the subject for the email :param body: the body for the email :param attachments: an array of paths for files to attach :param flags: options for this call :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: compose_email_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes the compose-email request. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: create_input_capture_session(parent: ~gi.repository.Xdp.Parent | None, capabilities: ~gi.repository.Xdp.InputCapability, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None Creates a session for input capture When the request is done, ``callback`` will be called. You can then call :obj:`~gi.repository.Portal.create_input_capture_session_finish` to get the results. :param parent: parent window information :param capabilities: which kinds of capabilities to request :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: create_input_capture_session_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Xdp.InputCaptureSession Finishes the InputCapture CreateSession request, and returns a :obj:`~gi.repository.Xdp.InputCaptureSession`\. To get to the :obj:`~gi.repository.Xdp.Session` within use :func:`~gi.repository.Xdp.InputCaptureSession.get_session`. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: create_remote_desktop_session(devices: ~gi.repository.Xdp.DeviceType, outputs: ~gi.repository.Xdp.OutputType, flags: ~gi.repository.Xdp.RemoteDesktopFlags, cursor_mode: ~gi.repository.Xdp.CursorMode, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None Creates a session for remote desktop. When the request is done, ``callback`` will be called. You can then call :obj:`~gi.repository.Portal.create_remote_desktop_session_finish` to get the results. :param devices: which kinds of input devices to ofer in the new dialog :param outputs: which kinds of source to offer in the dialog :param flags: options for this call :param cursor_mode: the cursor mode of the session :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: create_remote_desktop_session_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Xdp.Session Finishes the create-remote-desktop request, and returns a :obj:`~gi.repository.Xdp.Session`\. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: create_remote_desktop_session_full(devices: ~gi.repository.Xdp.DeviceType, outputs: ~gi.repository.Xdp.OutputType, flags: ~gi.repository.Xdp.RemoteDesktopFlags, cursor_mode: ~gi.repository.Xdp.CursorMode, persist_mode: ~gi.repository.Xdp.PersistMode, restore_token: str | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None Creates a session for remote desktop. When the request is done, ``callback`` will be called. You can then call :obj:`~gi.repository.Portal.create_remote_desktop_session_finish` to get the results. :param devices: which kinds of input devices to ofer in the new dialog :param outputs: which kinds of source to offer in the dialog :param flags: options for this call :param cursor_mode: the cursor mode of the session :param persist_mode: the persist mode of the session :param restore_token: the token of a previous screencast session to restore :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: create_screencast_session(outputs: ~gi.repository.Xdp.OutputType, flags: ~gi.repository.Xdp.ScreencastFlags, cursor_mode: ~gi.repository.Xdp.CursorMode, persist_mode: ~gi.repository.Xdp.PersistMode, restore_token: str | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None Creates a session for a screencast. When the request is done, ``callback`` will be called. You can then call :obj:`~gi.repository.Portal.create_screencast_session_finish` to get the results. :param outputs: which kinds of source to offer in the dialog :param flags: options for this call :param cursor_mode: the cursor mode of the session :param persist_mode: the persist mode of the session :param restore_token: the token of a previous screencast session to restore :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: create_screencast_session_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Xdp.Session Finishes the create-screencast request, and returns a :obj:`~gi.repository.Xdp.Session`\. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: dynamic_launcher_get_desktop_entry(desktop_file_id: str) -> 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". :param desktop_file_id: the .desktop file name .. method:: dynamic_launcher_get_icon(desktop_file_id: str, out_icon_format: str | None = None, out_icon_size: int | None = None) -> ~gi.repository.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". :param desktop_file_id: the .desktop file name :param out_icon_format: return location for icon format string, one of "png", "jpeg", "svg" :param out_icon_size: return location for icon size .. method:: dynamic_launcher_install(token: str, desktop_file_id: str, desktop_entry: str) -> 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. :param token: a token acquired via a :obj:`~gi.repository.Portal.dynamic_launcher_request_install_token` or :obj:`~gi.repository.Portal.dynamic_launcher_prepare_install` call :param desktop_file_id: the .desktop file name to be used :param desktop_entry: the key-file to be used for the contents of the .desktop file .. method:: dynamic_launcher_launch(desktop_file_id: str, activation_token: str) -> bool :param desktop_file_id: :param activation_token: .. method:: dynamic_launcher_prepare_install(parent: ~gi.repository.Xdp.Parent | None, name: str, icon_v: ~gi.repository.GLib.Variant, launcher_type: ~gi.repository.Xdp.LauncherType, target: str | None, editable_name: bool, editable_icon: bool, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None 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 :obj:`~gi.repository.Portal.dynamic_launcher_prepare_install_finish` to get the results. :param parent: parent window information :param name: the name for the launcher :param icon_v: a :obj:`~gi.repository.Gio.BytesIcon` as returned by :func:`~gi.repository.Gio.Icon.serialize`. Must be a png or jpeg no larger than 512x512, or an svg :param launcher_type: the type of the launcher :param target: the URL if the launcher is for a web app, or :const:`None` :param editable_name: if :const:`True`, the user will be able to edit the name of the launcher :param editable_icon: if :const:`True`, the user will be able to edit the icon of the launcher, if the implementation supports this :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: dynamic_launcher_prepare_install_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.GLib.Variant Finishes the prepare-install-launcher request, and returns :obj:`~gi.repository.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 :obj:`~gi.repository.Portal.dynamic_launcher_install` call to complete the installation :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: dynamic_launcher_request_install_token(name: str, icon_v: ~gi.repository.GLib.Variant) -> str Requests a token which can be passed to :obj:`~gi.repository.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. :param name: the name for the launcher :param icon_v: a :obj:`~gi.repository.Gio.BytesIcon` as returned by :func:`~gi.repository.Gio.Icon.serialize`. Must be a png or jpeg no larger than 512x512, or an svg .. method:: dynamic_launcher_uninstall(desktop_file_id: str) -> 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". :param desktop_file_id: the .desktop file name .. method:: get_settings() -> ~gi.repository.Xdp.Settings This function returns an object to access settings exposed through the portal. .. method:: get_user_information(parent: ~gi.repository.Xdp.Parent | None, reason: str | None, flags: ~gi.repository.Xdp.UserInformationFlags, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None Gets information about the user. When the request is done, ``callback`` will be called. You can then call :obj:`~gi.repository.Portal.get_user_information_finish` to get the results. :param parent: parent window information :param reason: a string that can be shown in the dialog to explain why the information is needed :param flags: options for this call :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: get_user_information_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.GLib.Variant Finishes the get-user-information request. Returns the result in the form of a :obj:`~gi.repository.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 :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: is_camera_present() -> bool Returns whether any camera are present. .. method:: location_monitor_start(parent: ~gi.repository.Xdp.Parent | None, distance_threshold: int, time_threshold: int, accuracy: ~gi.repository.Xdp.LocationAccuracy, flags: ~gi.repository.Xdp.LocationMonitorFlags, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None Makes ``XdpPortal`` start monitoring location changes. When the location changes, the :obj:`~gi.repository.Xdp.Portal.signals.location_updated`\. signal is emitted. Use :obj:`~gi.repository.Portal.location_monitor_stop` to stop monitoring. Note that :obj:`~gi.repository.Xdp.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 :obj:`~gi.repository.Portal.location_monitor_stop` to stop monitoring. :param parent: a :obj:`~gi.repository.Xdp.Parent`\, or ``NULL`` :param distance_threshold: distance threshold, in meters :param time_threshold: time threshold, in seconds :param accuracy: desired accuracy :param flags: options for this call :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: location_monitor_start_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes a location-monitor request. Returns result in the form of boolean. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: location_monitor_stop() -> None Stops location monitoring that was started with :obj:`~gi.repository.Portal.location_monitor_start`\. .. method:: open_directory(parent: ~gi.repository.Xdp.Parent, uri: str, flags: ~gi.repository.Xdp.OpenUriFlags, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None 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. :param parent: parent window information :param uri: the URI to open :param flags: options for this call :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: open_directory_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes the open-directory request. Returns the result in the form of a boolean. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: open_file(parent: ~gi.repository.Xdp.Parent | None, title: str, filters: ~gi.repository.GLib.Variant | None, current_filter: ~gi.repository.GLib.Variant | None, choices: ~gi.repository.GLib.Variant | None, flags: ~gi.repository.Xdp.OpenFileFlags, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None 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 :obj:`~gi.repository.Portal.open_file_finish` to get the results. :param parent: parent window information :param title: title for the file chooser dialog :param filters: a :obj:`~gi.repository.GLib.Variant` describing file filters :param current_filter: a :obj:`~gi.repository.GLib.Variant` describing the current file filter :param choices: a :obj:`~gi.repository.GLib.Variant` describing extra widgets :param flags: options for this call :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: open_file_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.GLib.Variant Finishes the open-file request Returns the result in the form of a :obj:`~gi.repository.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. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: open_pipewire_remote_for_camera() -> 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. .. method:: open_uri(parent: ~gi.repository.Xdp.Parent, uri: str, flags: ~gi.repository.Xdp.OpenUriFlags, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None Opens ``uri`` with an external handler. :param parent: parent window information :param uri: the URI to open :param flags: options for this call :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: open_uri_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes the open-uri request. Returns the result in the form of a boolean. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: pick_color(parent: ~gi.repository.Xdp.Parent | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None Lets the user pick a color from the screen. When the request is done, ``callback`` will be called. You can then call :obj:`~gi.repository.Portal.pick_color_finish` to get the results. :param parent: parent window information :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: pick_color_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.GLib.Variant Finishes a pick-color request. Returns the result in the form of a GVariant of the form (ddd), containing red, green and blue components in the range [0,1]. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: prepare_print(parent: ~gi.repository.Xdp.Parent | None, title: str, settings: ~gi.repository.GLib.Variant | None, page_setup: ~gi.repository.GLib.Variant | None, flags: ~gi.repository.Xdp.PrintFlags, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None 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 :obj:`~gi.repository.Portal.prepare_print_finish` to get the results. :param parent: parent window information :param title: tile for the print dialog :param settings: Serialized print settings :param page_setup: Serialized page setup :param flags: options for this call :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: prepare_print_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.GLib.Variant Finishes the prepare-print request. Returns a :obj:`~gi.repository.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 :obj:`~gi.repository.Portal.print_file` call to avoid the print dialog :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: print_file(parent: ~gi.repository.Xdp.Parent | None, title: str, token: int, file: str, flags: ~gi.repository.Xdp.PrintFlags, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None 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 :obj:`~gi.repository.Portal.print_file_finish` to get the results. :param parent: parent window information :param title: tile for the print dialog :param token: token that was returned by a previous :obj:`~gi.repository.Portal.prepare_print` call, or 0 :param file: path of the document to print :param flags: options for this call :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: print_file_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes the print request. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: remove_notification(id: str) -> None Withdraws a desktop notification. :param id: the ID of an notification .. method:: request_background(parent: ~gi.repository.Xdp.Parent | None, reason: str | None, commandline: list[str] | None, flags: ~gi.repository.Xdp.BackgroundFlags, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None Requests background permissions. When the request is done, ``callback`` will be called. You can then call :obj:`~gi.repository.Portal.request_background_finish` to get the results. :param parent: parent window information :param reason: reason to present to user for request :param commandline: command line to autostart :param flags: options for this call :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param user_data: data to pass to ``callback`` .. method:: request_background_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes the request. Returns ``TRUE`` if successful. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. classmethod:: running_under_flatpak() -> bool Detects if running inside of a Flatpak or WebKit sandbox. See also: :obj:`~gi.repository.Portal.running_under_sandbox`\. .. classmethod:: running_under_sandbox() -> 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 :obj:`~gi.repository.Portal.running_under_snap`\. Note that these functions are all cached and will always return the same result. .. classmethod:: running_under_snap() -> bool Detects if you are running inside of a Snap sandbox. See also: :obj:`~gi.repository.Portal.running_under_sandbox`\. .. method:: save_file(parent: ~gi.repository.Xdp.Parent | None, title: str, current_name: str | None, current_folder: str | None, current_file: str | None, filters: ~gi.repository.GLib.Variant | None, current_filter: ~gi.repository.GLib.Variant | None, choices: ~gi.repository.GLib.Variant | None, flags: ~gi.repository.Xdp.SaveFileFlags, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None Asks the user for a location to save a file. The format for the ``filters`` argument is the same as for :obj:`~gi.repository.Portal.open_file`\. The format for the ``choices`` argument is the same as for :obj:`~gi.repository.Portal.open_file`\. When the request is done, ``callback`` will be called. You can then call :obj:`~gi.repository.Portal.save_file_finish` to get the results. :param parent: parent window information :param title: title for the file chooser dialog :param current_name: suggested filename :param current_folder: suggested folder to save the file in :param current_file: the current file (when saving an existing file) :param filters: a :obj:`~gi.repository.GLib.Variant` describing file filters :param current_filter: a :obj:`~gi.repository.GLib.Variant` describing the current file filter :param choices: a :obj:`~gi.repository.GLib.Variant` describing extra widgets :param flags: options for this call :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: save_file_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.GLib.Variant Finishes the save-file request. Returns the result in the form of a :obj:`~gi.repository.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. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: save_files(parent: ~gi.repository.Xdp.Parent | None, title: str, current_name: str | None, current_folder: str | None, files: ~gi.repository.GLib.Variant, choices: ~gi.repository.GLib.Variant | None, flags: ~gi.repository.Xdp.SaveFileFlags, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None 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 :obj:`~gi.repository.Portal.open_file`\. When the request is done, ``callback`` will be called. You can then call :obj:`~gi.repository.Portal.save_file_finish` to get the results. :param parent: parent window information :param title: title for the file chooser dialog :param current_name: suggested filename :param current_folder: suggested folder to save the file in :param files: An array of file names to be saved :param choices: a :obj:`~gi.repository.GLib.Variant` describing extra widgets :param flags: options for this call :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: save_files_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.GLib.Variant Finishes the save-files request. Returns the result in the form of a :obj:`~gi.repository.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. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: session_inhibit(parent: ~gi.repository.Xdp.Parent | None, reason: str | None, flags: ~gi.repository.Xdp.InhibitFlags, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None Inhibits various session status changes. To obtain an ID that can be used to undo the inhibition, use :obj:`~gi.repository.Portal.session_inhibit_finish` in the callback. To remove an active inhibitor, call :obj:`~gi.repository.Portal.session_uninhibit` with the same ID. :param parent: parent window information :param reason: user-visible reason for the inhibition :param flags: information about what to inhibit :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: session_inhibit_finish(result: ~gi.repository.Gio.AsyncResult) -> int Finishes the inhbit request. Returns the ID of the inhibition as a positive integer. The ID can be passed to :obj:`~gi.repository.Portal.session_uninhibit` to undo the inhibition. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: session_monitor_query_end_response() -> None This method should be called within one second of receiving a :obj:`~gi.repository.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 :obj:`~gi.repository.Portal.session_inhibit` to prevent the session from ending, or to save your state and get ready for the session to end. .. method:: session_monitor_start(parent: ~gi.repository.Xdp.Parent | None, flags: ~gi.repository.Xdp.SessionMonitorFlags, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None Makes :obj:`~gi.repository.Xdp.Portal` start monitoring the login session state. When the state changes, the :obj:`~gi.repository.Xdp.Portal.signals.session_state_changed` signal is emitted. Use :obj:`~gi.repository.Portal.session_monitor_stop` to stop monitoring. :param parent: a XdpParent, or ``NULL`` :param flags: options for this call :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: session_monitor_start_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes a session-monitor request. Returns the result in the form of boolean. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: session_monitor_stop() -> None Stops session state monitoring that was started with :obj:`~gi.repository.Portal.session_monitor_start`\. .. method:: session_uninhibit(id: int) -> None Removes an inhibitor that was created by a call to :obj:`~gi.repository.Portal.session_inhibit`\. :param id: unique ID for an active inhibition .. method:: set_background_status(status_message: str | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None Sets the status information of the application, for when it's running in background. :param status_message: status message when running in background :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: set_background_status_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes setting the background status of the application. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: set_wallpaper(parent: ~gi.repository.Xdp.Parent | None, uri: str, flags: ~gi.repository.Xdp.WallpaperFlags, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None Sets a desktop background image, given by a uri. :param parent: parent window information :param uri: the URI to use :param flags: options for this call :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: set_wallpaper_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes the open-uri request. Returns the result in the form of a boolean. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: spawn(cwd: str, argv: list[str], fds: list[int] | None, map_to: list[int] | None, env: list[str] | None, flags: ~gi.repository.Xdp.SpawnFlags, sandbox_expose: list[str] | None = None, sandbox_expose_ro: list[str] | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None 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 :obj:`~gi.repository.Xdp.Portal.signals.spawn_exited` signal. :param cwd: the cwd for the new process :param argv: the argv for the new process :param fds: an array of open fds to pass to the new process, or ``NULL`` :param map_to: an array of integers to map the ``fds`` to, or ``NULL``\. Must be the same length as ``fds`` :param env: an array of KEY=VALUE environment settings, or ``NULL`` :param flags: flags influencing the spawn operation :param sandbox_expose: paths to expose rw in the new sandbox, or ``NULL`` :param sandbox_expose_ro: paths to expose ro in the new sandbox, or ``NULL`` :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: spawn_finish(result: ~gi.repository.Gio.AsyncResult) -> int Finishes the spawn request. Returns the pid of the newly spawned process. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: spawn_signal(pid: int, signal: int, to_process_group: bool) -> None Sends a Unix signal to a process that has been spawned by :obj:`~gi.repository.Portal.spawn`\. :param pid: the pid of the process to send a signal to :param signal: the Unix signal to send (see signal(7)) :param to_process_group: whether to send the signal to the process group of the process .. method:: take_screenshot(parent: ~gi.repository.Xdp.Parent | None, flags: ~gi.repository.Xdp.ScreenshotFlags, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None Takes a screenshot. When the request is done, ``callback`` will be called. You can then call :obj:`~gi.repository.Portal.take_screenshot_finish` to get the results. :param parent: parent window information :param flags: options for this call :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: take_screenshot_finish(result: ~gi.repository.Gio.AsyncResult) -> str | None Finishes a screenshot request. Returns the result in the form of a URI pointing to an image file. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: trash_file(path: str, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None Sends the file at ``path`` to the trash can. :param path: the path for a local file :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: trash_file_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes the trash-file request. Returns the result in the form of a boolean. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: update_install(parent: ~gi.repository.Xdp.Parent, flags: ~gi.repository.Xdp.UpdateInstallFlags, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None Installs an available software update. This should be called in response to a :obj:`~gi.repository.Xdp.Portal.signals.update_available` signal. During the update installation, the :obj:`~gi.repository.Xdp.Portal.signals.update_progress` signal will be emitted to provide progress information. :param parent: a :obj:`~gi.repository.Xdp.Parent` :param flags: options for this call :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: update_install_finish(result: ~gi.repository.Gio.AsyncResult) -> 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 :obj:`~gi.repository.Xdp.Portal.signals.update_progress` signal to learn when the installation is complete. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: update_monitor_start(flags: ~gi.repository.Xdp.UpdateMonitorFlags, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, data: ~typing.Any = None) -> None Makes ``XdpPortal`` start monitoring for available software updates. When a new update is available, the :obj:`~gi.repository.Xdp.Portal.signals.update_available`\. signal is emitted. Use :obj:`~gi.repository.Portal.update_monitor_stop` to stop monitoring. :param flags: options for this cal.. :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` :param callback: a callback to call when the request is done :param data: data to pass to ``callback`` .. method:: update_monitor_start_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes an update-monitor request. Returns the result in the form of boolean. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: update_monitor_stop() -> None Stops update monitoring that was started with :obj:`~gi.repository.Portal.update_monitor_start`\. Signals ------- .. rst-class:: interim-class .. class:: Portal.signals :no-index: .. method:: location_updated(latitude: float, longitude: float, altitude: float, accuracy: float, speed: float, heading: float, description: str, timestamp_s: int, timestamp_ms: int) -> None The type of the None singleton. :param latitude: the latitude, in degrees :param longitude: the longitude, in degrees :param altitude: the altitude, in meters :param accuracy: the accuracy, in meters :param speed: the speed, in meters per second :param heading: the heading, in degrees :param description: the description :param timestamp_s: the timestamp seconds since the Unix epoch :param timestamp_ms: the microseconds fraction of the timestamp .. method:: notification_action_invoked(id: str, action: str, parameter: ~gi.repository.GLib.Variant | None = None) -> None The type of the None singleton. :param id: the notification ID :param action: the action name :param parameter: the target parameter for the action .. method:: session_state_changed(screensaver_active: bool, session_state: ~gi.repository.Xdp.LoginSessionState) -> None The type of the None singleton. :param screensaver_active: whether the screensaver is active :param session_state: the current state of the login session .. method:: spawn_exited(pid: int, exit_status: int) -> None The type of the None singleton. :param pid: the pid of the process :param exit_status: the exit status of the process .. method:: update_available(running_commit: str, local_commit: str, remote_commit: str) -> None The type of the None singleton. :param running_commit: the commit that the sandbox is running with :param local_commit: the commit that is currently deployed. Restarting the app will use this commit :param remote_commit: the commit that is available as an update. Updating the app will deloy this commit .. method:: update_progress(n_ops: int, op: int, progress: int, status: ~gi.repository.Xdp.UpdateStatus, error: str, error_message: str) -> None The type of the None singleton. :param n_ops: the number of operations that the update consists of :param op: the position of the currently active operation :param progress: the progress of the currently active operation, as a number between 0 and 100 :param status: the overall status of the update :param error: the error name if the status is 'failed' :param error_message: the error message if the status is 'failed'