Merge pull request #2400 from atom/thumbar_button

Implement API for supporting thumbnail toolbars

docs/api/browser-window.md

@@ -643,6 +643,38 @@ Sets a 16px overlay onto the current taskbar icon, usually used to convey some s
 
 __Note:__ This API is only available on Windows (Windows 7 and above)
 
+
+### BrowserWindow.setThumbarButtons(buttons)
+
+* `buttons` Array of `button` objects
+  * `button` Object
+    * `icon` [NativeImage](native-image.md) - The icon showing in thumbnail
+      toolbar.
+    * `tooltip` String - (Option) - The text of the button's tooltip.
+    * `flags` Array of Strings - (Option) Control specific states and behaviors
+      of the button. By default, it uses `enabled`.
+      *  `enabled` - The button is active and available to the user.
+      *  `disabled` - The button is disabled. It is present, but has a visual
+         state that indicates that it will not respond to user action.
+      *  `dismissonclick` - When the button is clicked, the taskbar button's
+         flyout closes immediately.
+      *  `nobackground` - Do not draw a button border, use only the image.
+      *  `hidden` - The button is not shown to the user.
+      *  `noninteractive` - The button is enabled but not interactive; no
+         pressed button state is drawn. This value is intended for instances
+         where the button is used in a notification.
+    * `click` - Function
+
+Add a thumbnail toolbar with a specified set of buttons to the thumbnail image
+of a window in a taskbar button layout. Returns a `Boolean` object indicates
+whether the thumbnail has been added successfully.
+
+__Note:__ This API is only available on Windows (Windows 7 and above).
+The number of buttons in thumbnail toolbar should be no greater than 7 due to
+the limited room. Once you setup the thumbnail toolbar, the toolbar cannot be
+removed due to the platform's limitation. But you can call the API with an empty
+array to clean the buttons.
+
 ### BrowserWindow.showDefinitionForSelection()
 
 Shows pop-up dictionary that searches the selected word on the page.

docs/tutorial/desktop-environment-integration.md

@@ -134,6 +134,59 @@ 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 particualr
+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:
+
+```
+var BrowserWindow = require('browser-window');
+var path = require('path');
+var win = new BrowserWindow({
+  width: 800,
+  height: 600
+});
+win.setThumbarButtons([
+  {
+    tooltip: "button1",
+    icon: path.join(__dirname, 'button1.png'),
+    click: function() { console.log("button2 clicked"); }
+  },
+  {
+    tooltip: "button2",
+    icon: path.join(__dirname, 'button2.png'),
+    flags:['enabled', 'dismissonclick'],
+    click: function() { console.log("button2 clicked."); }
+  }
+]);
+```
+
+To clean thumbnail toolbar buttons, just call `BrowserWindow.setThumbarButtons`
+with an empty array:
+
+```javascript
+win.setThumbarButtons([]);
+```
+
 ## Unity launcher shortcuts (Linux)
 
 In Unity, you can add custom entries to its launcher via modifying `.desktop`
@@ -199,3 +252,4 @@ window.setDocumentEdited(true);
 [setdocumentedited]: ../api/browser-window.md#browserwindowsetdocumenteditededited
 [app-registration]: http://msdn.microsoft.com/en-us/library/windows/desktop/ee872121(v=vs.85).aspx
 [unity-launcher]: https://help.ubuntu.com/community/UnityLaunchersAndDesktopFiles#Adding_shortcuts_to_a_launcher
+[setthumbarbuttons]: ../api/browser-window.md#browserwindowsetthumbarbuttonsbuttons