juce/source/src/gui/graphics/geometry/juce_RectangleList.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_RECTANGLELIST_JUCEHEADER__
  27 #define __JUCE_RECTANGLELIST_JUCEHEADER__
  28
  29 #include "juce_Rectangle.h"
  30 #include "juce_Path.h"
  31
  32
  33 //==============================================================================
  34 /**
  35     Maintains a set of rectangles as a complex region.
  36
  37     This class allows a set of rectangles to be treated as a solid shape, and can
  38     add and remove rectangular sections of it, and simplify overlapping or
  39     adjacent rectangles.
  40
  41     @see Rectangle
  42 */
  43 class JUCE_API  RectangleList
  44 {
  45 public:
  46     //==============================================================================
  47     /** Creates an empty RectangleList */
  48     RectangleList() noexcept;
  49
  50     /** Creates a copy of another list */
  51     RectangleList (const RectangleList& other);
  52
  53     /** Creates a list containing just one rectangle. */
  54     RectangleList (const Rectangle<int>& rect);
  55
  56     /** Copies this list from another one. */
  57     RectangleList& operator= (const RectangleList& other);
  58
  59     /** Destructor. */
  60     ~RectangleList();
  61
  62     //==============================================================================
  63     /** Returns true if the region is empty. */
  64     bool isEmpty() const noexcept;
  65
  66     /** Returns the number of rectangles in the list. */
  67     int getNumRectangles() const noexcept                       { return rects.size(); }
  68
  69     /** Returns one of the rectangles at a particular index.
  70
  71         @returns    the rectangle at the index, or an empty rectangle if the
  72                     index is out-of-range.
  73     */
  74     Rectangle<int> getRectangle (int index) const noexcept;
  75
  76
  77     //==============================================================================
  78     /** Removes all rectangles to leave an empty region. */
  79     void clear();
  80
  81     /** Merges a new rectangle into the list.
  82
  83         The rectangle being added will first be clipped to remove any parts of it
  84         that overlap existing rectangles in the list.
  85     */
  86     void add (int x, int y, int width, int height);
  87
  88     /** Merges a new rectangle into the list.
  89
  90         The rectangle being added will first be clipped to remove any parts of it
  91         that overlap existing rectangles in the list, and adjacent rectangles will be
  92         merged into it.
  93     */
  94     void add (const Rectangle<int>& rect);
  95
  96     /** Dumbly adds a rectangle to the list without checking for overlaps.
  97
  98         This simply adds the rectangle to the end, it doesn't merge it or remove
  99         any overlapping bits.
 100     */
 101     void addWithoutMerging (const Rectangle<int>& rect);
 102
 103     /** Merges another rectangle list into this one.
 104
 105         Any overlaps between the two lists will be clipped, so that the result is
 106         the union of both lists.
 107     */
 108     void add (const RectangleList& other);
 109
 110     /** Removes a rectangular region from the list.
 111
 112         Any rectangles in the list which overlap this will be clipped and subdivided
 113         if necessary.
 114     */
 115     void subtract (const Rectangle<int>& rect);
 116
 117     /** Removes all areas in another RectangleList from this one.
 118
 119         Any rectangles in the list which overlap this will be clipped and subdivided
 120         if necessary.
 121
 122         @returns true if the resulting list is non-empty.
 123     */
 124     bool subtract (const RectangleList& otherList);
 125
 126     /** Removes any areas of the region that lie outside a given rectangle.
 127
 128         Any rectangles in the list which overlap this will be clipped and subdivided
 129         if necessary.
 130
 131         Returns true if the resulting region is not empty, false if it is empty.
 132
 133         @see getIntersectionWith
 134     */
 135     bool clipTo (const Rectangle<int>& rect);
 136
 137     /** Removes any areas of the region that lie outside a given rectangle list.
 138
 139         Any rectangles in this object which overlap the specified list will be clipped
 140         and subdivided if necessary.
 141
 142         Returns true if the resulting region is not empty, false if it is empty.
 143
 144         @see getIntersectionWith
 145     */
 146     bool clipTo (const RectangleList& other);
 147
 148     /** Creates a region which is the result of clipping this one to a given rectangle.
 149
 150         Unlike the other clipTo method, this one doesn't affect this object - it puts the
 151         resulting region into the list whose reference is passed-in.
 152
 153         Returns true if the resulting region is not empty, false if it is empty.
 154
 155         @see clipTo
 156     */
 157     bool getIntersectionWith (const Rectangle<int>& rect, RectangleList& destRegion) const;
 158
 159     /** Swaps the contents of this and another list.
 160
 161         This swaps their internal pointers, so is hugely faster than using copy-by-value
 162         to swap them.
 163     */
 164     void swapWith (RectangleList& otherList) noexcept;
 165
 166     //==============================================================================
 167     /** Checks whether the region contains a given point.
 168
 169         @returns true if the point lies within one of the rectangles in the list
 170     */
 171     bool containsPoint (int x, int y) const noexcept;
 172
 173     /** Checks whether the region contains the whole of a given rectangle.
 174
 175         @returns    true all parts of the rectangle passed in lie within the region
 176                     defined by this object
 177         @see intersectsRectangle, containsPoint
 178     */
 179     bool containsRectangle (const Rectangle<int>& rectangleToCheck) const;
 180
 181     /** Checks whether the region contains any part of a given rectangle.
 182
 183         @returns    true if any part of the rectangle passed in lies within the region
 184                     defined by this object
 185         @see containsRectangle
 186     */
 187     bool intersectsRectangle (const Rectangle<int>& rectangleToCheck) const noexcept;
 188
 189     /** Checks whether this region intersects any part of another one.
 190
 191         @see intersectsRectangle
 192     */
 193     bool intersects (const RectangleList& other) const noexcept;
 194
 195     //==============================================================================
 196     /** Returns the smallest rectangle that can enclose the whole of this region. */
 197     Rectangle<int> getBounds() const noexcept;
 198
 199     /** Optimises the list into a minimum number of constituent rectangles.
 200
 201         This will try to combine any adjacent rectangles into larger ones where
 202         possible, to simplify lists that might have been fragmented by repeated
 203         add/subtract calls.
 204     */
 205     void consolidate();
 206
 207     /** Adds an x and y value to all the co-ordinates. */
 208     void offsetAll (int dx, int dy) noexcept;
 209
 210     //==============================================================================
 211     /** Creates a Path object to represent this region. */
 212     Path toPath() const;
 213
 214
 215     //==============================================================================
 216     /** An iterator for accessing all the rectangles in a RectangleList. */
 217     class JUCE_API  Iterator
 218     {
 219     public:
 220         //==============================================================================
 221         Iterator (const RectangleList& list) noexcept;
 222         ~Iterator();
 223
 224         //==============================================================================
 225         /** Advances to the next rectangle, and returns true if it's not finished.
 226
 227             Call this before using getRectangle() to find the rectangle that was returned.
 228         */
 229         bool next() noexcept;
 230
 231         /** Returns the current rectangle. */
 232         const Rectangle<int>* getRectangle() const noexcept      { return current; }
 233
 234     private:
 235         const Rectangle<int>* current;
 236         const RectangleList& owner;
 237         int index;
 238
 239         JUCE_DECLARE_NON_COPYABLE (Iterator);
 240     };
 241
 242 private:
 243     //==============================================================================
 244     friend class Iterator;
 245     Array <Rectangle<int> > rects;
 246
 247     JUCE_LEAK_DETECTOR (RectangleList);
 248 };
 249
 250
 251 #endif   // __JUCE_RECTANGLELIST_JUCEHEADER__