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