Class TRegion

class TRegion;

Description

Clipping region - abstract base class.

This abstract base class represents a 2-dimensional area which is used by Graphics, the graphics window server, and the text window server to define regions of the display which need to be updated, or regions within which all operations must occur.

A TRegion is defined in terms of an array of TRects and the more complex the region, the more TRects are required to represent it.

A clipping region initially has space allocated for five rectangles. If manipulations result in a region which requires more than this, an attempt is made to allocate more rectangles. If this cannot be done, an error flag is set, and all subsequent operations involving the region have no effect (except possibly to propagate the error flag to other regions). The TRegion::CheckError()const member function allows the error flag to be tested; TRegion::Clear() can be used to clear it.

The redraw logic of application programs may use the TRegion in various ways:

1. minimally, they pass it to the graphics context as the clipping region; when a graphics context is activated to a window, the clipping region is set up automatically

2. if they wish to avoid redrawing objects which are outside the general area of the region, they may use TRegion::BoundingRect()const to return the rectangle which bounds the clipping region, and draw only primitives that lie within that rectangle

3. if they wish to exercise finer control, they may extract the individual rectangles that comprise the clipping region using Operator[]().

Application programs may also manipulate clipping regions in order to constrain parts of their redrawing to narrower areas of the screen than the clipping region offered by the window server. To do this, functions that allow clipping region manipulation may be used; for example, adding or removing rectangles or finding the intersection or union of two regions.

Members

Defined in TRegion:

• AddRect(const TRect &)Adds a rectangle to this region.
• BoundingRect()constGets the minimal rectangle that bounds the entire region.
• CheckError()constTests whether the region's error flag is set.
• Clear()Clears this region.
• ClipRect(const TRect &)Clips the region to the specified rectangle.
• Contains(const TPoint &)constTests whether a point is located within the region.
• Copy(const TRegion &)Copies another region to this region.
• Count()constGets the number of rectangles in this region.
• ERRegionBuf
• ForceError()Sets the error flag, and clears the region.
• Intersect(const TRegion &)Replaces this region with the area of intersection between it and the specified ...
• Intersection(const TRegion &,const TRegion &)Replaces this region with the area of intersection between two specified regions...
• Intersects(const TRect &)constTests whether where there is any intersection between this region and the specif...
• IsContainedBy(const TRect &)constTests whether the region is fully enclosed within the specified rectangle.
• IsEmpty()constTests whether the region is empty.
• Offset(TInt,TInt)Moves the region by adding X and Y offsets to the co-ordinates of its corners.
• Offset(const TPoint &)Moves the region by adding a TPoint offset to the co-ordinates of its corners.
• RectangleList()constGets a pointer to the array of rectangles defining this region.
• RectangleListW()
• Sort()Sorts the region's array of rectangles according to their vertical position on t...
• Sort(const TPoint &)Sorts the region's array of rectangles according to a specified sort order.
• SubRect(const TRect &,TRegion *)Removes a rectangle from this region.
• SubRegion(const TRegion &,TRegion *)Removes a region.
• TRegion()
• TRegion(TInt)
• Tidy()Merges all rectangles within this region which share an adjacent edge of the sam...
• Union(const TRegion &)Replaces this region with the union of it and the specified region.
• anonymous
• iAllocedRects
• iCount
• iError
• operator[](TInt)constGets a rectangle from the region.

protected: IMPORT_C TRegion(TInt aAllocedRects);

Description

Parameters

protected: inline TRegion();

Description

inline TInt Count() const;

Description

Gets the number of rectangles in this region.

Return value

inline const TRect* RectangleList() const;

Description

Gets a pointer to the array of rectangles defining this region.

Return value

See also:

• TRegion::Count()constGets the number of rectangles in this region.

inline TBool CheckError() const;

Description

Tests whether the region's error flag is set.

The error flag may be set:

1. when an attempt to allocate more memory for the region fails

2. if an attempt is made to expand a fixed size region beyond its allocated size

3. if TRegion::ForceError() has been called.

Use TRegion::Clear() to unset the error flag, clear the region and free all allocated memory.

Return value

See also:

• TRegion::ForceError()Sets the error flag, and clears the region.
• TRegion::Clear()Clears this region.

IMPORT_C TBool IsEmpty() const;

Description

Tests whether the region is empty.

Return value

IMPORT_C TRect BoundingRect() const;

Description

Gets the minimal rectangle that bounds the entire region.

Return value

IMPORT_C const TRect& operator[](TInt aIndex) const;

Description

Gets a rectangle from the region.

Parameters

Return value

Panic codes

IMPORT_C void Copy(const TRegion &aRegion);

Description

Copies another region to this region.

The state of the specified region's error flag is also copied.

Parameters

IMPORT_C void AddRect(const TRect &aRect);

Description

Adds a rectangle to this region.

