src/ui/base/resource/resource_bundle.h

   1 // Copyright (c) 2012 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 UI_BASE_RESOURCE_RESOURCE_BUNDLE_H_
   6 #define UI_BASE_RESOURCE_RESOURCE_BUNDLE_H_
   7
   8 #include "build/build_config.h"
   9
  10 #include <map>
  11 #include <string>
  12
  13 #include "base/basictypes.h"
  14 #include "base/files/file.h"
  15 #include "base/files/file_path.h"
  16 #include "base/gtest_prod_util.h"
  17 #include "base/memory/scoped_ptr.h"
  18 #include "base/memory/scoped_vector.h"
  19 #include "base/strings/string16.h"
  20 #include "base/strings/string_piece.h"
  21 #include "ui/base/layout.h"
  22 #include "ui/base/ui_base_export.h"
  23 #include "ui/gfx/font_list.h"
  24 #include "ui/gfx/image/image.h"
  25 #include "ui/gfx/native_widget_types.h"
  26
  27 class SkBitmap;
  28
  29 namespace base {
  30 class Lock;
  31 class RefCountedStaticMemory;
  32 }
  33
  34 namespace ui {
  35
  36 class DataPack;
  37 class ResourceHandle;
  38
  39 // ResourceBundle is a central facility to load images and other resources,
  40 // such as theme graphics. Every resource is loaded only once.
  41 class UI_BASE_EXPORT ResourceBundle {
  42  public:
  43   // An enumeration of the various font styles used throughout Chrome.
  44   // The following holds true for the font sizes:
  45   // Small <= SmallBold <= Base <= Bold <= Medium <= MediumBold <= Large.
  46   enum FontStyle {
  47     // NOTE: depending upon the locale, using one of the *BoldFont below
  48     // may *not* actually result in a bold font.
  49     SmallFont,
  50     SmallBoldFont,
  51     BaseFont,
  52     BoldFont,
  53     MediumFont,
  54     MediumBoldFont,
  55     LargeFont,
  56     LargeBoldFont,
  57   };
  58
  59   enum ImageRTL {
  60     // Images are flipped in RTL locales.
  61     RTL_ENABLED,
  62     // Images are never flipped.
  63     RTL_DISABLED,
  64   };
  65
  66   // Delegate class that allows interception of pack file loading and resource
  67   // requests. The methods of this class may be called on multiple threads.
  68   class Delegate {
  69    public:
  70     // Called before a resource pack file is loaded. Return the full path for
  71     // the pack file to continue loading or an empty value to cancel loading.
  72     // |pack_path| will contain the complete default path for the pack file if
  73     // known or just the pack file name otherwise.
  74     virtual base::FilePath GetPathForResourcePack(
  75         const base::FilePath& pack_path,
  76         ScaleFactor scale_factor) = 0;
  77
  78     // Called before a locale pack file is loaded. Return the full path for
  79     // the pack file to continue loading or an empty value to cancel loading.
  80     // |pack_path| will contain the complete default path for the pack file if
  81     // known or just the pack file name otherwise.
  82     virtual base::FilePath GetPathForLocalePack(
  83         const base::FilePath& pack_path,
  84         const std::string& locale) = 0;
  85
  86     // Return an image resource or an empty value to attempt retrieval of the
  87     // default resource.
  88     virtual gfx::Image GetImageNamed(int resource_id) = 0;
  89
  90     // Return an image resource or an empty value to attempt retrieval of the
  91     // default resource.
  92     virtual gfx::Image GetNativeImageNamed(int resource_id, ImageRTL rtl) = 0;
  93
  94     // Return a static memory resource or NULL to attempt retrieval of the
  95     // default resource.
  96     virtual base::RefCountedStaticMemory* LoadDataResourceBytes(
  97         int resource_id,
  98         ScaleFactor scale_factor) = 0;
  99
 100     // Retrieve a raw data resource. Return true if a resource was provided or
 101     // false to attempt retrieval of the default resource.
 102     virtual bool GetRawDataResource(int resource_id,
 103                                     ScaleFactor scale_factor,
 104                                     base::StringPiece* value) = 0;
 105
 106     // Retrieve a localized string. Return true if a string was provided or
 107     // false to attempt retrieval of the default string.
 108     virtual bool GetLocalizedString(int message_id, base::string16* value) = 0;
 109
 110     // Returns a font or NULL to attempt retrieval of the default resource.
 111     virtual scoped_ptr<gfx::Font> GetFont(FontStyle style) = 0;
 112
 113    protected:
 114     virtual ~Delegate() {}
 115   };
 116
 117   // Initialize the ResourceBundle for this process. Does not take ownership of
 118   // the |delegate| value. Returns the language selected.
 119   // NOTE: Mac ignores this and always loads up resources for the language
 120   // defined by the Cocoa UI (i.e., NSBundle does the language work).
 121   //
 122   // TODO(sergeyu): This method also loads common resources (i.e. chrome.pak).
 123   // There is no way to specify which resource files are loaded, i.e. names of
 124   // the files are hardcoded in ResourceBundle. Fix it to allow to specify which
 125   // files are loaded (e.g. add a new method in Delegate).
 126   static std::string InitSharedInstanceWithLocale(
 127       const std::string& pref_locale, Delegate* delegate);
 128
 129   // Same as InitSharedInstanceWithLocale(), but loads only localized resources,
 130   // without default resource packs.
 131   static std::string InitSharedInstanceLocaleOnly(
 132       const std::string& pref_locale, Delegate* delegate);
 133
 134   // Initialize the ResourceBundle using given file. The second argument
 135   // controls whether or not ResourceBundle::LoadCommonResources is called.
 136   // This allows the use of this function in a sandbox without local file
 137   // access (as on Android).
 138   static void InitSharedInstanceWithPakFile(base::File file,
 139                                             bool should_load_common_resources);
 140
 141   // Initialize the ResourceBundle using given data pack path for testing.
 142   static void InitSharedInstanceWithPakPath(const base::FilePath& path);
 143
 144   // Delete the ResourceBundle for this process if it exists.
 145   static void CleanupSharedInstance();
 146
 147   // Returns true after the global resource loader instance has been created.
 148   static bool HasSharedInstance();
 149
 150   // Return the global resource loader instance.
 151   static ResourceBundle& GetSharedInstance();
 152
 153   // Check if the .pak for the given locale exists.
 154   bool LocaleDataPakExists(const std::string& locale);
 155
 156   // Registers additional data pack files with this ResourceBundle.  When
 157   // looking for a DataResource, we will search these files after searching the
 158   // main module. |path| should be the complete path to the pack file if known
 159   // or just the pack file name otherwise (the delegate may optionally override
 160   // this value). |scale_factor| is the scale of images in this resource pak
 161   // relative to the images in the 1x resource pak. This method is not thread
 162   // safe! You should call it immediately after calling InitSharedInstance.
 163   void AddDataPackFromPath(const base::FilePath& path,
 164                            ScaleFactor scale_factor);
 165
 166   // Same as above but using an already open file.
 167   void AddDataPackFromFile(base::File file, ScaleFactor scale_factor);
 168
 169   // Same as AddDataPackFromPath but does not log an error if the pack fails to
 170   // load.
 171   void AddOptionalDataPackFromPath(const base::FilePath& path,
 172                                    ScaleFactor scale_factor);
 173
 174   // Changes the locale for an already-initialized ResourceBundle, returning the
 175   // name of the newly-loaded locale.  Future calls to get strings will return
 176   // the strings for this new locale.  This has no effect on existing or future
 177   // image resources.  |locale_resources_data_| is protected by a lock for the
 178   // duration of the swap, as GetLocalizedString() may be concurrently invoked
 179   // on another thread.
 180   std::string ReloadLocaleResources(const std::string& pref_locale);
 181
 182   // Gets image with the specified resource_id from the current module data.
 183   // Returns a pointer to a shared instance of gfx::ImageSkia. This shared
 184   // instance is owned by the resource bundle and should not be freed.
 185   // TODO(pkotwicz): Make method return const gfx::ImageSkia*
 186   //
 187   // NOTE: GetNativeImageNamed is preferred for cross-platform gfx::Image use.
 188   gfx::ImageSkia* GetImageSkiaNamed(int resource_id);
 189
 190   // Gets an image resource from the current module data. This will load the
 191   // image in Skia format by default. The ResourceBundle owns this.
 192   gfx::Image& GetImageNamed(int resource_id);
 193
 194   // Similar to GetImageNamed, but rather than loading the image in Skia format,
 195   // it will load in the native platform type. This can avoid conversion from
 196   // one image type to another. ResourceBundle owns the result.
 197   //
 198   // Note that if the same resource has already been loaded in GetImageNamed(),
 199   // gfx::Image will perform a conversion, rather than using the native image
 200   // loading code of ResourceBundle.
 201   //
 202   // If |rtl| is RTL_ENABLED then the image is flipped in RTL locales.
 203   gfx::Image& GetNativeImageNamed(int resource_id, ImageRTL rtl);
 204
 205   // Same as GetNativeImageNamed() except that RTL is not enabled.
 206   gfx::Image& GetNativeImageNamed(int resource_id);
 207
 208   // Loads the raw bytes of a scale independent data resource.
 209   base::RefCountedStaticMemory* LoadDataResourceBytes(int resource_id) const;
 210
 211   // Loads the raw bytes of a data resource nearest the scale factor
 212   // |scale_factor| into |bytes|, without doing any processing or
 213   // interpretation of the resource. Use ResourceHandle::SCALE_FACTOR_NONE
 214   // for scale independent image resources (such as wallpaper).
 215   // Returns NULL if we fail to read the resource.
 216   base::RefCountedStaticMemory* LoadDataResourceBytesForScale(
 217       int resource_id,
 218       ScaleFactor scale_factor) const;
 219
 220   // Return the contents of a scale independent resource in a
 221   // StringPiece given the resource id
 222   base::StringPiece GetRawDataResource(int resource_id) const;
 223
 224   // Return the contents of a resource in a StringPiece given the resource id
 225   // nearest the scale factor |scale_factor|.
 226   // Use ResourceHandle::SCALE_FACTOR_NONE for scale independent image resources
 227   // (such as wallpaper).
 228   base::StringPiece GetRawDataResourceForScale(int resource_id,
 229                                                ScaleFactor scale_factor) const;
 230
 231   // Get a localized string given a message id.  Returns an empty
 232   // string if the message_id is not found.
 233   base::string16 GetLocalizedString(int message_id);
 234
 235   // Returns the font list for the specified style.
 236   const gfx::FontList& GetFontList(FontStyle style);
 237
 238   // Returns the font for the specified style.
 239   const gfx::Font& GetFont(FontStyle style);
 240
 241   // Resets and reloads the cached fonts.  This is useful when the fonts of the
 242   // system have changed, for example, when the locale has changed.
 243   void ReloadFonts();
 244
 245   // Overrides the path to the pak file from which the locale resources will be
 246   // loaded. Pass an empty path to undo.
 247   void OverrideLocalePakForTest(const base::FilePath& pak_path);
 248
 249   // Returns the full pathname of the locale file to load.  May return an empty
 250   // string if no locale data files are found and |test_file_exists| is true.
 251   // Used on Android to load the local file in the browser process and pass it
 252   // to the sandboxed renderer process.
 253   base::FilePath GetLocaleFilePath(const std::string& app_locale,
 254                                    bool test_file_exists);
 255
 256   // Returns the maximum scale factor currently loaded.
 257   // Returns SCALE_FACTOR_100P if no resource is loaded.
 258   ScaleFactor GetMaxScaleFactor() const;
 259
 260  private:
 261   FRIEND_TEST_ALL_PREFIXES(ResourceBundleTest, DelegateGetPathForLocalePack);
 262   FRIEND_TEST_ALL_PREFIXES(ResourceBundleTest, DelegateGetImageNamed);
 263   FRIEND_TEST_ALL_PREFIXES(ResourceBundleTest, DelegateGetNativeImageNamed);
 264
 265   friend class ResourceBundleImageTest;
 266   friend class ResourceBundleTest;
 267
 268   class ResourceBundleImageSource;
 269   friend class ResourceBundleImageSource;
 270
 271   // Ctor/dtor are private, since we're a singleton.
 272   explicit ResourceBundle(Delegate* delegate);
 273   ~ResourceBundle();
 274
 275   // Shared initialization.
 276   static void InitSharedInstance(Delegate* delegate);
 277
 278   // Free skia_images_.
 279   void FreeImages();
 280
 281   // Load the main resources.
 282   void LoadCommonResources();
 283
 284   // Implementation for AddDataPackFromPath and AddOptionalDataPackFromPath, if
 285   // the pack is not |optional| logs an error on failure to load.
 286   void AddDataPackFromPathInternal(const base::FilePath& path,
 287                                    ScaleFactor scale_factor,
 288                                    bool optional);
 289
 290   // Inserts |data_pack| to |data_pack_| and updates |max_scale_factor_|
 291   // accordingly.
 292   void AddDataPack(DataPack* data_pack);
 293
 294   // Try to load the locale specific strings from an external data module.
 295   // Returns the locale that is loaded.
 296   std::string LoadLocaleResources(const std::string& pref_locale);
 297
 298   // Load test resources in given paths. If either path is empty an empty
 299   // resource pack is loaded.
 300   void LoadTestResources(const base::FilePath& path,
 301                          const base::FilePath& locale_path);
 302
 303   // Unload the locale specific strings and prepares to load new ones. See
 304   // comments for ReloadLocaleResources().
 305   void UnloadLocaleResources();
 306
 307   // Initializes all the gfx::FontList members if they haven't yet been
 308   // initialized.
 309   void LoadFontsIfNecessary();
 310
 311   // Returns a FontList or NULL by calling Delegate::GetFont and converting
 312   // scoped_ptr<gfx::Font> to scoped_ptr<gfx::FontList>.
 313   scoped_ptr<gfx::FontList> GetFontListFromDelegate(FontStyle style);
 314
 315   // Fills the |bitmap| given the data file to look in and the |resource_id|.
 316   // Returns false if the resource does not exist.
 317   //
 318   // If the call succeeds, |fell_back_to_1x| indicates whether Chrome's custom
 319   // csCl PNG chunk is present (added by GRIT if it falls back to a 100% image).
 320   bool LoadBitmap(const ResourceHandle& data_handle,
 321                   int resource_id,
 322                   SkBitmap* bitmap,
 323                   bool* fell_back_to_1x) const;
 324
 325   // Fills the |bitmap| given the |resource_id| and |scale_factor|.
 326   // Returns false if the resource does not exist. This may fall back to
 327   // the data pack with SCALE_FACTOR_NONE, and when this happens,
 328   // |scale_factor| will be set to SCALE_FACTOR_100P.
 329   bool LoadBitmap(int resource_id,
 330                   ScaleFactor* scale_factor,
 331                   SkBitmap* bitmap,
 332                   bool* fell_back_to_1x) const;
 333
 334   // Returns true if missing scaled resources should be visually indicated when
 335   // drawing the fallback (e.g., by tinting the image).
 336   static bool ShouldHighlightMissingScaledResources();
 337
 338   // Returns true if the data in |buf| is a PNG that has the special marker
 339   // added by GRIT that indicates that the image is actually 1x data.
 340   static bool PNGContainsFallbackMarker(const unsigned char* buf, size_t size);
 341
 342   // A wrapper for PNGCodec::Decode that returns information about custom
 343   // chunks. For security reasons we can't alter PNGCodec to return this
 344   // information. Our PNG files are preprocessed by GRIT, and any special chunks
 345   // should occur immediately after the IHDR chunk.
 346   static bool DecodePNG(const unsigned char* buf,
 347                         size_t size,
 348                         SkBitmap* bitmap,
 349                         bool* fell_back_to_1x);
 350
 351   // Returns an empty image for when a resource cannot be loaded. This is a
 352   // bright red bitmap.
 353   gfx::Image& GetEmptyImage();
 354
 355   const base::FilePath& GetOverriddenPakPath();
 356
 357   // This pointer is guaranteed to outlive the ResourceBundle instance and may
 358   // be NULL.
 359   Delegate* delegate_;
 360
 361   // Protects |images_| and font-related members.
 362   scoped_ptr<base::Lock> images_and_fonts_lock_;
 363
 364   // Protects |locale_resources_data_|.
 365   scoped_ptr<base::Lock> locale_resources_data_lock_;
 366
 367   // Handles for data sources.
 368   scoped_ptr<ResourceHandle> locale_resources_data_;
 369   ScopedVector<ResourceHandle> data_packs_;
 370
 371   // The maximum scale factor currently loaded.
 372   ScaleFactor max_scale_factor_;
 373
 374   // Cached images. The ResourceBundle caches all retrieved images and keeps
 375   // ownership of the pointers.
 376   typedef std::map<int, gfx::Image> ImageMap;
 377   ImageMap images_;
 378
 379   gfx::Image empty_image_;
 380
 381   // The various font lists used. Cached to avoid repeated GDI
 382   // creation/destruction.
 383   scoped_ptr<gfx::FontList> base_font_list_;
 384   scoped_ptr<gfx::FontList> bold_font_list_;
 385   scoped_ptr<gfx::FontList> small_font_list_;
 386   scoped_ptr<gfx::FontList> small_bold_font_list_;
 387   scoped_ptr<gfx::FontList> medium_font_list_;
 388   scoped_ptr<gfx::FontList> medium_bold_font_list_;
 389   scoped_ptr<gfx::FontList> large_font_list_;
 390   scoped_ptr<gfx::FontList> large_bold_font_list_;
 391   scoped_ptr<gfx::FontList> web_font_list_;
 392
 393   base::FilePath overridden_pak_path_;
 394
 395   DISALLOW_COPY_AND_ASSIGN(ResourceBundle);
 396 };
 397
 398 }  // namespace ui
 399
 400 // TODO(beng): Someday, maybe, get rid of this.
 401 using ui::ResourceBundle;
 402
 403 #endif  // UI_BASE_RESOURCE_RESOURCE_BUNDLE_H_