Merge pull request #2400 from atom/thumbar_button

Implement API for supporting thumbnail toolbars

atom/browser/api/atom_api_window.cc

@@ -20,6 +20,24 @@
 
 #include "atom/common/node_includes.h"
 
+namespace mate {
+
+template<>
+struct Converter<atom::NativeWindow::ThumbarButton> {
+  static bool FromV8(v8::Isolate* isolate, v8::Handle<v8::Value> val,
+                     atom::NativeWindow::ThumbarButton* out) {
+    mate::Dictionary dict;
+    if (!ConvertFromV8(isolate, val, &dict))
+      return false;
+    dict.Get("click", &(out->clicked_callback));
+    dict.Get("tooltip", &(out->tooltip));
+    dict.Get("flags", &out->flags);
+    return dict.Get("icon", &(out->icon));
+  }
+};
+
+}  // namespace mate
+
 namespace atom {
 
 namespace api {
@@ -413,6 +431,11 @@ void Window::SetOverlayIcon(const gfx::Image& overlay,
   window_->SetOverlayIcon(overlay, description);
 }
 
+void Window::SetThumbarButtons(
+    const std::vector<NativeWindow::ThumbarButton>& buttons) {
+  window_->SetThumbarButtons(buttons);
+}
+
 void Window::SetMenu(v8::Isolate* isolate, v8::Local<v8::Value> value) {
   mate::Handle<Menu> menu;
   if (value->IsObject() &&
@@ -538,6 +561,7 @@ void Window::BuildPrototype(v8::Isolate* isolate,
       .SetMethod("capturePage", &Window::CapturePage)
       .SetMethod("setProgressBar", &Window::SetProgressBar)
       .SetMethod("setOverlayIcon", &Window::SetOverlayIcon)
+      .SetMethod("setThumbarButtons", &Window::SetThumbarButtons)
       .SetMethod("setMenu", &Window::SetMenu)
       .SetMethod("setAutoHideMenuBar", &Window::SetAutoHideMenuBar)
       .SetMethod("isMenuBarAutoHide", &Window::IsMenuBarAutoHide)

atom/browser/api/atom_api_window.h

@@ -11,6 +11,7 @@
 #include "base/memory/scoped_ptr.h"
 #include "ui/gfx/image/image.h"
 #include "atom/browser/api/trackable_object.h"
+#include "atom/browser/native_window.h"
 #include "atom/browser/native_window_observer.h"
 #include "native_mate/handle.h"
 
@@ -129,6 +130,8 @@ class Window : public mate::TrackableObject<Window>,
   void SetProgressBar(double progress);
   void SetOverlayIcon(const gfx::Image& overlay,
                       const std::string& description);
+  void SetThumbarButtons(
+      const std::vector<NativeWindow::ThumbarButton>& buttons);
   void SetMenu(v8::Isolate* isolate, v8::Local<v8::Value> menu);
   void SetAutoHideMenuBar(bool auto_hide);
   bool IsMenuBarAutoHide();

atom/browser/native_window.cc

@@ -277,6 +277,11 @@ bool NativeWindow::HasModalDialog() {
   return has_dialog_attached_;
 }
 
+bool NativeWindow::SetThumbarButtons(
+    const std::vector<ThumbarButton>& buttons) {
+  return false;
+}
+
 void NativeWindow::FocusOnWebView() {
   web_contents()->GetRenderViewHost()->Focus();
 }

atom/browser/native_window.h

@@ -59,7 +59,15 @@ struct DraggableRegion;
 class NativeWindow : public content::WebContentsObserver,
                      public brightray::InspectableWebContentsViewDelegate {
  public:
-  typedef base::Callback<void(const SkBitmap& bitmap)> CapturePageCallback;
+  using CapturePageCallback = base::Callback<void(const SkBitmap& bitmap)>;
+  using ThumbarButtonClickedCallback = base::Closure;
+
+  struct ThumbarButton {
+    std::string tooltip;
+    gfx::Image icon;
+    std::vector<std::string> flags;
+    ThumbarButtonClickedCallback clicked_callback;
+  };
 
   class DialogScope {
    public:
@@ -144,6 +152,8 @@ class NativeWindow : public content::WebContentsObserver,
                               const std::string& description) = 0;
   virtual void SetVisibleOnAllWorkspaces(bool visible) = 0;
   virtual bool IsVisibleOnAllWorkspaces() = 0;
+  virtual bool SetThumbarButtons(
+      const std::vector<ThumbarButton>& buttons);
 
   virtual bool IsClosed() const { return is_closed_; }
 

atom/browser/native_window_views.cc

@@ -45,11 +45,13 @@
 #include "ui/views/window/native_frame_view.h"
 #elif defined(OS_WIN)
 #include "atom/browser/ui/views/win_frame_view.h"
+#include "atom/browser/ui/win/atom_desktop_window_tree_host_win.h"
 #include "base/win/scoped_comptr.h"
 #include "base/win/windows_version.h"
 #include "ui/base/win/shell.h"
 #include "ui/gfx/icon_util.h"
 #include "ui/gfx/win/dpi.h"
+#include "ui/views/widget/desktop_aura/desktop_native_widget_aura.h"
 #include "ui/views/win/hwnd_util.h"
 #endif
 
@@ -215,6 +217,14 @@ NativeWindowViews::NativeWindowViews(
   if (transparent())
     params.opacity = views::Widget::InitParams::TRANSLUCENT_WINDOW;
 
+#if defined(OS_WIN)
+  params.native_widget =
+      new views::DesktopNativeWidgetAura(window_.get());
+  atom_desktop_window_tree_host_win_ = new AtomDesktopWindowTreeHostWin(
+      window_.get(),
+      static_cast<views::DesktopNativeWidgetAura*>(params.native_widget));
+  params.desktop_window_tree_host = atom_desktop_window_tree_host_win_;
+#endif
 #if defined(USE_X11)
   std::string name = Browser::Get()->GetName();
   // Set WM_WINDOW_ROLE.
@@ -707,6 +717,18 @@ bool NativeWindowViews::IsVisibleOnAllWorkspaces() {
   return false;
 }
 
+bool NativeWindowViews::SetThumbarButtons(
+    const std::vector<NativeWindow::ThumbarButton>& buttons) {
+#if defined(OS_WIN)
+  if (atom_desktop_window_tree_host_win_) {
+    return atom_desktop_window_tree_host_win_->SetThumbarButtons(
+        views::HWNDForNativeWindow(window_->GetNativeWindow()),
+        buttons);
+  }
+#endif
+  return false;
+}
+
 gfx::AcceleratedWidget NativeWindowViews::GetAcceleratedWidget() {
   return GetNativeWindow()->GetHost()->GetAcceleratedWidget();
 }

atom/browser/native_window_views.h

@@ -23,6 +23,9 @@ namespace atom {
 class GlobalMenuBarX11;
 class MenuBar;
 class WindowStateWatcher;
+#if defined(OS_WIN)
+class AtomDesktopWindowTreeHostWin;
+#endif
 
 class NativeWindowViews : public NativeWindow,
                           public views::WidgetDelegateView,
@@ -79,6 +82,8 @@ class NativeWindowViews : public NativeWindow,
   bool IsMenuBarVisible() override;
   void SetVisibleOnAllWorkspaces(bool visible) override;
   bool IsVisibleOnAllWorkspaces() override;
+  bool SetThumbarButtons(
+      const std::vector<NativeWindow::ThumbarButton>& buttons) override;
 
   gfx::AcceleratedWidget GetAcceleratedWidget();
 
@@ -154,6 +159,8 @@ class NativeWindowViews : public NativeWindow,
   // Handles window state events.
   scoped_ptr<WindowStateWatcher> window_state_watcher_;
 #elif defined(OS_WIN)
+  // Weak ref.
+  AtomDesktopWindowTreeHostWin* atom_desktop_window_tree_host_win_;
   // Records window was whether restored from minimized state or maximized
   // state.
   bool is_minimized_;

atom/browser/ui/win/atom_desktop_window_tree_host_win.cc

@@ -0,0 +1,51 @@
+// Copyright (c) 2015 GitHub, Inc.
+// Use of this source code is governed by the MIT license that can be
+// found in the LICENSE file.
+
+#include "atom/browser/ui/win/atom_desktop_window_tree_host_win.h"
+
+#include <shobjidl.h>
+
+#include "atom/browser/native_window.h"
+#include "atom/browser/ui/win/thumbar_host.h"
+
+namespace atom {
+
+AtomDesktopWindowTreeHostWin::AtomDesktopWindowTreeHostWin(
+    views::internal::NativeWidgetDelegate* native_widget_delegate,
+    views::DesktopNativeWidgetAura* desktop_native_widget_aura)
+        : views::DesktopWindowTreeHostWin(native_widget_delegate,
+                                          desktop_native_widget_aura) {
+}
+
+AtomDesktopWindowTreeHostWin::~AtomDesktopWindowTreeHostWin() {
+}
+
+bool AtomDesktopWindowTreeHostWin::SetThumbarButtons(
+    HWND window,
+    const std::vector<NativeWindow::ThumbarButton>& buttons) {
+  if (!thumbar_host_.get()) {
+    thumbar_host_.reset(new ThumbarHost(window));
+  }
+  return thumbar_host_->SetThumbarButtons(buttons);
+}
+
+bool AtomDesktopWindowTreeHostWin::PreHandleMSG(UINT message,
+                                                WPARAM w_param,
+                                                LPARAM l_param,
+                                                LRESULT* result) {
+  switch (message) {
+    case WM_COMMAND: {
+       // Handle thumbar button click message.
+       int id = LOWORD(w_param);
+       int thbn_message = HIWORD(w_param);
+       if (thbn_message == THBN_CLICKED && thumbar_host_ &&
+           thumbar_host_->HandleThumbarButtonEvent(id))
+         return true;
+    }
+  }
+
+  return false;
+}
+
+}  // namespace atom

atom/browser/ui/win/atom_desktop_window_tree_host_win.h

@@ -0,0 +1,42 @@
+// Copyright (c) 2015 GitHub, Inc.
+// Use of this source code is governed by the MIT license that can be
+// found in the LICENSE file.
+
+#ifndef ATOM_BROWSER_UI_WIN_ATOM_DESKTOP_WINDOW_TREE_HOST_WIN_H_
+#define ATOM_BROWSER_UI_WIN_ATOM_DESKTOP_WINDOW_TREE_HOST_WIN_H_
+
+#include <windows.h>
+
+#include <vector>
+
+#include "atom/browser/native_window.h"
+#include "atom/browser/ui/win/thumbar_host.h"
+#include "base/memory/scoped_ptr.h"
+#include "ui/views/widget/desktop_aura/desktop_window_tree_host_win.h"
+
+namespace atom {
+
+class AtomDesktopWindowTreeHostWin : public views::DesktopWindowTreeHostWin {
+ public:
+  AtomDesktopWindowTreeHostWin(
+      views::internal::NativeWidgetDelegate* native_widget_delegate,
+      views::DesktopNativeWidgetAura* desktop_native_widget_aura);
+  ~AtomDesktopWindowTreeHostWin();
+
+  bool SetThumbarButtons(
+      HWND window,
+      const std::vector<NativeWindow::ThumbarButton>& buttons);
+
+ protected:
+  bool PreHandleMSG(UINT message,
+                    WPARAM w_param,
+                    LPARAM l_param,
+                    LRESULT* result) override;
+
+ private:
+  scoped_ptr<ThumbarHost> thumbar_host_;
+};
+
+}  // namespace atom
+
+#endif  // ATOM_BROWSER_UI_WIN_ATOM_DESKTOP_WINDOW_TREE_HOST_WIN_H_

atom/browser/ui/win/thumbar_host.cc

@@ -0,0 +1,141 @@
+// Copyright (c) 2015 GitHub, Inc.
+// Use of this source code is governed by the MIT license that can be
+// found in the LICENSE file.
+
+#include "atom/browser/ui/win/thumbar_host.h"
+
+#include <shobjidl.h>
+
+#include <string>
+
+#include "base/win/scoped_comptr.h"
+#include "base/win/win_util.h"
+#include "base/win/wrapped_window_proc.h"
+#include "base/strings/utf_string_conversions.h"
+#include "third_party/skia/include/core/SkBitmap.h"
+#include "ui/gfx/icon_util.h"
+#include "ui/gfx/win/hwnd_util.h"
+
+namespace atom {
+
+namespace {
+
+// From MSDN: https://msdn.microsoft.com/en-us/library/windows/desktop/
+// dd378460(v=vs.85).aspx#thumbbars
+// The thumbnail toolbar has a maximum of seven buttons due to the limited room.
+const int kMaxButtonsCount = 7;
+
+// The base id of Thumbar button.
+const int kButtonIdBase = 40001;
+
+bool GetThumbarButtonFlags(const std::vector<std::string>& flags,
+                           THUMBBUTTONFLAGS* out) {
+  if (flags.empty()) {
+    *out = THBF_ENABLED;
+    return true;
+  }
+  THUMBBUTTONFLAGS result = static_cast<THUMBBUTTONFLAGS>(0);
+  for (const auto& flag : flags) {
+    if (flag == "enabled") {
+      result |= THBF_ENABLED;
+    } else if (flag == "disabled") {
+      result |= THBF_DISABLED;
+    } else if (flag == "dismissonclick") {
+      result |= THBF_DISMISSONCLICK;
+    } else if (flag == "nobackground") {
+      result |= THBF_NOBACKGROUND;
+    } else if (flag == "hidden") {
+      result |= THBF_HIDDEN;
+    } else if (flag == "noninteractive") {
+      result |= THBF_NONINTERACTIVE;
+    } else {
+      return false;
+    }
+  }
+  *out = result;
+  return true;
+}
+
+}  // namespace
+
+ThumbarHost::ThumbarHost(HWND window) : is_initialized_(false),
+                                        window_(window) {
+}
+
+ThumbarHost::~ThumbarHost() {
+}
+
+bool ThumbarHost::SetThumbarButtons(
+    const std::vector<atom::NativeWindow::ThumbarButton>& buttons) {
+  if (buttons.size() > kMaxButtonsCount)
+    return false;
+
+  base::win::ScopedComPtr<ITaskbarList3> taskbar;
+  if (FAILED(taskbar.CreateInstance(CLSID_TaskbarList,
+                                    nullptr,
+                                    CLSCTX_INPROC_SERVER)) ||
+      FAILED(taskbar->HrInit())) {
+    return false;
+  }
+
+  THUMBBUTTON thumb_buttons[kMaxButtonsCount] = {};
+  thumbar_button_clicked_callback_map_.clear();
+
+  // Once a toolbar with a set of buttons is added to thumbnail, there is no way
+  // to remove it without re-creating the window.
+  // To achieve to re-set thumbar buttons,  we initialize the buttons with
+  // HIDDEN state and only updated the caller's specified buttons.
+  //
+  // Initialize all thumb buttons with HIDDEN state.
+  for (int i = 0; i < kMaxButtonsCount; ++i) {
+    thumb_buttons[i].iId = kButtonIdBase + i;
+    thumb_buttons[i].dwMask = THB_FLAGS;  // dwFlags is valid.
+    thumb_buttons[i].dwFlags = THBF_HIDDEN;
+  }
+
+  // Update the callers' specified buttons.
+  for (size_t i = 0; i < buttons.size(); ++i) {
+    if (!GetThumbarButtonFlags(buttons[i].flags, &thumb_buttons[i].dwFlags))
+      return false;
+    thumb_buttons[i].dwMask = THB_ICON | THB_FLAGS;
+    thumb_buttons[i].hIcon = IconUtil::CreateHICONFromSkBitmap(
+        buttons[i].icon.AsBitmap());
+    if (!buttons[i].tooltip.empty()) {
+      thumb_buttons[i].dwMask |= THB_TOOLTIP;
+      wcscpy_s(thumb_buttons[i].szTip,
+               base::UTF8ToUTF16(buttons[i].tooltip).c_str());
+    }
+
+    thumbar_button_clicked_callback_map_[thumb_buttons[i].iId] =
+        buttons[i].clicked_callback;
+  }
+
+  bool is_success = false;
+  if (!is_initialized_) {
+    is_initialized_ = true;
+    is_success = taskbar->ThumbBarAddButtons(
+        window_, buttons.size(), thumb_buttons) == S_OK;
+  } else {
+    is_success = taskbar->ThumbBarUpdateButtons(
+        window_, kMaxButtonsCount, thumb_buttons) == S_OK;
+  }
+
+  // Release thumb_buttons' icons, the taskbar makes its own copy.
+  for (size_t i = 0; i < buttons.size(); ++i) {
+    ::DestroyIcon(thumb_buttons[i].hIcon);
+  }
+  return is_success;
+}
+
+bool ThumbarHost::HandleThumbarButtonEvent(int button_id) {
+  if (thumbar_button_clicked_callback_map_.find(button_id) !=
+      thumbar_button_clicked_callback_map_.end()) {
+    auto callback = thumbar_button_clicked_callback_map_[button_id];
+    if (!callback.is_null())
+      callback.Run();
+    return true;
+  }
+  return false;
+}
+
+}  // namespace atom

atom/browser/ui/win/thumbar_host.h

@@ -0,0 +1,40 @@
+// Copyright (c) 2015 GitHub, Inc.
+// Use of this source code is governed by the MIT license that can be
+// found in the LICENSE file.
+
+#ifndef ATOM_BROWSER_UI_WIN_THUMBAR_HOST_H_
+#define ATOM_BROWSER_UI_WIN_THUMBAR_HOST_H_
+
+#include <windows.h>
+
+#include <map>
+#include <vector>
+
+#include "atom/browser/native_window.h"
+
+namespace atom {
+
+class ThumbarHost {
+ public:
+  explicit ThumbarHost(HWND window);
+  ~ThumbarHost();
+
+  bool SetThumbarButtons(
+      const std::vector<NativeWindow::ThumbarButton>& buttons);
+  bool HandleThumbarButtonEvent(int button_id);
+
+ private:
+  using ThumbarButtonClickedCallbackMap = std::map<
+      int, NativeWindow::ThumbarButtonClickedCallback>;
+  ThumbarButtonClickedCallbackMap thumbar_button_clicked_callback_map_;
+
+  bool is_initialized_;
+
+  HWND window_;
+
+  DISALLOW_COPY_AND_ASSIGN(ThumbarHost);
+};
+
+}  // namespace atom
+
+#endif  // ATOM_BROWSER_UI_WIN_THUMBAR_HOST_H_

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

filenames.gypi

@@ -202,10 +202,14 @@
       'atom/browser/ui/views/submenu_button.h',
       'atom/browser/ui/views/win_frame_view.cc',
       'atom/browser/ui/views/win_frame_view.h',
+      "atom/browser/ui/win/atom_desktop_window_tree_host_win.cc",
+      "atom/browser/ui/win/atom_desktop_window_tree_host_win.h",
       'atom/browser/ui/win/notify_icon_host.cc',
       'atom/browser/ui/win/notify_icon_host.h',
       'atom/browser/ui/win/notify_icon.cc',
       'atom/browser/ui/win/notify_icon.h',
+      'atom/browser/ui/win/thumbar_host.cc',
+      'atom/browser/ui/win/thumbar_host.h',
       'atom/browser/ui/x/window_state_watcher.cc',
       'atom/browser/ui/x/window_state_watcher.h',
       'atom/browser/ui/x/x_window_utils.cc',