Notifications

GNOME Shell provides implementations for freedesktop.org Notifications and GTK Notifications, serving as the notification server. These different implementations are usually hidden from application developers, who use the Gio.Notification abstraction to send notifications.

The GNOME Shell process itself is not a Gio.Application, and uses its own internal methods for showing notifications, bypassing the notification server. Extensions may also use these methods for displaying notifications.

Imports

The following imports should be all most developers need for Notifications:

import * as Main from 'resource:///org/gnome/shell/ui/main.js';
import * as MessageTray from 'resource:///org/gnome/shell/ui/messageTray.js';

Simple Notifications

Extensions that want to display a simple notification to the user, may use the method Main.notify().

Main.notify('Simple Notification', 'A notification with a title and body');

If the notification is communicating an error to the user, the Main.notifyError() method will also log the notification as a warning.

try {
    throw Error('File not found');
} catch (e) {
    Main.notifyError('Failed', e.message);
}

The logged warning will appear similar to this:

GNOME Shell-Message: 00:00:00.000: error: Failed to load configuration: File not found

Notifications

The MessageTray.Notification class represents a notification, which is usually an event from an application or system component.

const notification = new MessageTray.Notification({
    // The source of the notification
    source: customSource,
    // A title for the notification
    title: _('Custom Notification'),
    // The content of the notification
    body: _('This notification uses a custom source and policy'),
    // An icon for the notification (defaults to the source's icon)
    gicon: new Gio.ThemedIcon({name: 'dialog-warning'}),
    // Same as `gicon`, but takes a themed icon name
    iconName: 'dialog-warning',
    // The urgency of the notification
    urgency: MessageTray.Urgency.NORMAL,
});

When a notification is acknowledged in a permanent way, it will emit the destroy signal with a reason:

notification.connect('destroy', (_notification, reason) => {
    if (reason === MessageTray.NotificationDestroyedReason.DISMISSED)
        console.debug('The user closed the notification');
});

The reason argument may be one of the following:

• MessageTray.NotificationDestroyedReason.EXPIRED

  The notification was dismissed without being acknowledged by the user.

• MessageTray.NotificationDestroyedReason.DISMISSED

  The notification was closed by the user.

• MessageTray.NotificationDestroyedReason.SOURCE_CLOSED

  The notification was closed by its MessageTray.Source.

• MessageTray.NotificationDestroyedReason.REPLACED

  The notification was replaced by a newer version.

Actions

Every notification has a default action that is invoked when the notification itself is activated.

notification.connect('activated', _notification => {
    console.debug(`${notification.title}: notification activated`);
});

Notifications may also have 1-3 action buttons. Each button is added by calling addAction(), which takes a label and a callback (with no arguments):

notification.addAction(_('Close'), () => {
    console.debug('"Close" button activated');
});

A notification's actions can be removed with clearActions():

notification.clearActions();

Urgency

The urgency property controls how and when notifications are presented to the user. Since there may be a limit to how many notifications a source may show, a notification may replace another with a lower urgency.

may be one of the following:

• MessageTray.Urgency.LOW

  These notifications will be shown in the tray, but will not popup on the screen or be expanded.

• MessageTray.Urgency.NORMAL

  These notifications will be shown in the tray, and will popup on the screen unless the policy forbids it.

• MessageTray.Urgency.HIGH

  These notifications will be shown in the tray, and will popup on the screen unless the policy forbids it.

• MessageTray.Urgency.CRITICAL

  These notifications will always be shown, with the banner expanded, and must be acknowledged by the user before they will be dismissed.

Sources

The MessageTray.Source class represents a source of notifications, like an application or other desktop component. The simple notification helpers use the default system source:

const systemSource = MessageTray.getSystemSource();

const systemNotification = new MessageTray.Notification({
    source: systemSource,
    title: 'System Notification',
    body: 'This notification will appear to come from the system',
});
systemSource.addNotification(systemNotification);

An extension may create a custom source for managing its notifications, but must connect to the destroy signal to safely reuse it.

let notificationSource = null;

function getNotificationSource() {
    if (!notificationSource) {
        const notificationPolicy = new NotificationPolicy();

        notificationSource = new MessageTray.Source({
            // The source name (e.g. application name)
            title: _('Notifications Example'),
            // An icon for the source, used a fallback by notifications
            icon: new Gio.ThemedIcon({name: 'dialog-information'}),
            // Same as `icon`, but takes a themed icon name
            iconName: 'dialog-information',
            // The notification policy
            policy: notificationPolicy,
        });

        // Reset the notification source if it's destroyed
        notificationSource.connect('destroy', _source => {
            notificationSource = null;
        });
        Main.messageTray.add(notificationSource);
    }

    return notificationSource;
}

Policies

The MessageTray.NotificationPolicy class represents a policy that dictates how and when notifications are presented for a source. For example, whether to show on the lock screen or enable sound.

A custom notification policy is created by subclassing and overriding the read-only property getters:

const NotificationPolicy = GObject.registerClass(
class NotificationPolicy extends MessageTray.NotificationPolicy {
    /**
     * Whether notifications will be shown.
     *
     * @type {boolean}
     */
    get enable() {
        return true;
    }

    /**
     * Whether sound will be played.
     *
     * @type {boolean}
     */
    get enableSound() {
        return true;
    }

    /**
     * Whether the notification will popup outside of the tray.
     *
     * @type {boolean}
     */
    get showBanners() {
        return true;
    }

    /**
     * Whether the notification will always be expanded.
     *
     * @type {boolean}
     */
    get forceExpanded() {
        return false;
    }

    /**
     * Whether the notification will be shown on the lock screen.
     *
     * @type {boolean}
     */
    get showInLockScreen() {
        return false;
    }

    /**
     * Whether the notification content will be shown on the lock screen.
     *
     * @type {boolean}
     */
    get detailsInLockScreen() {
        return false;
    }

    /**
     * Called when the source is added to the message tray
     */
    store() {
    }
});

The default policy is MessageTray.NotificationGenericPolicy, which follows the desktop settings for notifications.