:right-sidebar: True Notification =================================================================== .. currentmodule:: gi.repository.Gio .. versionadded:: 2.40 .. class:: Notification(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` ``GNotification`` is a mechanism for creating a notification to be shown to the user — typically as a pop-up notification presented by the desktop environment shell. The key difference between ``GNotification`` and other similar APIs is that, if supported by the desktop environment, notifications sent with ``GNotification`` will persist after the application has exited, and even across system reboots. Since the user may click on a notification while the application is not running, applications using ``GNotification`` should be able to be started as a D-Bus service, using :obj:`~gi.repository.Gio.Application`\. In order for ``GNotification`` to work, the application must have installed a ``.desktop`` file. For example: .. code-block:: :dedent: [Desktop Entry] Name=Test Application Comment=Description of what Test Application does Exec=gnome-test-application Icon=org.gnome.TestApplication Terminal=false Type=Application Categories=GNOME;GTK;TestApplication Category; StartupNotify=true DBusActivatable=true X-GNOME-UsesNotifications=true The ``X-GNOME-UsesNotifications`` key indicates to GNOME Control Center that this application uses notifications, so it can be listed in the Control Center’s ‘Notifications’ panel. The ``.desktop`` file must be named as ``org.gnome.TestApplication.desktop``\, where ``org.gnome.TestApplication`` is the ID passed to :obj:`~gi.repository.Gio.Application.new`\. User interaction with a notification (either the default action, or buttons) must be associated with actions on the application (ie: ``app.`` actions). It is not possible to route user interaction through the notification itself, because the object will not exist if the application is autostarted as a result of a notification being clicked. A notification can be sent with :obj:`~gi.repository.Gio.Application.send_notification`\. Constructors ------------ .. rst-class:: interim-class .. class:: Notification :no-index: .. classmethod:: new(title: str) -> ~gi.repository.Gio.Notification Creates a new :obj:`~gi.repository.Gio.Notification` with ``title`` as its title. After populating ``notification`` with more details, it can be sent to the desktop shell with :func:`~gi.repository.Gio.Application.send_notification`. Changing any properties after this call will not have any effect until resending ``notification``\. .. versionadded:: 2.40 :param title: the title of the notification Methods ------- .. rst-class:: interim-class .. class:: Notification :no-index: .. method:: add_button(label: str, detailed_action: str) -> None Adds a button to ``notification`` that activates the action in ``detailed_action`` when clicked. That action must be an application-wide action (starting with "app."). If ``detailed_action`` contains a target, the action will be activated with that target as its parameter. See :func:`~gi.repository.Gio.Action.parse_detailed_name` for a description of the format for ``detailed_action``\. .. versionadded:: 2.40 :param label: label of the button :param detailed_action: a detailed action name .. method:: add_button_with_target(label: str, action: str, target: ~gi.repository.GLib.Variant | None = None) -> None Adds a button to ``notification`` that activates ``action`` when clicked. ``action`` must be an application-wide action (it must start with "app."). If ``target_format`` is given, it is used to collect remaining positional parameters into a :obj:`~gi.repository.GLib.Variant` instance, similar to :func:`~gi.repository.GLib.Variant.new`. ``action`` will be activated with that :obj:`~gi.repository.GLib.Variant` as its parameter. .. versionadded:: 2.40 :param label: label of the button :param action: an action name :param target: .. method:: set_body(body: str | None = None) -> None Sets the body of ``notification`` to ``body``\. .. versionadded:: 2.40 :param body: the new body for ``notification``\, or :const:`None` .. method:: set_category(category: str | None = None) -> None Sets the type of ``notification`` to ``category``\. Categories have a main type like ``email``\, ``im`` or ``device`` and can have a detail separated by a ``.``\, e.g. ``im.received`` or ``email.arrived``\. Setting the category helps the notification server to select proper feedback to the user. Standard categories are `listed in the specification `__\. .. versionadded:: 2.70 :param category: the category for ``notification``\, or :const:`None` for no category .. method:: set_default_action(detailed_action: str) -> None Sets the default action of ``notification`` to ``detailed_action``\. This action is activated when the notification is clicked on. The action in ``detailed_action`` must be an application-wide action (it must start with "app."). If ``detailed_action`` contains a target, the given action will be activated with that target as its parameter. See :func:`~gi.repository.Gio.Action.parse_detailed_name` for a description of the format for ``detailed_action``\. When no default action is set, the application that the notification was sent on is activated. .. versionadded:: 2.40 :param detailed_action: a detailed action name .. method:: set_default_action_and_target(action: str, target: ~gi.repository.GLib.Variant | None = None) -> None Sets the default action of ``notification`` to ``action``\. This action is activated when the notification is clicked on. It must be an application-wide action (it must start with "app."). If ``target_format`` is given, it is used to collect remaining positional parameters into a :obj:`~gi.repository.GLib.Variant` instance, similar to :func:`~gi.repository.GLib.Variant.new`. ``action`` will be activated with that :obj:`~gi.repository.GLib.Variant` as its parameter. When no default action is set, the application that the notification was sent on is activated. .. versionadded:: 2.40 :param action: an action name :param target: .. method:: set_icon(icon: ~gi.repository.Gio.Icon) -> None Sets the icon of ``notification`` to ``icon``\. .. versionadded:: 2.40 :param icon: the icon to be shown in ``notification``\, as a :obj:`~gi.repository.Gio.Icon` .. method:: set_priority(priority: ~gi.repository.Gio.NotificationPriority) -> None Sets the priority of ``notification`` to ``priority``\. See :obj:`~gi.repository.Gio.NotificationPriority` for possible values. :param priority: a :obj:`~gi.repository.Gio.NotificationPriority` .. method:: set_title(title: str) -> None Sets the title of ``notification`` to ``title``\. .. versionadded:: 2.40 :param title: the new title for ``notification`` .. method:: set_urgent(urgent: bool) -> None Deprecated in favor of :func:`~gi.repository.Gio.Notification.set_priority`. .. versionadded:: 2.40 .. deprecated:: 2.42 Since 2.42, this has been deprecated in favour of :func:`~gi.repository.Gio.Notification.set_priority`. :param urgent: :const:`True` if ``notification`` is urgent