Notification
Send native notifications.
| Header | #include "nativeui/notification.h" |
| Namespace | namespace nu |
| Type | class (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
const std::string&title
void SetBody(const std::string& body)
Set the body text of the notification.
Parameters
const std::string&body
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
const std::string&info
std::string GetInfo() const
Return the attached user info.
Return
std::stringvoid 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
const std::vector<Notification::Action>&actions - An array ofNotification::Action.
void SetSilent(bool silent)
Set whether to play sound when the notification is displayed.
Parameters
boolsilent
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
scoped_refptr<Image>image
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
const base::FilePath&path
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
std::optional<std::wstring>placement
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
boolhas
void SetResponsePlaceholder(const std::string& placeholder) macOS Windows
The the placeholder of the input field.
Parameters
const std::string&placeholder
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
const std::string&identifier
std::string GetIdentifier() const macOS Windows
Return the unique identifier of the notification.
Return
std::stringvoid 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::optional<std::wstring>xml
std::wstring GetXML() const Windows
Return the XML representation of the toast notification.
Return
std::wstring