Home | History | Annotate | Download | only in browser 
      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_
    140