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. 4 5 #ifndef UI_GFX_IMAGE_IMAGE_FAMILY_H_ 6 #define UI_GFX_IMAGE_IMAGE_FAMILY_H_ 7 8 #include <iterator> 9 #include <map> 10 #include <utility> 11 12 #include "ui/gfx/gfx_export.h" 13 #include "ui/gfx/image/image.h" 14 15 namespace gfx { 16 class ImageSkia; 17 class Size; 18 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. 23 // 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 { 29 private: 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> { MapKeyMapKey33 MapKey(float aspect, int width) 34 : std::pair<float, int>(aspect, width) {} 35 aspectMapKey36 float aspect() const { return first; } 37 widthMapKey38 int width() const { return second; } 39 }; 40 41 public: 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> { 46 public: 47 const_iterator(); 48 49 const_iterator(const const_iterator& other); 50 51 ~const_iterator(); 52 53 const_iterator& operator++() { 54 ++map_iterator_; 55 return *this; 56 } 57 58 const_iterator operator++(int /*unused*/) { 59 const_iterator result(*this); 60 ++(*this); 61 return result; 62 } 63 64 const_iterator& operator--() { 65 --map_iterator_; 66 return *this; 67 } 68 69 const_iterator operator--(int /*unused*/) { 70 const_iterator result(*this); 71 --(*this); 72 return result; 73 } 74 75 bool operator==(const const_iterator& other) const { 76 return map_iterator_ == other.map_iterator_; 77 } 78 79 bool operator!=(const const_iterator& other) const { 80 return map_iterator_ != other.map_iterator_; 81 } 82 83 const gfx::Image& operator*() const { 84 return map_iterator_->second; 85 } 86 87 const gfx::Image* operator->() const { 88 return &**this; 89 } 90 91 private: 92 friend class ImageFamily; 93 94 explicit const_iterator( 95 const std::map<MapKey, gfx::Image>::const_iterator& other); 96 97 std::map<MapKey, gfx::Image>::const_iterator map_iterator_; 98 }; 99 100 ImageFamily(); 101 ~ImageFamily(); 102 103 // Gets an iterator to the first image. begin()104 const_iterator begin() const { return const_iterator(map_.begin()); } 105 // Gets an iterator to one after the last image. end()106 const_iterator end() const { return const_iterator(map_.end()); } 107 108 // Determines whether the image family has no images in it. empty()109 bool empty() const { return map_.empty(); } 110 111 // Removes all images from the family. clear()112 void clear() { return map_.clear(); } 113 114 // Adds an image to the family. If another image is already present at the 115 // same size, it will be overwritten. 116 void Add(const gfx::Image& image); 117 118 // Adds an image to the family. If another image is already present at the 119 // same size, it will be overwritten. 120 void Add(const gfx::ImageSkia& image_skia); 121 122 // Gets the best image to use in a rectangle of |width|x|height|. 123 // Gets an image at the same aspect ratio as |width|:|height|, if possible, or 124 // if not, the closest aspect ratio. Among images of that aspect ratio, 125 // returns the smallest image with both its width and height bigger or equal 126 // to the requested size. If none exists, returns the largest image of that 127 // aspect ratio. If there are no images in the family, returns NULL. 128 const gfx::Image* GetBest(int width, int height) const; 129 130 // Gets the best image to use in a rectangle of |size|. 131 // Gets an image at the same aspect ratio as |size.width()|:|size.height()|, 132 // if possible, or if not, the closest aspect ratio. Among images of that 133 // aspect ratio, returns the smallest image with both its width and height 134 // bigger or equal to the requested size. If none exists, returns the largest 135 // image of that aspect ratio. If there are no images in the family, returns 136 // NULL. 137 const gfx::Image* GetBest(const gfx::Size& size) const; 138 139 private: 140 // Find the closest aspect ratio in the map to |desired_aspect|. 141 // Ties are broken by the thinner aspect. 142 // |map_| must not be empty. |desired_aspect| must be > 0.0. 143 float GetClosestAspect(float desired_aspect) const; 144 145 // Gets an image with aspect ratio |aspect|, at the best size for |width|. 146 // Returns the smallest image of aspect ratio |aspect| with its width bigger 147 // or equal to |width|. If none exists, returns the largest image of aspect 148 // ratio |aspect|. Behavior is undefined if there is not at least one image in 149 // |map_| of aspect ratio |aspect|. 150 const gfx::Image* GetWithExactAspect(float aspect, int width) const; 151 152 // Map from (aspect ratio, width) to image. 153 std::map<MapKey, gfx::Image> map_; 154 }; 155 156 } // namespace gfx 157 158 #endif // UI_GFX_IMAGE_IMAGE_FAMILY_H_ 159