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