Notification#

Description#

Portal for sending notifications

This simple interface lets sandboxed applications send and withdraw notifications. It is not possible for the application to learn if the notification was actually presented to the user. Not a portal in the strict sense, since there is no user interaction.

Note that in contrast to most other portal requests, notifications are expected to outlast the running application. If a user clicks on a notification after the application has exited, it will get activated again.

Notifications can specify actions that can be activated by the user. Actions whose name starts with ‘app.’ are assumed to be exported and will be activated via the ActivateAction() method in the org.freedesktop.Application interface. Other actions are activated by sending the org.freedesktop.portal.Notification::ActionInvoked signal to the application.

This documentation describes version 1 of this interface.

Properties#

org.freedesktop.portal.Notification:version#

version readable u

Methods#

org.freedesktop.portal.Notification.AddNotification#

AddNotification (
  IN id s,
  IN notification a{sv}
)

Sends a notification.

The ID can be used to later withdraw the notification. If the application reuses the same ID without withdrawing, the notification is replaced by the new one.

The format of the serialized notification is a vardict, with the following supported keys, all of which are optional:

  • title (s)

    User-visible string to display as the title.

  • body (s)

    User-visible string to display as the body.

  • icon (v)

    Serialized icon (see g_icon_serialize()).

    The portal only accepts serialized GThemedIcon and GBytesIcons. Both of these have the form (sv). For themed icons, the string is “themed”, and the value is an array of strings containing the icon names. For bytes icons, the string is “bytes”, and the value is a bytestring containing the icon data in png, jpeg or svg form. For historical reasons, it is also possible to send a simple string for themed icons with a single icon name.

    There may be further restrictions on the supported kinds of icons.

  • priority (s)

    The priority for the notification. Supported values:

    • low

    • normal

    • high

    • urgent

  • default-action (s)

    Name of an action that is exported by the application. This action 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 to add to the notification. The format for serialized buttons is a vardict with the following supported keys:

    • label (s)

      User-visible label for the button. Mandatory.

    • action (s)

      Name of an action that is exported by the application. The action will be activated when the user clicks on the button. Mandatory.

    • target (v)

      Target parameter to send along when activating the action.

id

Application-provided ID for this notification

notification

Vardict with the serialized notification

org.freedesktop.portal.Notification.RemoveNotification#

RemoveNotification (
  IN id s
)

Withdraws a notification.

id

Application-provided ID for this notification

Signals#

org.freedesktop.portal.Notification::ActionInvoked#

ActionInvoked (
  id s,
  action s,
  parameter av
)

Send to the application when a non-exported action is activated.

id

the application-provided ID for the notification

action

the name of the action

parameter

array which will contain the target parameter for the action, if one was specified