* restore stash revert some things work others dont tracking area for rescue manual popup restore drag n drop cleanup * fix: make tray not block main process (#18880) * fix: make tray not block main process * make AtomMenuModel refcounted * add support for ansi codes in title add remove TODOs * chore: use ScopedPumpMessagesInPrivateModes in tray (#18977) * chore: use ScopedPumpMessagesInPrivateModes in tray * revert refcounting of AtomMenuModel * Prefer WeakPtr for posting tasks to handle unexpected destruction * cleanup .h * cleanup .mm * add imports add missing include * fix: crash when tray popup called twice (#18999) * remove highlightMode and TODOs * remove unnecessary copy
6.4 KiB
Class: Tray
Add icons and context menus to the system's notification area.
Process: Main
Tray
is an EventEmitter.
const { app, Menu, Tray } = require('electron')
let tray = null
app.on('ready', () => {
tray = new Tray('/path/to/my/icon')
const contextMenu = Menu.buildFromTemplate([
{ label: 'Item1', type: 'radio' },
{ label: 'Item2', type: 'radio' },
{ label: 'Item3', type: 'radio', checked: true },
{ label: 'Item4', type: 'radio' }
])
tray.setToolTip('This is my application.')
tray.setContextMenu(contextMenu)
})
Platform limitations:
- On Linux the app indicator will be used if it is supported, otherwise
GtkStatusIcon
will be used instead. - On Linux distributions that only have app indicator support, you have to
install
libappindicator1
to make the tray icon work. - App indicator will only be shown when it has a context menu.
- When app indicator is used on Linux, the
click
event is ignored. - On Linux in order for changes made to individual
MenuItem
s to take effect, you have to callsetContextMenu
again. For example:
const { app, Menu, Tray } = require('electron')
let appIcon = null
app.on('ready', () => {
appIcon = new Tray('/path/to/my/icon')
const contextMenu = Menu.buildFromTemplate([
{ label: 'Item1', type: 'radio' },
{ label: 'Item2', type: 'radio' }
])
// Make a change to the context menu
contextMenu.items[1].checked = false
// Call this again for Linux because we modified the context menu
appIcon.setContextMenu(contextMenu)
})
- On Windows it is recommended to use
ICO
icons to get best visual effects.
If you want to keep exact same behaviors on all platforms, you should not
rely on the click
event and always attach a context menu to the tray icon.
new Tray(image)
image
(NativeImage | String)
Creates a new tray icon associated with the image
.
Instance Events
The Tray
module emits the following events:
Event: 'click'
Returns:
event
KeyboardEventbounds
Rectangle - The bounds of tray icon.position
Point - The position of the event.
Emitted when the tray icon is clicked.
Event: 'right-click' macOS Windows
Returns:
event
KeyboardEventbounds
Rectangle - The bounds of tray icon.
Emitted when the tray icon is right clicked.
Event: 'double-click' macOS Windows
Returns:
event
KeyboardEventbounds
Rectangle - The bounds of tray icon.
Emitted when the tray icon is double clicked.
Event: 'balloon-show' Windows
Emitted when the tray balloon shows.
Event: 'balloon-click' Windows
Emitted when the tray balloon is clicked.
Event: 'balloon-closed' Windows
Emitted when the tray balloon is closed because of timeout or user manually closes it.
Event: 'drop' macOS
Emitted when any dragged items are dropped on the tray icon.
Event: 'drop-files' macOS
Returns:
event
Eventfiles
String[] - The paths of the dropped files.
Emitted when dragged files are dropped in the tray icon.
Event: 'drop-text' macOS
Returns:
event
Eventtext
String - the dropped text string.
Emitted when dragged text is dropped in the tray icon.
Event: 'drag-enter' macOS
Emitted when a drag operation enters the tray icon.
Event: 'drag-leave' macOS
Emitted when a drag operation exits the tray icon.
Event: 'drag-end' macOS
Emitted when a drag operation ends on the tray or ends at another location.
Event: 'mouse-enter' macOS
Returns:
event
KeyboardEventposition
Point - The position of the event.
Emitted when the mouse enters the tray icon.
Event: 'mouse-leave' macOS
Returns:
event
KeyboardEventposition
Point - The position of the event.
Emitted when the mouse exits the tray icon.
Event: 'mouse-move' macOS Windows
Returns:
event
KeyboardEventposition
Point - The position of the event.
Emitted when the mouse moves in the tray icon.
Instance Methods
The Tray
class has the following methods:
tray.destroy()
Destroys the tray icon immediately.
tray.setImage(image)
image
(NativeImage | String)
Sets the image
associated with this tray icon.
tray.setPressedImage(image)
macOS
image
(NativeImage | String)
Sets the image
associated with this tray icon when pressed on macOS.
tray.setToolTip(toolTip)
toolTip
String
Sets the hover text for this tray icon.
tray.setTitle(title)
macOS
title
String
Sets the title displayed next to the tray icon in the status bar (Support ANSI colors).
tray.getTitle()
macOS
Returns String
- the title displayed next to the tray icon in the status bar
tray.setIgnoreDoubleClickEvents(ignore)
macOS
ignore
Boolean
Sets the option to ignore double click events. Ignoring these events allows you to detect every individual click of the tray icon.
This value is set to false by default.
tray.getIgnoreDoubleClickEvents()
macOS
Returns Boolean
- Whether double click events will be ignored.
tray.displayBalloon(options)
Windows
options
Objecticon
(NativeImage | String) (optional) -title
Stringcontent
String
Displays a tray balloon.
tray.popUpContextMenu([menu, position])
macOS Windows
menu
Menu (optional)position
Point (optional) - The pop up position.
Pops up the context menu of the tray icon. When menu
is passed, the menu
will
be shown instead of the tray icon's context menu.
The position
is only available on Windows, and it is (0, 0) by default.
tray.setContextMenu(menu)
menu
Menu | null
Sets the context menu for this icon.
tray.getBounds()
macOS Windows
Returns Rectangle
The bounds
of this tray icon as Object
.
tray.isDestroyed()
Returns Boolean
- Whether the tray icon is destroyed.