Notes:

1. If this region's error flag is already set, this function has no effect.

2. If the operation causes the capacity of this region to be exceeded, or if memory allocation fails, the region is cleared, freeing up any memory which has been allocated; its error flag is also set.

Parameters

IMPORT_C void SubRect(const TRect &aRect, TRegion *aSubtractedRegion=0);

Description

Removes a rectangle from this region.

If there is no intersection between the rectangle and this region, then this region is unaffected.

Parameters

IMPORT_C void Offset(TInt aXoffset, TInt aYoffset);

Description

Moves the region by adding X and Y offsets to the co-ordinates of its corners.

The size of the region is not changed.

Parameters

IMPORT_C void Offset(const TPoint &aOffset);

Description

Moves the region by adding a TPoint offset to the co-ordinates of its corners.

The size of the region is not changed.

Parameters

IMPORT_C void Union(const TRegion &aRegion);

Description

Replaces this region with the union of it and the specified region.

Note that if the error flag of either this region or the specified region is set, then this region is cleared and its error flag is set. This frees up allocated memory.

Parameters

IMPORT_C void Intersection(const TRegion &aRegion, const TRegion &aRegion2);

Description

Replaces this region with the area of intersection between two specified regions.

Notes:

1. If the error flag of either of the two specified regions is set, then this region is cleared and its error flag is set. This frees up allocated memory.

2. If this region's error flag is already set, then the function has no effect.

Parameters

IMPORT_C void Intersect(const TRegion &aRegion);

Description

Replaces this region with the area of intersection between it and the specified region.

Note that if the error flag of either this region or the specified region is set, then this region is cleared and its error flag is set. This frees up allocated memory.

Parameters

IMPORT_C void SubRegion(const TRegion &aRegion, TRegion *aSubtractedRegion=0);

Description

Removes a region.

If there is no area of intersection between the two regions, this region is unaffected.

Parameters

IMPORT_C void ClipRect(const TRect &aRect);

Description

Clips the region to the specified rectangle.

The resulting region is the area of overlap between the region and the rectangle. If there is no overlap, all rectangles within this region are deleted and the resulting region is empty.

Parameters

IMPORT_C void Clear();

Description

Clears this region.

This frees up any memory which has been allocated and unsets the error flag.

IMPORT_C void Tidy();

Description

Merges all rectangles within this region which share an adjacent edge of the same length.

The function subsequently frees up any allocated but unused memory.

IMPORT_C TInt Sort();

Description

Sorts the region's array of rectangles according to their vertical position on the screen.

The sort uses the bottom right hand corner co-ordinates of the rectangles. The co-ordinates of the top and left hand sides are irrelevant to the sort operation.

Higher rectangles take precedence over lower ones. For rectangles at the same vertical position, the leftmost takes priority.

Note that the sort order may need to be different from the default if, for example, a region is moved downwards so that lower non-overlapping rectangles need to be redrawn (and sorted) before higher ones. In this case, use the second overload of this function.

Return value

IMPORT_C TInt Sort(const TPoint &aOffset);

Description

Sorts the region's array of rectangles according to a specified sort order.

The sort uses the bottom right hand co-ordinates of the rectangles. The co-ordinates of the top and left hand sides are irrelevant to the sort operation

The order of the sort is determined by whether the iX and iY members of aOffset are positive, or zero or less. If aOffset.iY is greater than zero, lower rectangles take precedence over higher rectangles in the list order. Otherwise, higher rectangles take precedence. For rectangles of equal height, aOffset.iX becomes relevant to the sort. If is greater than zero, rightmost rectangles take precedence. Otherwise, leftmost rectangles take precedence.

Note that the sort order may need to be different from the default if, for example, a region is moved downwards so that lower non-overlapping rectangles need to be redrawn (and sorted) before higher ones.

Parameters

Return value

IMPORT_C void ForceError();

Description

Sets the error flag, and clears the region.

This frees up memory allocated to the region.

IMPORT_C TBool IsContainedBy(const TRect &aRect) const;

Description

Tests whether the region is fully enclosed within the specified rectangle.

Parameters

Return value

IMPORT_C TBool Contains(const TPoint &aPoint) const;

Description

Tests whether a point is located within the region.

If the point is located on the top or left hand side of any rectangle in the region, it is considered to be within that rectangle and within the region.

If the point is located on the right hand side or bottom of a rectangle, it is considered to be outside that rectangle, and may be outside the region.

Parameters

Return value

IMPORT_C TBool Intersects(const TRect &aRect) const;

Description

Tests whether where there is any intersection between this region and the specified rectangle.

Parameters

Return value

protected: IMPORT_C TRect* RectangleListW();

Description

Return value

protected: n/a

Description

protected: TInt iCount;

Description

protected: TBool iError;

Description

protected: TInt iAllocedRects;

Description