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