1 // Copyright 2013 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_GFX_IMAGE_IMAGE_FAMILY_H_
6 #define UI_GFX_IMAGE_IMAGE_FAMILY_H_
12 #include "ui/gfx/gfx_export.h"
13 #include "ui/gfx/image/image.h"
19 // A collection of images at different sizes. The images should be different
20 // representations of the same basic concept (for example, an icon) at various
21 // sizes and (optionally) aspect ratios. A method is provided for finding the
22 // most appropriate image to fit in a given rectangle.
24 // NOTE: This is not appropriate for storing an image at a single logical pixel
25 // size, with high-DPI bitmap versions; use an Image or ImageSkia for that. Each
26 // image in an ImageFamily should have a different logical size (and may also
27 // include high-DPI representations).
28 class GFX_EXPORT ImageFamily {
30 // An <aspect ratio, DIP width> pair.
31 // A 0x0 image has aspect ratio 1.0. 0xN and Nx0 images are treated as 0x0.
32 struct MapKey : std::pair<float, int> {
33 MapKey(float aspect, int width)
34 : std::pair<float, int>(aspect, width) {}
36 float aspect() const { return first; }
38 int width() const { return second; }
42 // Type for iterating over all images in the family, in order.
43 // Dereferencing this iterator returns a gfx::Image.
44 class GFX_EXPORT const_iterator :
45 std::iterator<std::bidirectional_iterator_tag, const gfx::Image> {
49 const_iterator(const const_iterator& other);
51 const_iterator& operator++() {
56 const_iterator operator++(int /*unused*/) {
57 const_iterator result(*this);
62 const_iterator& operator--() {
67 const_iterator operator--(int /*unused*/) {
68 const_iterator result(*this);
73 bool operator==(const const_iterator& other) const {
74 return map_iterator_ == other.map_iterator_;
77 bool operator!=(const const_iterator& other) const {
78 return map_iterator_ != other.map_iterator_;
81 const gfx::Image& operator*() const {
82 return map_iterator_->second;
85 const gfx::Image* operator->() const {
90 friend class ImageFamily;
92 explicit const_iterator(
93 const std::map<MapKey, gfx::Image>::const_iterator& other);
95 std::map<MapKey, gfx::Image>::const_iterator map_iterator_;
101 // Gets an iterator to the first image.
102 const_iterator begin() const { return const_iterator(map_.begin()); }
103 // Gets an iterator to one after the last image.
104 const_iterator end() const { return const_iterator(map_.end()); }
106 // Determines whether the image family has no images in it.
107 bool empty() const { return map_.empty(); }
109 // Removes all images from the family.
110 void clear() { return map_.clear(); }
112 // Adds an image to the family. If another image is already present at the
113 // same size, it will be overwritten.
114 void Add(const gfx::Image& image);
116 // Adds an image to the family. If another image is already present at the
117 // same size, it will be overwritten.
118 void Add(const gfx::ImageSkia& image_skia);
120 // Gets the best image to use in a rectangle of |width|x|height|.
121 // Gets an image at the same aspect ratio as |width|:|height|, if possible, or
122 // if not, the closest aspect ratio. Among images of that aspect ratio,
123 // returns the smallest image with both its width and height bigger or equal
124 // to the requested size. If none exists, returns the largest image of that
125 // aspect ratio. If there are no images in the family, returns NULL.
126 const gfx::Image* GetBest(int width, int height) const;
128 // Gets the best image to use in a rectangle of |size|.
129 // Gets an image at the same aspect ratio as |size.width()|:|size.height()|,
130 // if possible, or if not, the closest aspect ratio. Among images of that
131 // aspect ratio, returns the smallest image with both its width and height
132 // bigger or equal to the requested size. If none exists, returns the largest
133 // image of that aspect ratio. If there are no images in the family, returns
135 const gfx::Image* GetBest(const gfx::Size& size) const;
138 // Find the closest aspect ratio in the map to |desired_aspect|.
139 // Ties are broken by the thinner aspect.
140 // |map_| must not be empty. |desired_aspect| must be > 0.0.
141 float GetClosestAspect(float desired_aspect) const;
143 // Gets an image with aspect ratio |aspect|, at the best size for |width|.
144 // Returns the smallest image of aspect ratio |aspect| with its width bigger
145 // or equal to |width|. If none exists, returns the largest image of aspect
146 // ratio |aspect|. Behavior is undefined if there is not at least one image in
147 // |map_| of aspect ratio |aspect|.
148 const gfx::Image* GetWithExactAspect(float aspect, int width) const;
150 // Map from (aspect ratio, width) to image.
151 std::map<MapKey, gfx::Image> map_;
156 #endif // UI_GFX_IMAGE_IMAGE_FAMILY_H_