docs: added guide and updated docs for Tray (#29385)

* docs: added guide and updated docs for Tray

* docs: improve clarity
This commit is contained in:
George Xu 2021-06-14 18:34:53 -07:00 committed by GitHub
parent 3e2ec0e2ce
commit f022ead559
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 98 additions and 188 deletions

View file

@ -16,91 +16,12 @@
<p> <p>
Open the Open the
<a href="https://electronjs.org/docs/api/tray"> <a href="https://electronjs.org/docs/api/tray">
full API documentation (opens in new window) full API documentation
</a> </a>
in your browser. in your browser.
</p> </p>
</div> </div>
<div>
<div> <div>
<div>
<div>
<button id="put-in-tray">View Demo</button>
<span id="tray-countdown"></span>
</div>
<p>
The demo button sends a message to the main process using the
<code>ipc</code> module. In the main process the app is told to
place an icon, with a context menu, in the tray.
</p>
<p>
In this example the tray icon can be removed by clicking 'Remove' in
the context menu or selecting the demo button again.
</p>
<h5>Main Process</h5>
<pre>
<code>
const path = require('path')
const {ipcMain, app, Menu, Tray} = require('electron')
let appIcon = null
ipcMain.on('put-in-tray', (event) => {
const iconName = process.platform === 'win32' ? 'windows-icon.png' : 'iconTemplate.png'
const iconPath = path.join(__dirname, iconName)
appIcon = new Tray(iconPath)
const contextMenu = Menu.buildFromTemplate([{
label: 'Remove',
click: () => {
event.sender.send('tray-removed')
}
}])
appIcon.setToolTip('Electron Demo in the tray.')
appIcon.setContextMenu(contextMenu)
})
ipcMain.on('remove-tray', () => {
appIcon.destroy()
})
app.on('window-all-closed', () => {
if (appIcon) appIcon.destroy()
})
</code>
</pre>
<h5>Renderer Process</h5>
<pre>
<code>
const ipc = require('electron').ipcRenderer
const trayBtn = document.getElementById('put-in-tray')
let trayOn = false
trayBtn.addEventListener('click', function (event) {
if (trayOn) {
trayOn = false
document.getElementById('tray-countdown').innerHTML = ''
ipc.send('remove-tray')
} else {
trayOn = true
const message = 'Click demo again to remove.'
document.getElementById('tray-countdown').innerHTML = message
ipc.send('put-in-tray')
}
})
// Tray removed from context menu on icon
ipc.on('tray-removed', function () {
ipc.send('remove-tray')
trayOn = false
document.getElementById('tray-countdown').innerHTML = ''
})
</code>
</pre>
<div> <div>
<h2>ProTip</h2> <h2>ProTip</h2>
<strong>Tray support in Linux.</strong> <strong>Tray support in Linux.</strong>
@ -109,7 +30,7 @@ ipc.on('tray-removed', function () {
will need to install <code>libappindicator1</code> to make the will need to install <code>libappindicator1</code> to make the
tray icon work. See the tray icon work. See the
<a href="https://electronjs.org/docs/api/tray"> <a href="https://electronjs.org/docs/api/tray">
full API documentation (opens in new window) full API documentation
</a> </a>
for more details about using Tray on Linux. for more details about using Tray on Linux.
</p> </p>

File diff suppressed because one or more lines are too long

View file

@ -1,35 +0,0 @@
const { ipcRenderer, shell } = require('electron')
const trayBtn = document.getElementById('put-in-tray')
const links = document.querySelectorAll('a[href]')
let trayOn = false
trayBtn.addEventListener('click', function (event) {
if (trayOn) {
trayOn = false
document.getElementById('tray-countdown').innerHTML = ''
ipcRenderer.send('remove-tray')
} else {
trayOn = true
const message = 'Click demo again to remove.'
document.getElementById('tray-countdown').innerHTML = message
ipcRenderer.send('put-in-tray')
}
})
// Tray removed from context menu on icon
ipcRenderer.on('tray-removed', function () {
ipcRenderer.send('remove-tray')
trayOn = false
document.getElementById('tray-countdown').innerHTML = ''
})
Array.prototype.forEach.call(links, (link) => {
const url = link.getAttribute('href')
if (url.indexOf('http') === 0) {
link.addEventListener('click', (e) => {
e.preventDefault()
shell.openExternal(url)
})
}
})

83
docs/tutorial/tray.md Normal file
View file

@ -0,0 +1,83 @@
---
title: Tray
description: This guide will take you through the process of creating
a Tray icon with its own context menu to the system's notification area.
slug: tray
hide_title: true
---
# Tray
## Overview
<!-- ✍ Update this section if you want to provide more details -->
This guide will take you through the process of creating a
[Tray](https://www.electronjs.org/docs/api/tray) icon with
its own context menu to the system's notification area.
On MacOS and Ubuntu, the Tray will be located on the top
right corner of your screen, adjacent to your battery and wifi icons.
On Windows, the Tray will usually be located in the bottom right corner.
## Example
### main.js
First we must import `app`, `Tray`, `Menu`, `nativeImage` from `electron`.
```js
const { app, Tray, Menu, nativeImage } = require('electron')
```
Next we will create our Tray. To do this, we will use a
[`NativeImage`](https://www.electronjs.org/docs/api/native-image) icon,
which can be created through any one of these
[methods](https://www.electronjs.org/docs/api/native-image#methods).
Note that we wrap our Tray creation code within an
[`app.whenReady`](https://www.electronjs.org/docs/api/app#appwhenready)
as we will need to wait for our electron app to finish initializing.
```js title='main.js'
let tray
app.whenReady().then(() => {
const icon = nativeImage.createFromPath('path/to/asset.png')
tray = new Tray(icon)
// note: your contextMenu, Tooltip and Title code will go here!
})
```
Great! Now we can start attaching a context menu to our Tray, like so:
```js
const contextMenu = Menu.buildFromTemplate([
{ label: 'Item1', type: 'radio' },
{ label: 'Item2', type: 'radio' },
{ label: 'Item3', type: 'radio', checked: true },
{ label: 'Item4', type: 'radio' }
])
tray.setContextMenu(contextMenu)
```
The code above will create 4 separate radio-type items in the context menu.
To read more about constructing native menus, click
[here](https://www.electronjs.org/docs/api/menu#menubuildfromtemplatetemplate).
Finally, let's give our tray a tooltip and a title.
```js
tray.setToolTip('This is my application')
tray.setTitle('This is my title')
```
## Conclusion
After you start your electron app, you should see the Tray residing
in either the top or bottom right of your screen, depending on your
operating system.
```fiddle docs/fiddles/native-ui/tray
```