docs/user/interface/Region.dox

   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 */