.. _org.freedesktop.portal.Notification:

===================================
 Notification
===================================

-----------
Description
-----------

.. _org.freedesktop.portal.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 (without the 'app.' prefix) and will be activated via
`D-Bus Activation
<https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s08.html>`_
using ``ActivateAction()`` method in the
``org.freedesktop.Application`` interface. An `activation-token` for
`XDG Activation
<https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/staging/xdg-activation/xdg-activation-v1.xml>`_
and an application-defined `target` is passed when activating the action.
Other actions are activated by sending the
`org.freedesktop.portal.Notification::ActionInvoked`_ signal
to the application.

This documentation describes version 2 of this interface.



.. _org.freedesktop.portal.Notification Properties:

----------
Properties
----------

.. _org.freedesktop.portal.Notification:SupportedOptions:

org.freedesktop.portal.Notification:SupportedOptions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    SupportedOptions readable a{sv}


Some properties in :ref:`org.freedesktop.portal.Notification.AddNotification`
may have options advertised by the server.

Currently there are the following options the notification server can advertise:

* ``category`` (``as``)

  Categories that the notification server understands and supports.

* ``button-purpose`` (``as``)

  Button purposes that the notification server understands and supports.
  This is the list of options that can be used as `purpose` for `buttons`.

Since: version 2




.. _org.freedesktop.portal.Notification:version:

org.freedesktop.portal.Notification:version
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    version readable u




.. _org.freedesktop.portal.Notification Methods:

-------
Methods
-------

.. _org.freedesktop.portal.Notification.AddNotification:

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 updated with the new one. It's possible
to set ``show-as-new`` hint in the ``display-hint`` property
to animate replacing the notification instead of updating it.

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.

  This should be a short string, if it doesn't fit the UI it may
  be truncated to fit on a single line.

* ``body`` (``s``)

  User-visible string to display as the body.

  This can be a long string but if it doesn't fit the UI it may
  be wrapped or/and truncated.

* ``markup-body`` (``s``)

  The same as ``body`` but with support for markup formatting.
  The markup is XML-based and supports a small subset of HTML
  ``<b>...</b>``, ``<i>...</i>`` and ``<a href="...">...</a>``.

  Any markup not supported, e.g. new lines, will be removed from
  the string. In the future, the set of supported markup may be extended.

  This can be a long string but if it doesn't fit the UI it may
  be wrapped or/and truncated.

  Since: version 2

* ``icon`` (``v``)

  A serialized icon to add to the notification.
  The icon must pass `icon validation <icons.html>`_ in order to be used.
  The format for serialized icon is a tuple (sv) with the following
  supported keys:

  * ``themed`` (``as``)

    A themed icon containing an array of strings with the icon names.

    This is the same format as a
    `serialized <https://docs.gtk.org/gio/method.Icon.to_string.html>`_
    `GThemedIcon <https://docs.gtk.org/gio/class.ThemedIcon.html>`_ at
    the moment, but this interoperability may change in the future.

  * ``bytes`` (``ay``)

    The icon bytes into a variant bytes array.

    This is the same format as a
    `serialized <https://docs.gtk.org/gio/method.Icon.to_string.html>`_
    `GBytesIcon <https://docs.gtk.org/gio/class.BytesIcon.html>`_ at the
    moment, but this interoperability may change in the future.

    Since version 2, this is deprecated and should not be used.
    Please use the `themed` or `file-descriptor` option to set an icon.

  * ``file-descriptor`` (``h``)

    A file descriptor to an image file in png, jpeg or svg form.
    The file-descriptor used needs to be sealable, currently this is only
    possible for file descriptors created with ``memfd_create()`` with
    the ``MFD_ALLOW_SEALING`` flag set.

    Since: version 2

  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.

* ``sound`` (``v``)

  A serialized sound to add to the notification.
  Supported sound formats are ogg/opus, ogg/vorbis and wav/pcm.

  The format for
  serialized sound is a tuple (sv) with the following supported keys:

  * ``file-descriptor`` (``h``)

    A file descriptor to a sound file.
    The file-descriptor used needs to be sealable, currently this is only
    possible for file descriptors created with ``memfd_create()`` with
    the ``MFD_ALLOW_SEALING`` flag set.

  To play the default sound the string ``default`` can be passed.
  To play no sound at all the string ``silent`` can be passed.
  If this property isn't specified the notification server can decide
  whether to play a sound.

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

  Since: version 2

* ``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, if no purpose
    is specified. It is strongly recommended to always provide
    sensible label. Buttons without a ``label`` are ignored
    by the server when it doesn't understand the ``purpose`` or
    is needed to display the button.

  * ``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.

  * ``purpose`` (``s``)

    The ``purpose`` of the button. This information may be used by the
    notification server to treat the button specially.

    Depending on the ``purpose`` other fields of the button may be ignored.
    If the server doesn't understand the ``purpose`` it will be
    ignored and the button will be shown as a normal button.

    Most standardized hints are defined as part of a ``category``.
    Additional purposes may be defined by notification servers using
    ``x-vendor`` prefix e.g. ``x-gnome.class.specific``

    The following purposes are defined outside of a ``category``:

    * ``system.custom-alert``:

      Not a button in a strict sense. This action may be called,
      depending on system policies, automatically by the notification
      server whenever the notification is shown.

      This allows apps to use custom methods for notifying the user,
      for example, to play audio from a special
      source like a streaming service or a radio station.

      No ``label`` should be given when this purpose is used, so that
      the server can ignore the button if it doesn't understand the purpose.

    Since: version 2

