1// Copyright 2014 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5#ifndef CHROME_BROWSER_JUMPLIST_UPDATER_WIN_H_
6#define CHROME_BROWSER_JUMPLIST_UPDATER_WIN_H_
7
8#include <windows.h>
9#include <shobjidl.h>
10
11#include <string>
12#include <vector>
13
14#include "base/command_line.h"
15#include "base/memory/ref_counted.h"
16#include "base/win/scoped_comptr.h"
17#include "third_party/skia/include/core/SkBitmap.h"
18
19// Represents a class used for creating an IShellLink object.
20// Even though an IShellLink also needs the absolute path to an application to
21// be executed, this class does not have any variables for it because current
22// users always use "chrome.exe" as the application.
23class ShellLinkItem : public base::RefCountedThreadSafe<ShellLinkItem> {
24 public:
25  ShellLinkItem();
26
27  const std::wstring& title() const { return title_; }
28  const std::wstring& icon_path() const { return icon_path_; }
29  int icon_index() const { return icon_index_; }
30  const SkBitmap& icon_data() const { return icon_data_; }
31
32  std::wstring GetArguments() const;
33  base::CommandLine* GetCommandLine();
34
35  void set_title(const std::wstring& title) {
36    title_ = title;
37  }
38
39  void set_icon(const std::wstring& path, int index) {
40    icon_path_ = path;
41    icon_index_ = index;
42  }
43
44  void set_icon_data(const SkBitmap& data) {
45    icon_data_ = data;
46  }
47
48 private:
49  friend class base::RefCountedThreadSafe<ShellLinkItem>;
50  ~ShellLinkItem();
51
52  // Used for storing and appending command-line arguments.
53  base::CommandLine command_line_;
54
55  // The string to be displayed in a JumpList.
56  std::wstring title_;
57
58  // The absolute path to an icon to be displayed in a JumpList.
59  std::wstring icon_path_;
60
61  // The icon index in the icon file. If an icon file consists of two or more
62  // icons, set this value to identify the icon. If an icon file consists of
63  // one icon, this value is 0.
64  int icon_index_;
65
66  // Icon bitmap. Used by the browser JumpList.
67  // Note that an icon path must be supplied to IShellLink, so users of this
68  // class must save icon data to disk.
69  SkBitmap icon_data_;
70
71  DISALLOW_COPY_AND_ASSIGN(ShellLinkItem);
72};
73
74typedef std::vector<scoped_refptr<ShellLinkItem> > ShellLinkItemList;
75
76
77// A utility class that hides the boilerplate for updating Windows JumpLists.
78// Note that JumpLists are available in Windows 7 and later only.
79//
80// Example of usage:
81//
82//    JumpListUpdater updater(app_id);
83//    if (updater.BeginUpdate()) {
84//      updater.AddTasks(...);
85//      updater.AddCustomCategory(...);
86//      updater.CommitUpdate();
87//    }
88//
89// Note:
90// - Each JumpListUpdater instance is expected to be used once only.
91// - The JumpList must be updated in its entirety, i.e. even if a category has
92//   not changed, all its items must be added in each update.
93class JumpListUpdater {
94 public:
95  explicit JumpListUpdater(const std::wstring& app_user_model_id);
96  ~JumpListUpdater();
97
98  // Returns true if JumpLists are enabled on this OS.
99  static bool IsEnabled();
100
101  // Returns the current user setting for the maximum number of items to display
102  // in JumpLists. The setting is retrieved in BeginUpdate().
103  size_t user_max_items() const { return user_max_items_; }
104
105  // Starts a transaction that updates the JumpList of this application.
106  // This must be called prior to updating the JumpList. If this function
107  // returns false, this instance should not be used.
108  bool BeginUpdate();
109
110  // Commits the update.
111  bool CommitUpdate();
112
113  // Updates the predefined "Tasks" category of the JumpList.
114  bool AddTasks(const ShellLinkItemList& link_items);
115
116  // Updates an unregistered category of the JumpList.
117  // This function cannot update registered categories (such as "Tasks")
118  // because special steps are required for updating them.
119  // |max_items| specifies the maximum number of items from |link_items| to add
120  // to the JumpList.
121  bool AddCustomCategory(const std::wstring& category_name,
122                         const ShellLinkItemList& link_items,
123                         size_t max_items);
124
125 private:
126  // The app ID.
127  std::wstring app_user_model_id_;
128
129  // Windows API interface used to modify JumpLists.
130  base::win::ScopedComPtr<ICustomDestinationList> destination_list_;
131
132  // The current user setting for "Number of recent items to display in Jump
133  // Lists" option in the "Taskbar and Start Menu Properties".
134  size_t user_max_items_;
135
136  DISALLOW_COPY_AND_ASSIGN(JumpListUpdater);
137};
138
139#endif  // CHROME_BROWSER_JUMPLIST_UPDATER_WIN_H_
140