Notification
Send native notifications.
| Module | require("gui") |
| Type | Class |
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.
gui.app.setName("MyApp")
if (process.platform !== 'darwin')
gui.app.setID("org.yue.myapp")
else if (gui.app.getID().length === 0)
console.error("Unable to send notifications due to app not being bundled")
// Create start menu shortcut for testing.
if (process.platform === "win32")
gui.app.createStartMenuShortcut({})
const notification = gui.Notification.create()
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.
Class methods
create()
Create a new Notification instance.
Return
NotificationMethods
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.
close()
Close the notification.
setTitle(title)
Set the title of the notification.
Parameters
Stringtitle
setBody(body)
Set the body text of the notification.
Parameters
Stringbody
setInfo(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
Stringinfo
getInfo()
Return the attached user info.
Return
StringsetActions(actions)
Set the buttons to be displayed in the notification.
The onNotificationAction event of NotificationCenter
will be emitted when user clicks one of the buttons.
Parameters
Arrayactions - An array ofNotification::Action.
setSilent(silent)
Set whether to play sound when the notification is displayed.
Parameters
Booleansilent
setImage(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
Imageimage
setImagePath(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
Stringpath
setImagePlacement(placement) Windows
Set the placement attribute of the image.
The most common used placements are "appLogoOverride" and "hero".
Parameters
Stringplacement
setHasReplyButton(has) macOS Windows
Set whether to display an input field and a reply button in the notification.
The onNotificationReply event of NotificationCenter
will be emitted when user sends a reply in the notification.
Parameters
Booleanhas
setResponsePlaceholder(placeholder) macOS Windows
The the placeholder of the input field.
Parameters
Stringplaceholder
setIdentifier(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
Stringidentifier
getIdentifier() macOS Windows
Return the unique identifier of the notification.
Return
StringsetXML(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
Stringxml
getXML() Windows
Return the XML representation of the toast notification.
Return
String