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