i2p/haiku-beta6
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

BRegion: Style updates for documentation.

Browse Source 
No functional changes intended.

* Updated copyright information.
* Reduced doxygen documentation down to a helpful summary
  in a regular comment, the documentation has been moved into
  the Haiku Book.
* Some parameter renaming for consistency and clarity.
* A few other style fixes.
This commit is contained in:
John Scipione
2014-06-03 20:26:45 -04:00
parent c1400fb617
commit 44cee34013
2 changed files with 87 additions and 181 deletions
Download Patch File Download Diff File Expand all files Collapse all files
headers/os/interface/Region.h
+11 -9
View File
@@ -1,13 +1,14 @@
/* /*
* Copyright 2007, Haiku, Inc. All rights reserved. * Copyright 2003-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License. * Distributed under the terms of the MIT License.
*/ */
#ifndef _REGION_H #ifndef _REGION_H
#define _REGION_H #define _REGION_H
#include <Rect.h> #include <Rect.h>
namespace BPrivate { namespace BPrivate {
class ServerLink; class ServerLink;
class LinkReceiver; class LinkReceiver;
@@ -26,11 +27,11 @@ typedef struct {
class BRegion { class BRegion {
public: public:
BRegion(); BRegion();
BRegion(const BRegion& region); BRegion(const BRegion& other);
BRegion(const BRect rect); BRegion(const BRect rect);
virtual ~BRegion(); virtual ~BRegion();
BRegion& operator=(const BRegion& from); BRegion& operator=(const BRegion& other);
bool operator==(const BRegion& other) const; bool operator==(const BRegion& other) const;
void Set(BRect newBounds); void Set(BRect newBounds);
@@ -48,7 +49,7 @@ public:
int32 CountRects() const; int32 CountRects() const;
bool Intersects(BRect rect) const; bool Intersects(BRect rect) const;
bool Intersects(clipping_rect rect) const; bool Intersects(clipping_rect clipping) const;
bool Contains(BPoint point) const; bool Contains(BPoint point) const;
bool Contains(int32 x, int32 y); bool Contains(int32 x, int32 y);
@@ -62,11 +63,11 @@ public:
void MakeEmpty(); void MakeEmpty();
void Include(BRect rect); void Include(BRect rect);
void Include(clipping_rect rect); void Include(clipping_rect clipping);
void Include(const BRegion* region); void Include(const BRegion* region);
void Exclude(BRect r); void Exclude(BRect rect);
void Exclude(clipping_rect r); void Exclude(clipping_rect clipping);
void Exclude(const BRegion* region); void Exclude(const BRegion* region);
void IntersectWith(const BRegion* region); void IntersectWith(const BRegion* region);
@@ -82,7 +83,7 @@ private:
friend class Support; friend class Support;
private: private:
BRegion(const clipping_rect& rect); BRegion(const clipping_rect& other);
void _AdoptRegionData(BRegion& region); void _AdoptRegionData(BRegion& region);
bool _SetSize(int32 newSize); bool _SetSize(int32 newSize);
@@ -99,4 +100,5 @@ private:
clipping_rect* fData; clipping_rect* fData;
}; };
#endif // _REGION_H #endif // _REGION_H
src/kits/interface/Region.cpp
+76 -172
View File
@@ -1,10 +1,10 @@
/* /*
* Copyright 2003-2007, Haiku. All rights reserved. * Copyright 2003-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License. * Distributed under the terms of the MIT License.
* *
* Authors: * Authors:
* Stefano Ceccherini ([email protected]) * Stephan Aßmus, [email protected]
* Stephan Aßmus <[email protected]> * Stefano Ceccherini, [email protected]
*/ */
@@ -22,9 +22,7 @@
const static int32 kDataBlockSize = 8; const static int32 kDataBlockSize = 8;
/*! \brief Initializes a region. The region will have no rects, // Initializes an empty region.
and its fBounds will be invalid.
*/
BRegion::BRegion() BRegion::BRegion()
: :
fCount(0), fCount(0),
@@ -36,23 +34,19 @@ BRegion::BRegion()
} }
/*! \brief Initializes a region to be a copy of another. // Initializes a region to be a copy of another.
\param region The region to copy. BRegion::BRegion(const BRegion& other)
*/
BRegion::BRegion(const BRegion& region)
: :
fCount(0), fCount(0),
fDataSize(0), fDataSize(0),
fBounds((clipping_rect){ 0, 0, 0, 0 }), fBounds((clipping_rect){ 0, 0, 0, 0 }),
fData(NULL) fData(NULL)
{ {
*this = region; *this = other;
} }
/*! \brief Initializes a region to contain a BRect. // Initializes a region to contain a BRect.
\param rect The BRect to set the region to.
*/
BRegion::BRegion(const BRect rect) BRegion::BRegion(const BRect rect)
: :
fCount(0), fCount(0),
@@ -67,22 +61,19 @@ BRegion::BRegion(const BRect rect)
fCount = 1; fCount = 1;
} }
// Initializes a region to contain a clipping_rect.
// NOTE: private constructor // NOTE: private constructor
/*! \brief Initializes a region to contain a clipping_rect.
\param rect The clipping_rect to set the region to, already in
internal rect format.
*/
BRegion::BRegion(const clipping_rect& rect) BRegion::BRegion(const clipping_rect& rect)
: fCount(1) :
, fDataSize(1) fCount(1),
, fBounds(rect) fDataSize(1),
, fData(&fBounds) fBounds(rect),
fData(&fBounds)
{ {
} }
/*! \brief Frees the allocated memory.
*/
BRegion::~BRegion() BRegion::~BRegion()
{ {
if (fData != &fBounds) if (fData != &fBounds)
@@ -90,36 +81,27 @@ BRegion::~BRegion()
} }
// #pragma mark - // Modifies the region to be a copy of the given BRegion.
/*! \brief Modifies the region to be a copy of the given BRegion.
\param region the BRegion to copy.
\return This function always returns \c *this.
*/
BRegion& BRegion&
BRegion::operator=(const BRegion& region) BRegion::operator=(const BRegion& other)
{ {
if (&region == this) if (&other == this)
return *this; return *this;
// handle reallocation if we're too small to contain // handle reallocation if we're too small to contain
// the other region // the other other
if (_SetSize(region.fDataSize)) { if (_SetSize(other.fDataSize)) {
memcpy(fData, region.fData, region.fCount * sizeof(clipping_rect)); memcpy(fData, other.fData, other.fCount * sizeof(clipping_rect));
fBounds = region.fBounds; fBounds = other.fBounds;
fCount = region.fCount; fCount = other.fCount;
} }
return *this; return *this;
} }
/*! \brief Compares this region to another (by value). // Compares this region to another (by value).
\param other the BRegion to compare to.
\return \ctrue if the two regions are the same, \cfalse otherwise.
*/
bool bool
BRegion::operator==(const BRegion& other) const BRegion::operator==(const BRegion& other) const
{ {
@@ -133,9 +115,7 @@ BRegion::operator==(const BRegion& other) const
} }
/*! \brief Set the region to contain just the given BRect. // Set the region to contain just the given BRect.
\param newBounds A BRect.
*/
void void
BRegion::Set(BRect newBounds) BRegion::Set(BRect newBounds)
{ {
@@ -143,9 +123,7 @@ BRegion::Set(BRect newBounds)
} }
/*! \brief Set the region to contain just the given clipping_rect. //Set the region to contain just the given clipping_rect.
\param newBounds A clipping_rect.
*/
void void
BRegion::Set(clipping_rect newBounds) BRegion::Set(clipping_rect newBounds)
{ {
@@ -162,12 +140,7 @@ BRegion::Set(clipping_rect newBounds)
} }
// #pragma mark - // Returns the bounds of the region.
/*! \brief Returns the bounds of the region.
\return A BRect which represents the bounds of the region.
*/
BRect BRect
BRegion::Frame() const BRegion::Frame() const
{ {
@@ -176,9 +149,8 @@ BRegion::Frame() const
} }
/*! \brief Returns the bounds of the region as a clipping_rect (which has integer coordinates). // Returns the bounds of the region as a clipping_rect
\return A clipping_rect which represents the bounds of the region. // (which has integer coordinates).
*/
clipping_rect clipping_rect
BRegion::FrameInt() const BRegion::FrameInt() const
{ {
@@ -187,6 +159,7 @@ BRegion::FrameInt() const
} }
// Returns the rect contained in the region at the given index.
BRect BRect
BRegion::RectAt(int32 index) BRegion::RectAt(int32 index)
{ {
@@ -194,11 +167,7 @@ BRegion::RectAt(int32 index)
} }
/*! \brief Returns the regions's BRect at the given index. // Returns the rect contained in the region at the given index. (const)
\param index The index (zero based) of the wanted rectangle.
\return If the given index is valid, it returns the BRect at that index,
otherwise, it returns an invalid BRect.
*/
BRect BRect
BRegion::RectAt(int32 index) const BRegion::RectAt(int32 index) const
{ {
@@ -212,6 +181,7 @@ BRegion::RectAt(int32 index) const
} }
// Returns the clipping_rect contained in the region at the given index.
clipping_rect clipping_rect
BRegion::RectAtInt(int32 index) BRegion::RectAtInt(int32 index)
{ {
@@ -219,11 +189,7 @@ BRegion::RectAtInt(int32 index)
} }
/*! \brief Returns the regions's clipping_rect at the given index. // Returns the clipping_rect contained in the region at the given index.
\param index The index (zero based) of the wanted rectangle.
\return If the given index is valid, it returns the clipping_rect at that index,
otherwise, it returns an invalid clipping_rect.
*/
clipping_rect clipping_rect
BRegion::RectAtInt(int32 index) const BRegion::RectAtInt(int32 index) const
{ {
@@ -237,9 +203,7 @@ BRegion::RectAtInt(int32 index) const
} }
/*! \brief Counts the region rects. // Returns the number of rects contained in the region.
\return An int32 which is the total number of rects in the region.
*/
int32 int32
BRegion::CountRects() BRegion::CountRects()
{ {
@@ -247,9 +211,7 @@ BRegion::CountRects()
} }
/*! \brief Counts the region rects. // Returns the number of rects contained in the region.
\return An int32 which is the total number of rects in the region.
*/
int32 int32
BRegion::CountRects() const BRegion::CountRects() const
{ {
@@ -257,13 +219,7 @@ BRegion::CountRects() const
} }
// #pragma mark - // Check if the region has any area in common with the given BRect.
/*! \brief Check if the region has any area in common with the given BRect.
\param rect The BRect to check the region against to.
\return \ctrue if the region has any area in common with the BRect, \cfalse if not.
*/
bool bool
BRegion::Intersects(BRect rect) const BRegion::Intersects(BRect rect) const
{ {
@@ -271,27 +227,21 @@ BRegion::Intersects(BRect rect) const
} }
/*! \brief Check if the region has any area in common with the given clipping_rect. // Check if the region has any area in common with the given clipping_rect.
\param rect The clipping_rect to check the region against to.
\return \ctrue if the region has any area in common with the clipping_rect, \cfalse if not.
*/
bool bool
BRegion::Intersects(clipping_rect rect) const BRegion::Intersects(clipping_rect clipping) const
{ {
// cheap convert to internal rect format // cheap convert to internal rect format
rect.right ++; clipping.right++;
rect.bottom ++; clipping.bottom++;
int result = Support::XRectInRegion(this, rect); int result = Support::XRectInRegion(this, clipping);
return result > Support::RectangleOut; return result > Support::RectangleOut;
} }
/*! \brief Check if the region contains the given BPoint. // Check if the region contains the given BPoint.
\param pt The BPoint to be checked.
\return \ctrue if the region contains the BPoint, \cfalse if not.
*/
bool bool
BRegion::Contains(BPoint point) const BRegion::Contains(BPoint point) const
{ {
@@ -299,11 +249,7 @@ BRegion::Contains(BPoint point) const
} }
/*! \brief Check if the region contains the given coordinates. // Check if the region contains the given coordinates.
\param x The \cx coordinate of the point to be checked.
\param y The \cy coordinate of the point to be checked.
\return \ctrue if the region contains the point, \cfalse if not.
*/
bool bool
BRegion::Contains(int32 x, int32 y) BRegion::Contains(int32 x, int32 y)
{ {
@@ -311,11 +257,7 @@ BRegion::Contains(int32 x, int32 y)
} }
/*! \brief Check if the region contains the given coordinates. // Check if the region contains the given coordinates.
\param x The \cx coordinate of the point to be checked.
\param y The \cy coordinate of the point to be checked.
\return \ctrue if the region contains the point, \cfalse if not.
*/
bool bool
BRegion::Contains(int32 x, int32 y) const BRegion::Contains(int32 x, int32 y) const
{ {
@@ -323,8 +265,7 @@ BRegion::Contains(int32 x, int32 y) const
} }
/*! \brief Prints the BRegion to stdout. // Prints the BRegion to stdout.
*/
void void
BRegion::PrintToStream() const BRegion::PrintToStream() const
{ {
@@ -339,9 +280,6 @@ BRegion::PrintToStream() const
} }
// #pragma mark -
void void
BRegion::OffsetBy(const BPoint& point) BRegion::OffsetBy(const BPoint& point)
{ {
@@ -349,10 +287,8 @@ BRegion::OffsetBy(const BPoint& point)
} }
/*! \brief Offsets all region's rects, and bounds by the given values. // Applies the given x and y offsets to each rect contained by
\param dh The horizontal offset. // the region and recalculates the region's bounds.
\param dv The vertical offset.
*/
void void
BRegion::OffsetBy(int32 x, int32 y) BRegion::OffsetBy(int32 x, int32 y)
{ {
@@ -370,8 +306,8 @@ BRegion::OffsetBy(int32 x, int32 y)
} }
/*! \brief Empties the region, so that it doesn't include any rect, and invalidates its bounds. // Empties the region, so that it doesn't include any rect, and invalidates
*/ // its bounds.
void void
BRegion::MakeEmpty() BRegion::MakeEmpty()
{ {
@@ -380,12 +316,7 @@ BRegion::MakeEmpty()
} }
// #pragma mark - // Modifies the region, so that it includes the given BRect.
/*! \brief Modifies the region, so that it includes the given BRect.
\param rect The BRect to be included by the region.
*/
void void
BRegion::Include(BRect rect) BRegion::Include(BRect rect)
{ {
@@ -393,32 +324,28 @@ BRegion::Include(BRect rect)
} }
/*! \brief Modifies the region, so that it includes the given clipping_rect. // Modifies the region, so that it includes the given clipping_rect.
\param rect The clipping_rect to be included by the region.
*/
void void
BRegion::Include(clipping_rect rect) BRegion::Include(clipping_rect clipping)
{ {
if (!valid_rect(rect)) if (!valid_rect(clipping))
return; return;
// convert to internal rect format // convert to internal clipping format
rect.right ++; clipping.right++;
rect.bottom ++; clipping.bottom++;
// use private clipping_rect constructor which avoids malloc() // use private clipping_rect constructor which avoids malloc()
BRegion t(rect); BRegion temp(clipping);
BRegion result; BRegion result;
Support::XUnionRegion(this, &t, &result); Support::XUnionRegion(this, &temp, &result);
_AdoptRegionData(result); _AdoptRegionData(result);
} }
/*! \brief Modifies the region, so that it includes the area of the given region. // Modifies the region, so that it includes the area of the given region.
\param region The region to be included.
*/
void void
BRegion::Include(const BRegion* region) BRegion::Include(const BRegion* region)
{ {
@@ -429,9 +356,6 @@ BRegion::Include(const BRegion* region)
} }
// #pragma mark -
/*! \brief Modifies the region, excluding the area represented by the given BRect. /*! \brief Modifies the region, excluding the area represented by the given BRect.
\param rect The BRect to be excluded. \param rect The BRect to be excluded.
*/ */
@@ -442,33 +366,28 @@ BRegion::Exclude(BRect rect)
} }
/*! \brief Modifies the region, excluding the area represented by the given clipping_rect. // Modifies the region, excluding the area represented by the given clipping_rect.
\param rect The clipping_rect to be excluded.
*/
void void
BRegion::Exclude(clipping_rect rect) BRegion::Exclude(clipping_rect clipping)
{ {
if (!valid_rect(rect)) if (!valid_rect(clipping))
return; return;
// convert to internal rect format // convert to internal clipping format
rect.right ++; clipping.right++;
rect.bottom ++; clipping.bottom++;
// use private clipping_rect constructor which avoids malloc() // use private clipping_rect constructor which avoids malloc()
BRegion t(rect); BRegion temp(clipping);
BRegion result; BRegion result;
Support::XSubtractRegion(this, &t, &result); Support::XSubtractRegion(this, &temp, &result);
_AdoptRegionData(result); _AdoptRegionData(result);
} }
/*! \brief Modifies the region, excluding the area contained in the given // Modifies the region, excluding the area contained in the given BRegion.
BRegion.
\param region The BRegion to be excluded.
*/
void void
BRegion::Exclude(const BRegion* region) BRegion::Exclude(const BRegion* region)
{ {
@@ -479,13 +398,8 @@ BRegion::Exclude(const BRegion* region)
} }
// #pragma mark - // Modifies the region, so that it will contain only the area in common
// with the given BRegion.
/*! \brief Modifies the region, so that it will contain just the area
in common with the given BRegion.
\param region the BRegion to intersect with.
*/
void void
BRegion::IntersectWith(const BRegion* region) BRegion::IntersectWith(const BRegion* region)
{ {
@@ -496,13 +410,8 @@ BRegion::IntersectWith(const BRegion* region)
} }
// #pragma mark - // Modifies the region, so that it will contain just the area which both
// regions do not have in common.
/*! \brief Modifies the region, so that it will contain just the area
which both regions do not have in common.
\param region the BRegion to exclusively include.
*/
void void
BRegion::ExclusiveInclude(const BRegion* region) BRegion::ExclusiveInclude(const BRegion* region)
{ {
@@ -513,12 +422,10 @@ BRegion::ExclusiveInclude(const BRegion* region)
} }
// #pragma mark - // #pragma mark - BRegion private methods
/*! \brief Takes over the data of a region and marks that region empty. // Takes over the data of a region and marks that region empty.
\param region The region to adopt the data from.
*/
void void
BRegion::_AdoptRegionData(BRegion& region) BRegion::_AdoptRegionData(BRegion& region)
{ {
@@ -540,15 +447,13 @@ BRegion::_AdoptRegionData(BRegion& region)
} }
/*! \brief Reallocate the memory in the region. // Reallocate the memory in the region.
\param newSize The amount of rectangles that the region should be
able to hold.
*/
bool bool
BRegion::_SetSize(int32 newSize) BRegion::_SetSize(int32 newSize)
{ {
// we never shrink the size // we never shrink the size
newSize = max_c(fDataSize, newSize); newSize = max_c(fDataSize, newSize);
// The amount of rectangles that the region should be able to hold.
if (newSize == fDataSize) if (newSize == fDataSize)
return true; return true;
@@ -611,4 +516,3 @@ BRegion::_ConvertToInternal(const clipping_rect& rect) const
return (clipping_rect){ rect.left, rect.top, return (clipping_rect){ rect.left, rect.top,
rect.right + 1, rect.bottom + 1 }; rect.right + 1, rect.bottom + 1 };
} }