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 \since BeOS R3 36*/ 37 38 39/*! 40 \fn BRegion::BRegion() 41 \brief Initializes an empty region. The region contains no rectangles, 42 and its bounds are invalid. 43 44 \since BeOS R3 45*/ 46 47 48/*! 49 \fn BRegion::BRegion(const BRegion& other) 50 \brief Initializes a region as a copy of \a other. 51 52 \param other The region to copy. 53 54 \since BeOS R3 55*/ 56 57 58/*! 59 \fn BRegion::BRegion(const BRect rect) 60 \brief Initializes a region to contain a \a rect. 61 62 \param rect The BRect to add to the region. 63 64 \since BeOS R5 65*/ 66 67 68/*! 69 \fn BRegion::BRegion(const clipping_rect& clipping) 70 \brief Initializes a region to contain a clipping_rect. 71 72 \param clipping The clipping_rect to set the region to, already in 73 internal rect format. 74 75 \since Haiku R1 76*/ 77 78 79/*! 80 \fn BRegion::~BRegion() 81 \brief Destroys the BRegion freeing any memory allocated by it. 82 83 \since BeOS R3 84*/ 85 86 87/*! 88 \name Operators 89*/ 90 91 92//! @{ 93 94 95/*! 96 \fn BRegion& BRegion::operator=(const BRegion& other) 97 \brief Modifies the BRegion to be a copy of \a other. 98 99 \param other the BRegion to copy. 100 101 \return This method always returns \c *this. 102 103 \since BeOS R3 104*/ 105 106 107/*! 108 \fn bool BRegion::operator==(const BRegion& other) const 109 \brief Compares this region to \a other by value. 110 111 \param other the BRegion to compare to. 112 113 \return \c true if the regions are the same, \c false otherwise. 114 115 \since BeOS R3 116*/ 117 118 119//! @} 120 121 122/*! 123 \fn void BRegion::Set(BRect rect) 124 \brief Set the region to bounds of \a newBounds. 125 126 \param rect The BRect to set the bounds to. 127 128 \since BeOS R3 129*/ 130 131 132/*! 133 \fn void BRegion::Set(clipping_rect clipping) 134 \brief Set the region to the bounds of \a clipping_rect. 135 136 \param clipping The clipping_rect to set the bounds to. 137 138 \since Haiku R1 139*/ 140 141 142/*! 143 \fn BRect BRegion::Frame() const 144 \brief Returns a rectangle that encloses the BRegion. 145 146 \return A BRect that encloses the BRegion. 147 148 \since BeOS R3 149*/ 150 151 152/*! 153 \fn clipping_rect BRegion::FrameInt() const 154 \brief Returns the bounds of the region as a clipping_rect 155 (which has integer coordinates). 156 157 \return The clipping_rect which represents the region's bounds. 158 159 \since Haiku R1 160*/ 161 162 163/*! 164 \fn BRect BRegion::RectAt(int32 index) 165 \brief Returns the rectangle contained in the region at the given \a index. 166 167 \param index The index of the BRect to retreive. 168 169 \return If the given index is valid, it returns the BRect at that index, 170 otherwise, it returns an invalid BRect. 171 172 \since BeOS R3 173*/ 174 175 176/*! 177 \fn BRect BRegion::RectAt(int32 index) const 178 \brief Returns the rectangle contained in the region at the given \a index. 179 180 \param index The index of the BRect to retreive. (zero based) 181 182 \return If the given index is valid, it returns the BRect at that index, 183 otherwise, it returns an invalid BRect. 184 185 \since Haiku R1 186*/ 187 188 189/*! 190 \fn clipping_rect BRegion::RectAtInt(int32 index) 191 \brief Returns the clipping_rect contained in the region at the given 192 \a index. 193 194 \param index The index of the clipping_rect to retrieve. (zero based) 195 196 \return If the given index is valid, it returns the clipping_rect at that 197 index, otherwise, it returns an invalid clipping_rect. 198 199 \since Haiku R1 200*/ 201 202 203/*! 204 \fn clipping_rect BRegion::RectAtInt(int32 index) const 205 \brief Returns the clipping_rect contained in the region at the given 206 \a index. 207 208 \param index The index of the clipping_rect to retrieve. (zero based) 209 210 \return If the given index is valid, it returns the clipping_rect at that 211 index, otherwise, it returns an invalid clipping_rect. 212 213 \since Haiku R1 214*/ 215 216 217/*! 218 \fn int32 BRegion::CountRects() 219 \brief Returns the number of rectangles contained in the region. 220 221 \return The number of rectangles in the region as an int32. 222 223 \since BeOS R3 224*/ 225 226 227/*! 228 \fn int32 BRegion::CountRects() const 229 \brief Returns the number of rectangles contained in the region. 230 231 \return The number of rectangles in the region as an int32. 232 233 \since Haiku R1 234*/ 235 236 237/*! 238 \fn bool BRegion::Intersects(BRect rect) const 239 \brief Returns whether or not the region has any area in common with 240 \a rect. 241 242 \param rect The BRect to check the region against. 243 244 \return \c true if the region has any area in common with the BRect, 245 \c false if not. 246 247 \since BeOS R3 248*/ 249 250 251/*! 252 \fn bool BRegion::Intersects(clipping_rect clipping) const 253 \brief Returns whether or not the region has any area in common with 254 \a clipping. 255 256 \param clipping The clipping_rect to check the region against. 257 258 \return \c true if the region has any area in common with the 259 clipping_rect, \c false if not. 260 261 \since Haiku R1 262*/ 263 264 265/*! 266 \fn bool BRegion::Contains(BPoint point) const 267 \brief Returns whether or not if the region contains the given \a point. 268 269 \param point The \a point to check. 270 271 \return \c true if the region contains the \a point, \c false if not. 272 273 \since BeOS R3 274*/ 275 276 277/*! 278 \fn bool BRegion::Contains(int32 x, int32 y) 279 \brief Returns whether or not the region contains the given coordinates. 280 281 \param x The \c x coordinate of the point to check. 282 \param y The \c y coordinate of the point to check. 283 284 \return \c true if the region contains the point, \c false if not. 285 286 \since Haiku R1 287*/ 288 289 290/*! 291 \fn bool BRegion::Contains(int32 x, int32 y) const 292 \brief Return whether or not the region contains the given coordinates. 293 294 \param x The \c x coordinate of the point to check. 295 \param y The \c y coordinate of the point to check. 296 297 \return \c true if the region contains the point, \c false if not. 298 299 \since Haiku R1 300*/ 301 302 303/*! 304 \fn void BRegion::PrintToStream() const 305 \brief Prints each rect in the the BRegion to standard output. 306 307 \since BeOS R3 308*/ 309 310 311/*! 312 \fn void BRegion::OffsetBy(const BPoint& point) 313 \brief Applies the given offsets given by the x and y coordinates of 314 \a point to each rectangle contained in the region and recalculates 315 the region's bounds. 316 317 \param point The point to get the coordinates to offset by. 318 319 \since Haiku R1 320*/ 321 322 323/*! 324 \fn void BRegion::OffsetBy(int32 x, int32 y) 325 \brief Applies the given \a x and \a y offsets to each rectangle contained 326 in the region and recalculates the region's bounds. 327 328 \param x The horizontal offset. 329 \param y The vertical offset. 330 331 \since BeOS R3 332*/ 333 334 335/*! 336 \fn void BRegion::ScaleBy(BSize scale) 337 \brief Resize each of the contained rectangles by the given factor 338 and recalculates the region's bounds. 339 340 \param scale The scale factor 341 342 \since Haiku R1 343*/ 344 345 346/*! 347 \fn void BRegion::ScaleBy(float x, float y) 348 \brief Resize each of the contained rectangles by the given factors 349 and recalculates the region's bounds. 350 351 \param x The horizontal scale. 352 \param y The vertical scale. 353 354 \since Haiku R1 355*/ 356 357 358/*! 359 \fn void BRegion::MakeEmpty() 360 \brief Empties the region so that it doesn't containt any rects, and 361 invalidates its bounds. 362 363 \since BeOS R3 364*/ 365 366 367/*! 368 \fn void BRegion::Include(BRect rect) 369 \brief Modifies the region so that it includes the given \a rect. 370 371 \param rect The BRect to include in the region. 372 373 \since BeOS R3 374*/ 375 376 377/*! 378 \fn void BRegion::Include(clipping_rect clipping) 379 \brief Modifies the region so that it includes the given \a clipping 380 rectangle. 381 382 \param clipping The clipping_rect to include in the region. 383 384 \since Haiku R1 385*/ 386 387 388/*! 389 \fn void BRegion::Include(const BRegion* region) 390 \brief Modifies the region to include the area of the given \a region. 391 392 \param region The \a region to be included. 393 394 \since BeOS R3 395*/ 396 397 398/*! 399 \fn void BRegion::Exclude(BRect rect) 400 \brief Modifies the region excluding the area of the given \a rect. 401 402 \param rect The BRect to be excluded. 403 404 \since BeOS R3 405*/ 406 407 408/*! 409 \fn void BRegion::Exclude(clipping_rect clipping) 410 \brief Modifies the region excluding the area of the given \a clipping 411 rectangle. 412 413 \param clipping The clipping_rect to be excluded. 414 415 \since Haiku R1 416*/ 417 418 419/*! 420 \fn void BRegion::Exclude(const BRegion* region) 421 \brief Modifies the region excluding the area contained by the given 422 \a region. 423 424 \param region The BRegion to be excluded. 425 426 \since BeOS R3 427*/ 428 429 430/*! 431 \fn void BRegion::IntersectWith(const BRegion* region) 432 \brief Modifies the region, so that it will contain only the area 433 in common with \a region. 434 435 \param region the BRegion to intersect with. 436 437 \since BeOS R3 438*/ 439 440 441/*! 442 \fn void BRegion::ExclusiveInclude(const BRegion* region) 443 \brief Modifies the region so that it contains only the area 444 which the BRegion and \a region do NOT have in common. 445 446 \param region the BRegion to exclusively include. 447 448 \since Haiku R1 449*/ 450