mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions

docs: revised windows taskbar page (#26120)

Browse source 
* docs: revised windows taskbar page

* docs: fixed mentions related to windows taskbar
This commit is contained in:
Antonio 2020-10-27 03:31:40 +02:00 committed by GitHub
parent ae323565f7
commit 33ac7dbd48
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 90 additions and 41 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

131
docs/tutorial/windows-taskbar.md
View file

@ -1,20 +1,21 @@
# Windows Taskbar # Windows Taskbar
Electron has APIs to configure the app's icon in the Windows taskbar. Supported ## Overview
are the [creation of a `JumpList`](#jumplist),
Electron has APIs to configure the app's icon in the Windows taskbar. This API
supports both Windows-only features like [creation of a `JumpList`](#jumplist),
[custom thumbnails and toolbars](#thumbnail-toolbars), [custom thumbnails and toolbars](#thumbnail-toolbars),
[icon overlays](#icon-overlays-in-taskbar), and the so-called [icon overlays](#icon-overlays-in-taskbar), and the so-called
["Flash Frame" effect](#flash-frame), but ["Flash Frame" effect](#flash-frame), and cross-platform features
Electron also uses the app's dock icon to implement cross-platform features
like [recent documents][recent-documents] and like [recent documents][recent-documents] and
[application progress][progress-bar]. [application progress][progress-bar].
## JumpList ## JumpList
Windows allows apps to define a custom context menu that shows up when users Windows allows apps to define a custom context menu that shows up when users
right-click the app's icon in the task bar. That context menu is called right-click the app's icon in the taskbar. That context menu is called
`JumpList`. You specify custom actions in the `Tasks` category of JumpList, `JumpList`. You specify custom actions in the `Tasks` category of JumpList,
as quoted from MSDN: as quoted from [MSDN][msdn-jumplist]:
> Applications define tasks based on both the program's features and the key > Applications define tasks based on both the program's features and the key
> things a user is expected to do with them. Tasks should be context-free, in > things a user is expected to do with them. Tasks should be context-free, in
@ -33,19 +34,29 @@ as quoted from MSDN:
> confuse the user who does not expect that portion of the destination list to > confuse the user who does not expect that portion of the destination list to
> change. > change.
__Tasks of Internet Explorer:__
![IE](https://i-msdn.sec.s-msft.com/dynimg/IC420539.png) ![IE](https://i-msdn.sec.s-msft.com/dynimg/IC420539.png)
> NOTE: The screenshot above is an example of general tasks of
Internet Explorer
Unlike the dock menu in macOS which is a real menu, user tasks in Windows work Unlike the dock menu in macOS which is a real menu, user tasks in Windows work
like application shortcuts such that when user clicks a task, a program will be like application shortcuts. For example, when a user clicks a task, the program
executed with specified arguments. will be executed with specified arguments.
To set user tasks for your application, you can use To set user tasks for your application, you can use
[app.setUserTasks][setusertaskstasks] API: [app.setUserTasks][setusertaskstasks] API.
#### Examples
##### Set user tasks
Starting with a working application from the
[Quick Start Guide](quick-start.md), update the `main.js` file with the
following lines:
```javascript ```javascript
const { app } = require('electron') const { app } = require('electron')
app.setUserTasks([ app.setUserTasks([
{ {
program: process.execPath, program: process.execPath,
@ -58,25 +69,29 @@ app.setUserTasks([
]) ])
``` ```
To clean your tasks list, call `app.setUserTasks` with an empty array: ##### Clear tasks list
To clear your tasks list, you need to call `app.setUserTasks` with an empty
array in the `main.js` file.
```javascript ```javascript
const { app } = require('electron') const { app } = require('electron')
app.setUserTasks([]) app.setUserTasks([])
``` ```
The user tasks will still show even after your application closes, so the icon > NOTE: The user tasks will still be displayed even after closing your
and program path specified for a task should exist until your application is application, so the icon and program path specified for a task should exist until your application is uninstalled.
uninstalled.
[msdn-jumplist]: https://docs.microsoft.com/en-us/windows/win32/shell/taskbar-extensions#tasks
## Thumbnail Toolbars ### Thumbnail Toolbars
On Windows you can add a thumbnail toolbar with specified buttons in a taskbar On Windows, you can add a thumbnail toolbar with specified buttons to a taskbar
layout of an application window. It provides users a way to access to a layout of an application window. It provides users with a way to access a
particular window's command without restoring or activating the window. particular window's command without restoring or activating the window.
From MSDN, it's illustrated: As quoted from [MSDN][msdn-thumbnail]:
> This toolbar is the familiar standard toolbar common control. It has a > This toolbar is the familiar standard toolbar common control. It has a
> maximum of seven buttons. Each button's ID, image, tooltip, and state are defined > maximum of seven buttons. Each button's ID, image, tooltip, and state are defined
@ -87,12 +102,21 @@ From MSDN, it's illustrated:
> For example, Windows Media Player might offer standard media transport controls > For example, Windows Media Player might offer standard media transport controls
> such as play, pause, mute, and stop. > such as play, pause, mute, and stop.
__Thumbnail toolbar of Windows Media Player:__
![player](https://i-msdn.sec.s-msft.com/dynimg/IC420540.png) ![player](https://i-msdn.sec.s-msft.com/dynimg/IC420540.png)
You can use [BrowserWindow.setThumbarButtons][setthumbarbuttons] to set > NOTE: The screenshot above is an example of thumbnail toolbar of Windows
thumbnail toolbar in your application: Media Player
To set thumbnail toolbar in your application, you need to use
[BrowserWindow.setThumbarButtons][setthumbarbuttons]
#### Examples
##### Set thumbnail toolbar
Starting with a working application from the
[Quick Start Guide](quick-start.md), update the `main.js` file with the
following lines:
```javascript ```javascript
const { BrowserWindow } = require('electron') const { BrowserWindow } = require('electron')
@ -114,8 +138,10 @@ win.setThumbarButtons([
]) ])
``` ```
To clean thumbnail toolbar buttons, just call `BrowserWindow.setThumbarButtons` ##### Clear thumbnail toolbar
with an empty array:
To clear thumbnail toolbar buttons, you need to call
`BrowserWindow.setThumbarButtons` with an empty array in the `main.js` file.
```javascript ```javascript
const { BrowserWindow } = require('electron') const { BrowserWindow } = require('electron')
@ -124,11 +150,14 @@ const win = new BrowserWindow()
win.setThumbarButtons([]) win.setThumbarButtons([])
``` ```
[msdn-thumbnail]: https://docs.microsoft.com/en-us/windows/win32/shell/taskbar-extensions#thumbnail-toolbars
## Icon Overlays in Taskbar ### Icon Overlays in Taskbar
On Windows a taskbar button can use a small overlay to display application On Windows, a taskbar button can use a small overlay to display application
status, as quoted from MSDN: status.
As quoted from [MSDN][msdn-icon-overlay]:
> Icon overlays serve as a contextual notification of status, and are intended > Icon overlays serve as a contextual notification of status, and are intended
> to negate the need for a separate notification area status icon to communicate > to negate the need for a separate notification area status icon to communicate
@ -140,42 +169,62 @@ status, as quoted from MSDN:
> network status, messenger status, or new mail. The user should not be > network status, messenger status, or new mail. The user should not be
> presented with constantly changing overlays or animations. > presented with constantly changing overlays or animations.
__Overlay on taskbar button:__
![Overlay on taskbar button](https://i-msdn.sec.s-msft.com/dynimg/IC420441.png) ![Overlay on taskbar button](https://i-msdn.sec.s-msft.com/dynimg/IC420441.png)
To set the overlay icon for a window, you can use the > NOTE: The screenshot above is an example of overlay on a taskbar button
[BrowserWindow.setOverlayIcon][setoverlayicon] API:
To set the overlay icon for a window, you need to use the
[BrowserWindow.setOverlayIcon][setoverlayicon] API.
#### Example
Starting with a working application from the
[Quick Start Guide](quick-start.md), update the `main.js` file with the
following lines:
```javascript ```javascript
const { BrowserWindow } = require('electron') const { BrowserWindow } = require('electron')
const win = new BrowserWindow() const win = new BrowserWindow()
win.setOverlayIcon('path/to/overlay.png', 'Description for overlay') win.setOverlayIcon('path/to/overlay.png', 'Description for overlay')
``` ```
[msdn-icon-overlay]: https://docs.microsoft.com/en-us/windows/win32/shell/taskbar-extensions#icon-overlays
## Flash Frame ### Flash Frame
On Windows you can highlight the taskbar button to get the user's attention. On Windows, you can highlight the taskbar button to get the user's attention.
This is similar to bouncing the dock icon on macOS. This is similar to bouncing the dock icon in macOS.
From the MSDN reference documentation:
As quoted from [MSDN][msdn-flash-frame]:
> Typically, a window is flashed to inform the user that the window requires > Typically, a window is flashed to inform the user that the window requires
> attention but that it does not currently have the keyboard focus. > attention but that it does not currently have the keyboard focus.
To flash the BrowserWindow taskbar button, you can use the To flash the BrowserWindow taskbar button, you need to use the
[BrowserWindow.flashFrame][flashframe] API: [BrowserWindow.flashFrame][flashframe] API.
#### Example
Starting with a working application from the
[Quick Start Guide](quick-start.md), update the `main.js` file with the
following lines:
```javascript ```javascript
const { BrowserWindow } = require('electron') const { BrowserWindow } = require('electron')
const win = new BrowserWindow() const win = new BrowserWindow()
win.once('focus', () => win.flashFrame(false)) win.once('focus', () => win.flashFrame(false))
win.flashFrame(true) win.flashFrame(true)
``` ```
Don't forget to call the `flashFrame` method with `false` to turn off the flash. In > NOTE: Don't forget to call `win.flashFrame(false)` to turn off the flash.
the above example, it is called when the window comes into focus, but you might In the above example, it is called when the window comes into focus,
use a timeout or some other event to disable it. but you might use a timeout or some other event to disable it.
[msdn-flash-frame]: https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-flashwindow#remarks
[setthumbarbuttons]: ../api/browser-window.md#winsetthumbarbuttonsbuttons-windows [setthumbarbuttons]: ../api/browser-window.md#winsetthumbarbuttonsbuttons-windows
[setusertaskstasks]: ../api/app.md#appsetusertaskstasks-windows [setusertaskstasks]: ../api/app.md#appsetusertaskstasks-windows