Notification

Send native notifications.

Header#include "nativeui/notification.h"
Namespacenamespace nu
Typeclass (RefCounted)

The Notification API is responsible for sending notifications, for handling events of notifications, the NotificationCenter API should be used.

Before sending notifications, you should set app's ID and name otherwise the notifications may not be displayed.

auto* app = nu::App::GetCurrent();
app->SetName("MyApp");
#if defined(OS_LINUX) || defined(OS_WIN)
app->SetID("org.yue.myapp");
#else
if (app->GetID().empty())
  LOG(ERROR) << "Unable to send notifications due to app not being bundled";
#endif

#if defined(OS_WIN)
// Create start menu shortcut for testing.
app->CreateStartMenuShortcut(nu::App::ShortcutOptions());
#endif

scoped_refptr<nu::Notification> notification = new nu::Notification;
notification->SetTitle("Title");
notification->SetBody("Message");
notification->SetInfo("first-notification");
notification->Show();

Platform requirements

On macOS, only bundled apps can send notifications. To check if the app is bundled, you can check whether App::GetID() returns a non-empty string.

On Linux, Notification is implemented by sending DBus messages following the Desktop Notifications Specification, the desktop environment must has a desktop notifications service running to show the notifications.

On Windows, to display the notifications the app must has an AppUserModelID, and a shortcut on the start menu. For testing purpose, you can use the App::CreateStartMenuShortcut(options) API to create a start menu shortcut file.

Also on Windows Notification uses toast notifications under the hood, and currently only Windows 10 and above are supported.

Methods

void Show()

Display the notification.

If the notification has already been displayed, calling this method again will update the contents of the notification. If the notification has been closed, calling this method will show the notification again.

On Windows due to platform limitation, only the title and body of the notification can be updated after it has been displayed.

void Close()

Close the notification.

void SetTitle(const std::string& title)

Set the title of the notification.

Parameters

void SetBody(const std::string& body)

Set the body text of the notification.

Parameters

void SetInfo(const std::string& info)

Set the user info to be attached to the notification.

When handling notification events with NotificationCenter, only the user info will be passed to the event handler.

Parameters

std::string GetInfo() const

Return the attached user info.

Return

std::string

void SetActions(const std::vector<Notification::Action>& actions)

Set the buttons to be displayed in the notification.

The on_notification_action event of NotificationCenter will be emitted when user clicks one of the buttons.

Parameters

void SetSilent(bool silent)

Set whether to play sound when the notification is displayed.

Parameters

void SetImage(scoped_refptr<Image> image)

Set the image shown in the content of the notification.

Different platforms may choose to put the image in different places, there is no guarentee on where the image is placed.

Parameters

void SetImagePath(const base::FilePath& path)

Set the file path of the image shown in the content of the notification.

This method is usually faster than reading a file from disk and passing its content to SetImage, so it is recommended to use this method over SetImage if the image is stored on disk.

Different platforms may choose to put the image in different places, there is no guarentee on where the image is placed.

Parameters

void SetImagePlacement(std::optional<std::wstring> placement) Windows

Set the placement attribute of the image.

The most common used placements are "appLogoOverride" and "hero".

Parameters

void SetHasReplyButton(bool has) macOS Windows

Set whether to display an input field and a reply button in the notification.

The on_notification_reply event of NotificationCenter will be emitted when user sends a reply in the notification.

Parameters

void SetResponsePlaceholder(const std::string& placeholder) macOS Windows

The the placeholder of the input field.

Parameters

void SetIdentifier(const std::string& identifier) macOS Windows

Set an unique identifier that can identifies a notification.

When there is already a displayed notification with the same identifier, showing this notification will update its contents.

On Windows due to platform limitation, only the title and body of the notification can be updated after it has been displayed.

Note that there is no equivalent API on Linux, to update an existing notification's contents you have to keep the instance of the notification and call its Show method.

Parameters

std::string GetIdentifier() const macOS Windows

Return the unique identifier of the notification.

Return

std::string

void SetXML(std::optional<std::wstring> xml) Windows

Set custom XML of the toast notification.

On Windows the notification can have rich contents and the Notification APIs do not cover all the possible features. In case you want to show some rich contents, you can use this API to set raw XML of the notification.

You can find documentation on the XML schema and tools to generate XML at here.

Parameters

std::wstring GetXML() const Windows

Return the XML representation of the toast notification.

Return

std::wstring