Notification

Send native notifications.

Modulerequire("gui")
TypeClass

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

Notification

Methods

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

setBody(body)

Set the body text of the notification.

Parameters

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

getInfo()

Return the attached user info.

Return

String

setActions(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

setSilent(silent)

Set whether to play sound when the notification is displayed.

Parameters

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

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

setImagePlacement(placement) Windows

Set the placement attribute of the image.

The most common used placements are "appLogoOverride" and "hero".

Parameters

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

setResponsePlaceholder(placeholder) macOS Windows

The the placeholder of the input field.

Parameters

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

getIdentifier() macOS Windows

Return the unique identifier of the notification.

Return

String

setXML(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

getXML() Windows

Return the XML representation of the toast notification.

Return

String