chrome/browser/jumplist_updater_win.h

   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.
  23 class 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
  74 typedef 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.
  93 class 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_