NotificationCenter
Handle events of notifications.
| Module | require("yue.gui") |
| Type | table |
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.
function app.notificationcenter.onnotificationclick(info)
print(info)
end
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().
Methods
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 onnotificationclose event.
setcomserveroptions(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
booleanregistercomserver() 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
writeregistry is set to false in setcomserveroptions.
Return
booleanremovecomserverfromregistry() Windows
Remove the app's COM server from registry.
gettoastactivatorclsid() Windows
Return current ToastActivatorCLSID.
Return
stringEvents
onnotificationshow(info)
Emitted when a notification has been displayed, the custom info of the
notification is passed.
Parameters
stringinfo
Preventable
No.onnotificationclose(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
stringinfo
Preventable
No.onnotificationclick(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
stringinfo
Preventable
No.onnotificationaction(actioninfo)
Emitted when user clicks on an action button of a notification, the custom
actioninfo string of the action button is passed.
Parameters
stringactioninfo
Preventable
No.onnotificationreply(info, 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
stringinfostringreply
Preventable
No.ontoastactivate(appusermodelid, invokedargs, 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
stringappusermodelidstringinvokedargstabledata - An array ofNotificationCenter::InputData.