From 3623cf97298249b16fbad7fe1871b89374696df4 Mon Sep 17 00:00:00 2001 From: Felix Rieseberg Date: Mon, 19 Feb 2018 17:10:25 -0600 Subject: [PATCH] :memo: Windows Taskbar documentation --- docs/tutorial/windows-taskbar.md | 185 +++++++++++++++++++++++++++++++ 1 file changed, 185 insertions(+) create mode 100644 docs/tutorial/windows-taskbar.md diff --git a/docs/tutorial/windows-taskbar.md b/docs/tutorial/windows-taskbar.md new file mode 100644 index 000000000000..1e539830eb4e --- /dev/null +++ b/docs/tutorial/windows-taskbar.md @@ -0,0 +1,185 @@ +# Windows Taskbar + +Electron has APIs to configure the app's icon in the Windows taskbar. Supported +are the [creation of a `JumpList`](#jumplist), +[custom thumbnails and toolbars](#thumbnail-toolbars), +[icon overlays](#icon-overlays-in-taskbar-windows), and the so-called +["Flash Frame" effect](#flash-frame), but +Electron also uses the app's dock icon to implement cross-platform features +like [recent documents][recent-documents] and +[application progress][progress-bar]. + +## JumpList + +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 +`JumpList`. You specify custom actions in the `Tasks` category of JumpList, +as quoted from MSDN: + +> 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 +> that the application does not need to be running for them to work. They +> should also be the statistically most common actions that a normal user would +> perform in an application, such as compose an email message or open the +> calendar in a mail program, create a new document in a word processor, launch +> an application in a certain mode, or launch one of its subcommands. An +> application should not clutter the menu with advanced features that standard +> users won't need or one-time actions such as registration. Do not use tasks +> for promotional items such as upgrades or special offers. +> +> It is strongly recommended that the task list be static. It should remain the +> same regardless of the state or status of the application. While it is +> possible to vary the list dynamically, you should consider that this could +> confuse the user who does not expect that portion of the destination list to +> change. + +__Tasks of Internet Explorer:__ + +![IE](http://i.msdn.microsoft.com/dynimg/IC420539.png) + +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 +executed with specified arguments. + +To set user tasks for your application, you can use +[app.setUserTasks][setusertaskstasks] API: + +```javascript +const { app } = require('electron') +app.setUserTasks([ + { + program: process.execPath, + arguments: '--new-window', + iconPath: process.execPath, + iconIndex: 0, + title: 'New Window', + description: 'Create a new window' + } +]) +``` + +To clean your tasks list, just call `app.setUserTasks` with an empty array: + +```javascript +const { app } = require('electron') +app.setUserTasks([]) +``` + +The user tasks will still show even after your application closes, so the icon +and program path specified for a task should exist until your application is +uninstalled. + + +## Thumbnail Toolbars + +On Windows you can add a thumbnail toolbar with specified buttons in a taskbar +layout of an application window. It provides users a way to access to a +particular window's command without restoring or activating the window. + +From MSDN, it's illustrated: + +> This toolbar is simply the familiar standard toolbar common control. It has a +> maximum of seven buttons. Each button's ID, image, tooltip, and state are defined +> in a structure, which is then passed to the taskbar. The application can show, +> enable, disable, or hide buttons from the thumbnail toolbar as required by its +> current state. +> +> For example, Windows Media Player might offer standard media transport controls +> such as play, pause, mute, and stop. + +__Thumbnail toolbar of Windows Media Player:__ + +![player](https://i-msdn.sec.s-msft.com/dynimg/IC420540.png) + +You can use [BrowserWindow.setThumbarButtons][setthumbarbuttons] to set +thumbnail toolbar in your application: + +```javascript +const { BrowserWindow } = require('electron') +const path = require('path') + +const win = new BrowserWindow() + +win.setThumbarButtons([ + { + tooltip: 'button1', + icon: path.join(__dirname, 'button1.png'), + click () { console.log('button1 clicked') } + }, { + tooltip: 'button2', + icon: path.join(__dirname, 'button2.png'), + flags: ['enabled', 'dismissonclick'], + click () { console.log('button2 clicked.') } + } +]) +``` + +To clean thumbnail toolbar buttons, just call `BrowserWindow.setThumbarButtons` +with an empty array: + +```javascript +const { BrowserWindow } = require('electron') + +const win = new BrowserWindow() +win.setThumbarButtons([]) +``` + + +## Icon Overlays in Taskbar + +On Windows a taskbar button can use a small overlay to display application +status, as quoted from MSDN: + +> 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 +> that information to the user. For instance, the new mail status in Microsoft +> Outlook, currently shown in the notification area, can now be indicated +> through an overlay on the taskbar button. Again, you must decide during your +> development cycle which method is best for your application. Overlay icons are +> intended to supply important, long-standing status or notifications such as +> network status, messenger status, or new mail. The user should not be +> 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) + +To set the overlay icon for a window, you can use the +[BrowserWindow.setOverlayIcon][setoverlayicon] API: + +```javascript +const {BrowserWindow} = require('electron') +let win = new BrowserWindow() +win.setOverlayIcon('path/to/overlay.png', 'Description for overlay') +``` + + +## Flash Frame + +On Windows you can highlight the taskbar button to get the user's attention. +This is similar to bouncing the dock icon on macOS. +From the MSDN reference documentation: + +> Typically, a window is flashed to inform the user that the window requires +> attention but that it does not currently have the keyboard focus. + +To flash the BrowserWindow taskbar button, you can use the +[BrowserWindow.flashFrame][flashframe] API: + +```javascript +const {BrowserWindow} = require('electron') +let win = new BrowserWindow() +win.once('focus', () => win.flashFrame(false)) +win.flashFrame(true) +``` + +Don't forget to call the `flashFrame` method with `false` to turn off the flash. In +the above example, it is called when the window comes into focus, but you might +use a timeout or some other event to disable it. + +[setthumbarbuttons]: ../api/browser-window.md#winsetthumbarbuttonsbuttons-windows +[setusertaskstasks]: ../api/app.md#appsetusertaskstasks-windows +[setoverlayicon]: ../api/browser-window.md#winsetoverlayiconoverlay-description-windows +[flashframe]: ../api/browser-window.md#winflashframeflag +[recent-documents]: ./recent-documents.md +[progress-bar]: ./progress-bar.md