NotificationCenter
Handle events of notifications.
| Header | #include "nativeui/notification_center.h" |
| Namespace | namespace nu |
| Type | class |
The NotificationCenter API is responsible for handling events of
notifications, for sending notifications, the Notification API should
be used.
For most platforms, the notifications will persist after the app is quit, so
the source notification of the received event may be sent by other instances
of the app. For this reason, you do not get the source Notification instance
when handling events, and you should not do bookkeeping to try to do so.
To pass information in notifications, you should use
Notification::SetInfo(info) to store a custom string, which will
be passed to the event handlers of NotificationCenter.
auto* notification_center = nu::NotificationCenter::GetCurrent();
notification_center->on_notification_click.Connect([=](const std::string& info) {
LOG(ERROR) << "Clicked: " << info;
});
Linux notices
On Windows and macOS, clicking a notification will start the app that sent the notification, but this feature has not been implemented on Linux yet.
On Linux due to the limitation of
Desktop Notifications Specification,
the custom information attached to the notification is not persisted after
the app is quit, so if a notification is sent by other instances of the app,
the info parameter will be empty in its events.
Windows notices
On Windows receiving notification events is implemented by starting a COM server, which is started automatcially when any event is subscribed.
The COM server must has a ToastActivatorCLSID, which will be automatcially
generated from the app's AppUserModelID if non is specified. It is
recommended to use uuidgen.exe to generate one and set it explicitly
with NotificationCenter::SetCOMServerOptions(options).
For the COM server to receive events from Action Center, there must be a start
menu shortcut, with AppUserModelID and ToastActivatorCLSID properties
assigned to it. The App::CreateStartMenuShortcut(options) API can be
used to create one for testing.
It is also possible to start the app by clicking the notification, after the
app has quit, but it requires registering the COM server in registry, which
is done automatcially when any event is subscribed. This behavior can be
turned off with NotificationCenter::SetCOMServerOptions(options),
and the item in registry can be removed with
NotificationCenter::RemoveCOMServerFromRegistry().
Class methods
NotificationCenter* GetCurrent()
Return current NotificationCenter instance.
Return
NotificationCenter*Methods
void Clear()
Remove all notifications sent by this app.
Due to the limitations of system APIs, on Linux only notifications created
by current process can be cleared, and on Windows clearing notifications
won't emit the on_notification_close event.
bool SetCOMServerOptions(NotificationCenter::COMServerOptions options) Windows
Set COM server related options, false will be returned if the passed
ToastActivatorCLSID is invalid.
This API should be only called before subscribing to any event.
Parameters
Return
boolbool RegisterCOMServer() Windows
Register the COM server.
Usually the COM server is automatcially registered when any event is
subscribed, but this API can be used to register COM server manully if
write_registry is set to false in SetCOMServerOptions.
Return
boolvoid RemoveCOMServerFromRegistry() Windows
Remove the app's COM server from registry.
const std::wstring& GetToastActivatorCLSID() Windows
Return current ToastActivatorCLSID.
Return
const std::wstring&Events
void on_notification_show(const std::string& info)
Emitted when a notification has been displayed, the custom info of the
notification is passed.
Parameters
const std::string&info
Preventable
No.void on_notification_close(const std::string& info)
Emitted when a notification has been closed without activation, the custom
info of the notification is passed.
Note that this event is not guarenteed to emit for notifications, the system may choose to not notify the app when a notification is closed. So you should not do bookkeeping of notifications and count on this API to clear closed notifications.
Parameters
const std::string&info
Preventable
No.void on_notification_click(const std::string& info)
Emitted when user clicks on the body of a notification, the custom
info of the notification is passed.
On Linux due to the limitation of
Desktop Notifications Specification,
only the custom info of notifications sent by current app will be
passed, i.e. if the app received a notification sent by other instances
of the app, the info will be empty.
Parameters
const std::string&info
Preventable
No.void on_notification_action(const std::string& action_info)
Emitted when user clicks on an action button of a notification, the custom
action_info string of the action button is passed.
Parameters
const std::string&action_info
Preventable
No.void on_notification_reply(const std::string& info, std::string reply) macOS Windows
Emitted when user sends a text using inline reply in a notification, the
custom info of the notification, and the reply string will be passed.
On Linux due to the limitation of
Desktop Notifications Specification,
only the custom info of notifications sent by current app will be
passed, i.e. if the app received a notification sent by other instances
of the app, the info will be empty.
Parameters
const std::string&infostd::stringreply
Preventable
No.bool on_toast_activate(std::wstring app_user_model_id, std::wstring invoked_args, std::vector<NotificationCenter::InputData> data) Windows
Emitted when the notification activator COM server receives the Activate message.
This event is useful if you are using custom XML in the notification and want to handle the events yourself.
Returning true will prevent normal notifications event from emitting.
Parameters
std::wstringapp_user_model_idstd::wstringinvoked_argsstd::vector<NotificationCenter::InputData>data - An array ofNotificationCenter::InputData.