* ``display-hint`` (``as``)

  An array of ways to display the notification. If none are set, or the notification server has its own policy, it is
  free to decide how and where to display the notification.

  * ``transient``

    The notification is displayed only as a banner and won't be kept
    by the server in a tray.

    It's a programmer error to specify ``tray`` at the same time.

  * ``tray``

    No banner for the notification will be displayed and
    the notification is placed in the tray.

    It's a programmer error to specify ``transient`` at the same time.

  * ``persistent``

    Make the notification persistent in the notification tray.
    The user can’t dismiss it using the usual close button or gesture.

    Apps are only allowed to display persistent notifications
    as long as they have a window. Once the last window of an app
    is closed the persistent notification will be removed.

  * ``hide-on-lockscreen``

    Don't show the notification on the lockscreen.

  * ``hide-content-on-lockscreen``

    All content of the notification will be hidden on the lockscreen.

  * ``show-as-new``

    If a notification with the same ``id`` of the app exists already
    replace the previous notification, by removing the old notification
    (including animation, etc) and adding a new notification.

    If this hint isn't specified the notification's content is updated
    without any flickering.

  Since: version 2

* ``category`` (``s``)

  The ``category`` describes the content of a notification.
  A notification server may use this information to display the
  notification specially. Some categories also include
  button purposes that can be set for a button so that the notification
  can know the purpose of the button.

  Additional categories and button purposes may be defined by notification servers
  using ``x-vendor`` prefix e.g. ``x-gnome.class.specific``

  The following categories are standarized so far:

  * ``im.received``

    Intended for instant messaging apps displaying notifications for new messages.

    This category has the following button purposes:

    * ``im.reply-with-text``:

      Inline replies for instant messaging.
      The user-provided text will be added to the response.

      The user response (``s``) will be placed as the second value
      in the parameter array of exported actions.
      For non-exported actions it will be placed as the third value
      in the parameter array of `org.freedesktop.portal.Notification::ActionInvoked`_.

  * ``alarm.ringing``

    Intended for alarm clock apps

  * ``call.incoming``

    Intended for call apps to notify the user about an incoming call.

    This category has the following button purposes:

    * ``call.accept``:

      Accept the incoming call.

    * ``call.decline``:

      Decline the incoming call.

  * ``call.ongoing``

    Intended for call apps while a call is ongoing.

    This type has the following button purposes:

    * ``call.hang-up``:

      Hang up the ongoing call.

    * ``call.enable-speakerphone``:

      Enable the speakerphone for the ongoing call.

    * ``call.disable-speakerphone``:

      Disable the speakerphone for the ongoing call.

  * ``call.unanswered``

    Intended to be used by call apps when a call was missed.

  * ``weather.warning.extreme``

    Intended to be used to display an extreme weather warning.

  * ``cellbroadcast.danger.presidential``

    Intended to be used to display nationwide or presidential warnings broadcasted by the cell network.

  * ``cellbroadcast.danger.extreme``

    Intended to be used to display extreme danger warnings broadcasted by the cell network.

  * ``cellbroadcast.danger.severe``

    Intended to be used to display severe danger warnings broadcasted by the cell network.

  * ``cellbroadcast.public-safety``

    Intended to be used to display public safety warnings broadcasted by the cell network.

  * ``cellbroadcast.amber-alert``

    Intended to be used to display amber alerts broadcasted by the cell network.

  * ``cellbroadcast.test``

    Intended to be used to display tests broadcasted by the cell network.

  * ``os.battery.low``

    Intended to be used to indicate that the system is low on battery.

  * ``browser.web-notification``

    Intended to be used by browsers to mark notifications send by websites via
    the `Notifications API <https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API>`_.

  Since: version 2



id
  Application-provided ID for this notification

notification
  Vardict with the serialized notification



.. _org.freedesktop.portal.Notification.RemoveNotification:

org.freedesktop.portal.Notification.RemoveNotification
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    RemoveNotification (
      IN id s
    )



Withdraws a notification.



id
  Application-provided ID for this notification


.. _org.freedesktop.portal.Notification Signals:

-------
Signals
-------

.. _org.freedesktop.portal.Notification::ActionInvoked:

org.freedesktop.portal.Notification::ActionInvoked
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    ActionInvoked (
      id s,
      action s,
      parameter av
    )



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

The ``parameter`` contains the following values in order:

#. The `target` for the action, if one was specified.

#. The `platform-data` as vardict (``a{sv}``) containing an ``activation-token`` (``s``) for
   `XDG Activation
   <https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/staging/xdg-activation/xdg-activation-v1.xml>`_

   Since: version 2

#. The user `response` for an action based on the purpose if applicable.

   Since: version 2



id
  the application-provided ID for the notification

action
  the name of the action

parameter
  an array containing additional information


