CompRegion
Out of all of the classes describing 2D geometry, a CompRegion is probably the most complex description, but also the most versatile. Unlike CompRect, a CompRegion can describe a multi-vertex geometry. However because of this, it's dimensions cannot be directly manipulated since the number of vertexes is relatively unknown. To handle this problem, each CompRegion has a vector of CompRect's, which are a number of rectangles inside the region, which each describe an area within the region. Like CompRect, CompRegion is also a wrapper around an X11 Region, but this time allows for more region based operations.
Class Definition
/**
* A 2D region with an (x,y) position and arbitrary dimensions similar to
* an XRegion. It's data membmers are private and must be manipulated with
* set() methods.
*/
class CompRegion {
public:
typedef std::vector<CompRegion> List;
typedef std::vector<CompRegion *> PtrList;
typedef std::vector<CompRegion> Vector;
typedef std::vector<CompRegion *> PtrVector;
public:
CompRegion ();
CompRegion (const CompRegion &);
CompRegion (int x, int y, int w, int h);
CompRegion (const CompRect &);
CompRegion (const CompPoint::vector &); // Abstract Shape
~CompRegion ();
/**
* Returns a CompRect which encapsulates a given CompRegion
*/
CompRect boundingRect () const;
bool isEmpty () const;
/**
* Returns the number of XRectangles in the XRegion handle
*/
int numRects () const;
/**
* Returns a vector of all the XRectangles in the XRegion handle
*/
CompRect::vector rects () const;
/**
* Returns the internal XRegion handle
*/
const Region handle () const;
/**
* Returns true if the specified CompPoint falls within the
* CompRegion
*/
bool contains (const CompPoint &) const;
/**
* Returns true if the specified CompRect falls within the
* CompRegion
*/
bool contains (const CompRect &) const;
/**
* Returns true if the specified size falls withing the
* CompRegion
*/
bool contains (int x, int y, int width, int height) const;
/**
* Returns a CompRegion that is the result of an intersect with
* the specified CompRegion and the region
*/
CompRegion intersected (const CompRegion &) const;
/**
* Returns a CompRegion that is the result of an intersect with
* the specified CompRect and the region
*/
CompRegion intersected (const CompRect &) const;
/**
* Returns true if a specified CompRegion intersects a region
*/
bool intersects (const CompRegion &) const;
/**
* Returns true if a specified CompRect intersects a region
*/
bool intersects (const CompRect &) const;
/**
* Returns a CompRegion covering the area of the region
* and not including the area of the specified CompRegion
*/
CompRegion subtracted (const CompRegion &) const;
/**
* Returns a CompRegion covering the area of the region
* and not including the area of the specified CompRect
*/
CompRegion subtracted (const CompRect &) const;
/**
* Moves a region by x and y amount
*/
void translate (int dx, int dy);
/**
* Moves a region by an amount specified by the co-ordinates of a
* CompPoint
*/
void translate (const CompPoint &);
/**
* Returns a CompRegion which is the result of the region being moved
* by dx and dy amount
*/
CompRegion translated (int, int) const;
/**
* Returns a CompRegion which is the result of the region being moved
* by an amount specified by the co-ordinates of a CompPoint
*/
CompRegion translated (const CompPoint &) const;
void shrink (int, int);
void shrink (const CompPoint &);
CompRegion shrinked (int, int) const;
CompRegion shrinked (const CompPoint &) const;
/**
* Returns a CompRegion which is the result of the region joined
* with a specified CompRegion
*/
CompRegion united (const CompRegion &) const;
/**
* Returns a CompRegion which is the result of the region joined
* with a specified CompRect
*/
CompRegion united (const CompRect &) const;
/**
* Returns a CompRegion which is the result of the region joined
* with a specified CompRegion, excluding the area in which
* both regions intersect
*/
CompRegion xored (const CompRegion &) const;
bool operator== (const CompRegion &) const;
bool operator!= (const CompRegion &) const;
const CompRegion operator& (const CompRegion &) const;
const CompRegion operator& (const CompRect &) const;
CompRegion & operator&= (const CompRegion &);
CompRegion & operator&= (const CompRect &);
const CompRegion operator+ (const CompRegion &) const;
const CompRegion operator+ (const CompRect &) const;
CompRegion & operator+= (const CompRegion &);
CompRegion & operator+= (const CompRect &);
const CompRegion operator- (const CompRegion &) const;
const CompRegion operator- (const CompRect &) const;
CompRegion & operator-= (const CompRegion &);
CompRegion & operator-= (const CompRect &);
CompRegion & operator= (const CompRegion &);
const CompRegion operator^ (const CompRegion &) const;
CompRegion & operator^= (const CompRegion &);
const CompRegion operator| (const CompRegion &) const;
CompRegion & operator|= (const CompRegion &);
private:
PrivateRegion *priv;
};
Setting the geometry
The geometry of a CompRegion can only be set once, and this is on it's constructor. The most common geometry to set to be some sort of rectangle by taking a CompRect or rectangle dimentions. However, since a CompRegion can represent any area, it can also take a CompPoint::vector which describes the geometry. After the constructor, the geometry can no longer be set directly.
Getting the geometry
If you only wish to know basic information about the rect, such as it's width, height, and position, then you can use the ::boundingBox () method, which returns a CompRect with that information. However, considering that a CompRegion can represent any area, this information can be inaccurate. In this case, you might want to consider using the ::rects () method, which returns a vector of CompRect's, each describing some area within the region. For example, the Blur plugin uses this information to do specific non-rectangular areas of blurring.
Union
Regions can be united, that is both areas combined to represent the combined are of both of them. To do this, you can use the following methods:
::united (const CompRegion &); - which takes a CompRegion or a CompRect and returns the result of both regions joined
::operator+ (const CompRegion &lhs, const CompRegion &rhs); which returns the union of the regions or region and rect in the right and left hand sides.
::operator+= (const CompRegion &); which united the current region with the region on the right hand side.
Intersection
Regions can also be intersected, where the area shared by both can be found. This is done using the following methods:
::intersected (const CompRegion &); which returns the area of intersection between the two regions or rects.
::intersects (const CompRegion &); which returns true if the two regions intersect.
::operator& (const CompRegion &lhs, const CompRegion &rhs); which returns the intersection between the regions on the left and right hand sides.
::operator&= (const CompRegion &); which makes the CompRegion take on the area shared only by the region and the region on the right hand side.
Subtraction
Regions can also be subtracted from each other, where the entire overlapping area of one region is removed from another, using the following methods:
::subtracted (const CompRegion &); which returns a CompRegion which contains all of the area of the first CompRegion without any area covered by the second CompRegion
::operator- which returns a CompRegion which contains all of the area of the CompRegion on the left hand side without any area covered by the CompRegion on the right
::operator-= which takes away all the area from the CompRegion on the left hand side that was covered by the right.
X-OR Operations
Regions can also be Xored , which unites the two, and does not cover any region where the two overlap. This means that if there were two regions that did overlap, the new region would represent the uniting of the two, but with a gap where the two overlapped.
::xored (const CompRegion &);
::operator^ (const CompRegion &lhs, const CompRegion &rhs);
::operator^= (const CompRegion &);
Operating directly with an X Region
The internal X11 Region belonging to a CompRegion cannot be directly manipulated - however you can obtain a const Region & by making a call to ::handle (). This can be used directly for drawing by your plugin.
Development/zero-nine/CoreClasses/CompRegion (last edited 2010-07-27 03:41:28 by 124-169-107-122)