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