AtlasPortal

A singleton for what an app asks the desktop to do: open a link with the default app and show a desktop notification.

Since 1.4.0

AtlasPortal is a singleton. openUrl() opens a link with the user's default app (through the OpenURI portal under Flatpak), after checking the URL. notify() shows a desktop notification over org.freedesktop.Notifications. Use these instead of Qt.openUrlExternally() or a hand-built notification.

Example

AtlasButton { text: qsTr("Help"); onClicked: AtlasPortal.openUrl("https://example.com/help") }

Component.onCompleted: {
    const id = AtlasPortal.notify(qsTr("Update ready"), qsTr("Restart to finish."),
        [{ id: "default", text: qsTr("Open") }, { id: "restart", text: qsTr("Restart") }],
        { eventId: "updateStaged" });
}
Connections {
    target: AtlasPortal
    function onActionInvoked(notificationId, actionId) { /* ... */ }
}

Properties

Name	Type	Default	Description
`extraSchemes`	`list<string>`	`[]`	URL schemes `openUrl()` accepts besides http, https, mailto and file. The file and host rules still apply to those four.

Signals

Name	Description
`actionInvoked(string notificationId, string actionId)`	The user picked an action of a notification this app sent. `notificationId` is the id `notify()` returned; `"default"` is a click on the notification itself.

Methods

Signature	Description
`escape(string text): string`	Returns `text` safe for a notification body with `options.markup: true`: markup characters are escaped and control characters become spaces.
`notify(string title, string body): string`	Shows a notification with no actions.
`notify(string title, string body, list actions): string`	Shows a notification with actions: a list of `{ id, text }`.
`notify(string title, string body, list actions, object options): string`	Shows a notification with actions and options (see below).
`openUrl(url url): bool`	Opens the link with the default app. Returns `false`, with a warning in the log, for any URL that is refused.

notify() returns the notification's id at once, or "" when nothing was sent (the user turned the event's popup off, or the arguments are bad).

What `openUrl()` opens

http and https, with a host.
mailto, with an address. Only subject and body are kept; any other query key, such as attach or bcc, is dropped and logged.
file, for a local path that exists. The real path behind symbolic links is checked, and a program, a launcher or any executable file is refused, by content and not by name. Directories are fine.
Any scheme listed in extraSchemes.

Notification arguments

body is plain text; the portal escapes it.
actions is a list of { id, text }. At most 8, with ids of ASCII letters, digits and ., _ or -, up to 64 characters. An action whose text is empty, over 200 characters or has control characters is skipped, with a warning. The id "default" is a click on the notification itself.

The options object takes:

Key	Meaning
`markup`	`true` says the body is markup that the caller has escaped (use `escape()` on everything that came from outside); the server shows it as markup.
`eventId`	The notifyrc event name: ASCII camelCase letters and digits, not starting with a digit, up to 64 characters. Default `"notification"`. The user's choice in System Settings is honoured.
`urgency`	`"low"` or `"normal"` (the default). Anything else is normal. There are no sounds.
`persistent`	Stays until the user acts. Use only when ignoring the notification has consequences.
`icon`	An icon name or an absolute path. Anything else shows the app's own icon.

Note

An app that uses eventId ships a <short name>.notifyrc. The component name (x-kde-appname) and the desktop entry are derived from the app ID, the same as in the Rust crate's notify.