ui/gfx/image/image_family.h

   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> {
  33     MapKey(float aspect, int width)
  34         : std::pair<float, int>(aspect, width) {}
  35
  36     float aspect() const { return first; }
  37
  38     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.
 104   const_iterator begin() const { return const_iterator(map_.begin()); }
 105   // Gets an iterator to one after the last image.
 106   const_iterator end() const { return const_iterator(map_.end()); }
 107
 108   // Determines whether the image family has no images in it.
 109   bool empty() const { return map_.empty(); }
 110
 111   // Removes all images from the family.
 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_