NotificationCenter

Handle events of notifications.

Modulerequire("yue.gui")
Typetable

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

boolean

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 writeregistry is set to false in setcomserveroptions.

Return

boolean

removecomserverfromregistry() Windows

Remove the app's COM server from registry.

gettoastactivatorclsid() Windows

Return current ToastActivatorCLSID.

Return

string

Events

onnotificationshow(info)

Emitted when a notification has been displayed, the custom info of the notification is passed.

Parameters

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

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

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

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

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

Preventable

Yes.