1/* 2 * Copyright 2014 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Stephan Aßmus, superstippi@gmx.de 7 * Stefano Ceccherini, burton666@libero.it 8 * John Scipione, jscipione@gmail.com 9 * 10 * Corresponds to: 11 * headers/os/interface/Region.h hrev47312 12 * src/kits/interface/Region.cpp hrev47312 13 */ 14 15 16/*! 17 \file Region.h 18 \ingroup interface 19 \ingroup libbe 20 \brief BRegion class definition. 21*/ 22 23 24/*! 25 \class BRegion 26 \ingroup interface 27 \ingroup libbe 28 \brief An area composed of rectangles. 29 30 The rectangles do not need to overlap. This class is useful for creating 31 clipping masks. 32 33 \warning BRegion is designed to be used with integral coordinates only. 34*/ 35 36 37/*! 38 \fn BRegion::BRegion() 39 \brief Initializes an empty region. The region contains no rectangles, 40 and its bounds are invalid. 41*/ 42 43 44/*! 45 \fn BRegion::BRegion(const BRegion& other) 46 \brief Initializes a region as a copy of \a other. 47 48 \param other The region to copy. 49*/ 50 51 52/*! 53 \fn BRegion::BRegion(const BRect rect) 54 \brief Initializes a region to contain a \a rect. 55 56 \param rect The BRect to add to the region. 57*/ 58 59 60/*! 61 \fn BRegion::BRegion(const clipping_rect& clipping) 62 \brief Initializes a region to contain a clipping_rect. 63 64 \param clipping The clipping_rect to set the region to, already in 65 internal rect format. 66*/ 67 68 69/*! 70 \fn BRegion::~BRegion() 71 \brief Destroys the BRegion freeing any memory allocated by it. 72*/ 73 74 75/*! 76 \fn BRegion& BRegion::operator=(const BRegion& other) 77 \brief Modifies the BRegion to be a copy of \a other. 78 79 \param other the BRegion to copy. 80 81 \return This method always returns \c *this. 82*/ 83 84 85/*! 86 \fn bool BRegion::operator==(const BRegion& other) const 87 \brief Compares this region to \a other by value. 88 89 \param other the BRegion to compare to. 90 91 \return \c true if the regions are the same, \c false otherwise. 92*/ 93 94 95/*! 96 \fn void BRegion::Set(BRect newBounds) 97 \brief Set the region to bounds of \a newBounds. 98 99 \param newBounds The BRect to set the bounds to. 100*/ 101 102 103/*! 104 \fn void BRegion::Set(clipping_rect newBounds) 105 \brief Set the region to the bounds of \a clipping_rect. 106 107 \param newBounds The clipping_rect to set the bounds to. 108*/ 109 110 111/*! 112 \fn BRect BRegion::Frame() const 113 \brief Returns the region's bounds. 114 115 \return A BRect which represents the region's bounds. 116*/ 117 118 119/*! 120 \fn clipping_rect BRegion::FrameInt() const 121 \brief Returns the bounds of the region as a clipping_rect 122 (which has integer coordinates). 123 124 \return The clipping_rect which represents the region's bounds. 125*/ 126 127 128/*! 129 \fn BRect BRegion::RectAt(int32 index) 130 \brief Returns the rectangle contained in the region at the given \a index. 131 132 \param index The index of the BRect to retreive. 133 134 \return If the given index is valid, it returns the BRect at that index, 135 otherwise, it returns an invalid BRect. 136*/ 137 138 139/*! 140 \fn BRect BRegion::RectAt(int32 index) const 141 \brief Returns the rectangle contained in the region at the given \a index. 142 143 \param index The index of the BRect to retreive. (zero based) 144 145 \return If the given index is valid, it returns the BRect at that index, 146 otherwise, it returns an invalid BRect. 147*/ 148 149 150/*! 151 fn clipping_rect BRegion::RectAtInt(int32 index) 152 \brief Returns the clipping_rect contained in the region at the given 153 \a index. 154 155 \param index The index of the clipping_rect to retrieve. (zero based) 156 157 \return If the given index is valid, it returns the clipping_rect at that 158 index, otherwise, it returns an invalid clipping_rect. 159*/ 160 161 162/*! 163 \fn clipping_rect BRegion::RectAtInt(int32 index) const 164 \brief Returns the clipping_rect contained in the region at the given 165 \a index. 166 167 \param index The index of the clipping_rect to retrieve. (zero based) 168 169 \return If the given index is valid, it returns the clipping_rect at that 170 index, otherwise, it returns an invalid clipping_rect. 171*/ 172 173 174/*! 175 \fn int32 BRegion::CountRects() 176 \brief Returns the number of rectangles contained in the region. 177 178 \return The number of rectangles in the region as an int32. 179*/ 180 181 182/*! 183 \fn int32 BRegion::CountRects() const 184 \brief Returns the number of rectangles contained in the region. 185 186 \return The number of rectangles in the region as an int32. 187*/ 188 189 190/*! 191 \fn bool BRegion::Intersects(BRect rect) const 192 \brief Returns whether or not the region has any area in common with 193 \a rect. 194 195 \param rect The BRect to check the region against. 196 197 \return \c true if the region has any area in common with the BRect, 198 \c false if not. 199*/ 200 201 202/*! 203 \fn bool BRegion::Intersects(clipping_rect clipping) const 204 \brief Returns whether or not the region has any area in common with 205 \a clipping. 206 207 \param clipping The clipping_rect to check the region against. 208 209 \return \c true if the region has any area in common with the 210 clipping_rect, \c false if not. 211*/ 212 213 214/*! 215 \fn bool BRegion::Contains(BPoint point) const 216 \brief Returns whether or not if the region contains the given \a point. 217 218 \param point The \a point to check. 219 220 \return \c true if the region contains the \a point, \c false if not. 221*/ 222 223 224/*! 225 \fn bool BRegion::Contains(int32 x, int32 y) 226 \brief Returns whether or not the region contains the given coordinates. 227 228 \param x The \c x coordinate of the point to check. 229 \param y The \c y coordinate of the point to check. 230 231 \return \c true if the region contains the point, \c false if not. 232*/ 233 234 235/*! 236 \fn bool BRegion::Contains(int32 x, int32 y) const 237 \brief Return whether or not the region contains the given coordinates. 238 239 \param x The \c x coordinate of the point to check. 240 \param y The \c y coordinate of the point to check. 241 242 \return \c true if the region contains the point, \c false if not. 243*/ 244 245 246/*! 247 \fn void BRegion::PrintToStream() const 248 \brief Prints each rect in the the BRegion to standard output. 249*/ 250 251 252/*! 253 \fn void BRegion::OffsetBy(const BPoint& point) 254 \brief Applies the given offsets given by the x and y coordinates of 255 \a point to each rectangle contained in the region and recalculates 256 the region's bounds. 257 258 \param point The point to get the coordinates to offset by. 259*/ 260 261 262/*! 263 \fn void BRegion::OffsetBy(int32 x, int32 y) 264 \brief Applies the given \a x and \a y offsets to each rectangle contained 265 in the region and recalculates the region's bounds. 266 267 \param x The horizontal offset. 268 \param y The vertical offset. 269*/ 270 271 272/*! 273 \fn void BRegion::MakeEmpty() 274 \brief Empties the region so that it doesn't containt any rects, and 275 invalidates its bounds. 276*/ 277 278 279/*! 280 \fn void BRegion::Include(BRect rect) 281 \brief Modifies the region so that it includes the given \a rect. 282 283 \param rect The BRect to include in the region. 284*/ 285 286 287/*! 288 \fn void BRegion::Include(clipping_rect clipping) 289 \brief Modifies the region so that it includes the given \a clipping 290 rectangle. 291 292 \param clipping The clipping_rect to include in the region. 293*/ 294 295 296/*! 297 \fn void BRegion::Include(const BRegion* region) 298 \brief Modifies the region to include the area of the given \a region. 299 300 \param region The \a region to be included. 301*/ 302 303 304/*! 305 \fn void BRegion::Exclude(BRect rect) 306 \brief Modifies the region excluding the area of the given \a rect. 307 308 \param rect The BRect to be excluded. 309*/ 310 311 312/*! 313 \fn void BRegion::Exclude(clipping_rect clipping) 314 \brief Modifies the region excluding the area of the given \a clipping 315 rectangle. 316 317 \param clipping The clipping_rect to be excluded. 318*/ 319 320 321/*! 322 \fn void BRegion::Exclude(const BRegion* region) 323 \brief Modifies the region excluding the area contained by the given 324 \a region. 325 326 \param region The BRegion to be excluded. 327*/ 328 329 330/*! 331 \fn void BRegion::IntersectWith(const BRegion* region) 332 \brief Modifies the region, so that it will contain only the area 333 in common with \a region. 334 335 \param region the BRegion to intersect with. 336*/ 337 338 339/*! 340 \fn void BRegion::ExclusiveInclude(const BRegion* region) 341 \brief Modifies the region so that it contains only the area 342 which the BRegion and \a region do NOT have in common. 343 344 \param region the BRegion to exclusively include. 345*/ 346 347 348/*! 349 \fn void BRegion::_AdoptRegionData(BRegion& region) 350 \brief Takes over the data of \a region and empties it. 351 352 \param region The \a region to adopt data from. 353*/ 354 355 356/*! 357 \fn bool BRegion::_SetSize(int32 newSize) 358 \brief Reallocate the memory in the region. 359 360 \param newSize The amount of rectangles that the region should be 361 able to hold. 362*/ 363