Clipping region - abstract base class. More...

#include <e32std.h>

Inheritance diagram for TRegion:

Public Member Functions
TInt	Count () const
	Gets the number of rectangles in this region.

const TRect *	RectangleList () const
	Gets a pointer to the array of rectangles defining this region.

TBool	CheckError () const
	Tests whether the region's error flag is set.

IMPORT_C TBool	IsEmpty () const
	Tests whether the region is empty.

IMPORT_C TRect	BoundingRect () const
	Gets the minimal rectangle that bounds the entire region.

IMPORT_C const TRect &	operator[] (TInt aIndex) const
	Gets a rectangle from the region.

IMPORT_C void	Copy (const TRegion &aRegion)
	Copies another region to this region.

IMPORT_C void	AddRect (const TRect &aRect)
	Adds a rectangle to this region.

IMPORT_C void	SubRect (const TRect &aRect, TRegion *aSubtractedRegion=NULL)
	Removes a rectangle from this region.

IMPORT_C void	Offset (TInt aXoffset, TInt aYoffset)
	Moves the region by adding X and Y offsets to the co-ordinates of its corners.

IMPORT_C void	Offset (const TPoint &aOffset)
	Moves the region by adding a TPoint offset to the co-ordinates of its corners.

IMPORT_C void	Union (const TRegion &aRegion)
	Replaces this region with the union of it and the specified region.

IMPORT_C void	Intersection (const TRegion &aRegion, const TRegion &aRegion2)
	Replaces this region with the area of intersection between two specified regions.

IMPORT_C void	Intersect (const TRegion &aRegion)
	Replaces this region with the area of intersection between it and the specified region.

IMPORT_C void	SubRegion (const TRegion &aRegion, TRegion *aSubtractedRegion=NULL)
	Removes a region.

IMPORT_C void	ClipRect (const TRect &aRect)
	Clips the region to the specified rectangle.

IMPORT_C void	Clear ()
	Clears this region.

IMPORT_C void	Tidy ()
	Merges all rectangles within this region which share an adjacent edge of the same length.

IMPORT_C TInt	Sort ()
	Sorts the region's array of rectangles according to their vertical position on the screen.

IMPORT_C TInt	Sort (const TPoint &aOffset)
	Sorts the region's array of rectangles according to a specified sort order.

IMPORT_C void	ForceError ()
	Sets the error flag, and clears the region.

IMPORT_C TBool	IsContainedBy (const TRect &aRect) const
	Tests whether the region is fully enclosed within the specified rectangle.

IMPORT_C TBool	Contains (const TPoint &aPoint) const
	Tests whether a point is located within the region.

IMPORT_C TBool	Intersects (const TRect &aRect) const
	Tests whether where there is any intersection between this region and the specified rectangle.

Protected Types
enum	{ ERRegionBuf =0x40000000 }

Protected Member Functions
IMPORT_C TRect *	RectangleListW ()

IMPORT_C	TRegion (TInt aAllocedRects)

	TRegion ()

TBool	SetListSize (TInt aCount)
	Ensure that the region is big enough to hold aCount rectangles.

void	AppendRect (const TRect &aRect)

void	DeleteRect (TRect *aRect)

void	AppendRegion (TRegion &aRegion)

void	MergeRect (const TRect &aRect, TBool aEnclosed)
	Merges a rectangle with this region.

void	SubtractRegion (const TRegion &aRegion, TRegion *aSubtractedRegion=NULL)
	Removes a region.

void	ShrinkRegion ()
	After an RRegion's iCount has reduced try to release some memory.

TRect *	ExpandRegion (TInt aCount)
	Ensure that the region is big enough to hold aCount rectangles.

Protected Attributes
TInt	iCount

TBool	iError

TInt	iAllocedRects

Detailed 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 CheckError() member function allows the error flag to be tested; Clear() can be used to clear it.

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

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
if they wish to avoid redrawing objects which are outside the general area of the region, they may use TRegion::BoundingRect() to return the rectangle which bounds the clipping region, and draw only primitives that lie within that rectangle
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.

API status: Published to all clients. Released API.

Definition at line 2773 of file e32std.h.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

protected

Enumerator
ERRegionBuf

Definition at line 2817 of file e32std.h.

Constructor & Destructor Documentation

◆ TRegion() [1/2]

IMPORT_C TRegion::TRegion ( TInt aAllocedRects )

protected

◆ TRegion() [2/2]

TRegion::TRegion ( )

inlineprotected

Member Function Documentation

◆ AddRect()

IMPORT_C void TRegion::AddRect ( const TRect & aRect )

Adds a rectangle to this region.

Notes:

If this region's error flag is already set, this function has no effect.
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

aRect The rectangle to be added to this region.

(generated from Symbian Developer Library)

◆ AppendRect()

void TRegion::AppendRect ( const TRect & aRect )

protected

◆ AppendRegion()

void TRegion::AppendRegion ( TRegion & aRegion )

protected

◆ BoundingRect()

IMPORT_C TRect TRegion::BoundingRect ( ) const

Gets the minimal rectangle that bounds the entire region.

(generated from Symbian Developer Library)

◆ CheckError()

TBool TRegion::CheckError ( ) const

inline

Tests whether the region's error flag is set.

The error flag may be set:

when an attempt to allocate more memory for the region fails
if an attempt is made to expand a fixed size region beyond its allocated size
if ForceError() has been called.

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

TRegion::ForceError TRegion::Clear

(generated from Symbian Developer Library)

◆ Clear()

IMPORT_C void TRegion::Clear ( )

Clears this region.

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

(generated from Symbian Developer Library)

◆ ClipRect()

IMPORT_C void TRegion::ClipRect ( const TRect & aRect )

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

aRect The rectangle to which this region is to be clipped.

(generated from Symbian Developer Library)

◆ Contains()

IMPORT_C TBool TRegion::Contains ( const TPoint & aPoint ) const

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

aPoint The specified point.

(generated from Symbian Developer Library)

◆ Copy()

IMPORT_C void TRegion::Copy ( const TRegion & aRegion )

Copies another region to this region.

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

Parameters

aRegion The region to be copied.

(generated from Symbian Developer Library)

◆ Count()

TInt TRegion::Count ( ) const

inline

Gets the number of rectangles in this region.

(generated from Symbian Developer Library)

◆ DeleteRect()

void TRegion::DeleteRect ( TRect * aRect )

protected

◆ ExpandRegion()

TRect * TRegion::ExpandRegion ( TInt aCount )

protected

Ensure that the region is big enough to hold aCount rectangles.

Any allocation increase is for at least the granularity count of rectangles. Similar to SetListSize, but always preserves existing iCount rectangles.

Parameters

aCount number of rectangles the region is expected to hold

(generated from Symbian Developer Library)

◆ ForceError()

IMPORT_C void TRegion::ForceError ( )

Sets the error flag, and clears the region.

This frees up memory allocated to the region.

(generated from Symbian Developer Library)

◆ Intersect()

IMPORT_C void TRegion::Intersect ( const TRegion & aRegion )

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

aRegion The region to be intersected with this region.

(generated from Symbian Developer Library)

◆ Intersection()

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

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

Notes:

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.
If this region's error flag is already set, then the function has no effect.

Parameters

aRegion	The first region.
aRegion2	The second region.

(generated from Symbian Developer Library)

◆ Intersects()

IMPORT_C TBool TRegion::Intersects ( const TRect & aRect ) const

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

Parameters

aRect The specified rectangle.

(generated from Symbian Developer Library)

◆ IsContainedBy()

IMPORT_C TBool TRegion::IsContainedBy ( const TRect & aRect ) const

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

Parameters

aRect The specified rectangle.

(generated from Symbian Developer Library)

◆ IsEmpty()

IMPORT_C TBool TRegion::IsEmpty ( ) const

Tests whether the region is empty.

(generated from Symbian Developer Library)

◆ MergeRect()

void TRegion::MergeRect	(	const TRect &	aRect,
		TBool	aEnclosed
	)

protected

Merges a rectangle with this region.

If requested it looks for a rectangle in the region that covers the new rectangle, if found method returns immediately. Otherwise, or if an enclosing rectangle is not found, the new aRect is subtracted from all intersecting rectangles, and then aRect is appended to the region.

Parameters

aRect	The rectangular area to be added to this region.
aEnclosed	Whether to look for a rectangle in the region that covers the new aRect.

(generated from Symbian Developer Library)

◆ Offset() [1/2]

IMPORT_C void TRegion::Offset ( const TPoint & aOffset )

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

The size of the region is not changed.

Parameters

aOffset The offset by which the region is moved. The region is moved horizontally by aOffset.iX pixels and vertically by aOffset.iY pixels.

(generated from Symbian Developer Library)

◆ Offset() [2/2]

IMPORT_C void TRegion::Offset	(	TInt	aXoffset,
		TInt	aYoffset
	)

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

aXoffset	The number of pixels by which to move the region horizontally. If negative, the region moves leftwards.
aYoffset	The number of pixels by which to move the region vertically. If negative, the region moves upwards.

(generated from Symbian Developer Library)

◆ operator[]()

IMPORT_C const TRect & TRegion::operator[] ( TInt aIndex ) const

Gets a rectangle from the region.

Parameters

aIndex The index of a rectangle within the region's array of rectangles. Indexes are relative to zero.

Panic condition: USER 81, if aIndex is greater than or equal to the number of rectangles in the region.

(generated from Symbian Developer Library)

◆ RectangleList()

const TRect * TRegion::RectangleList ( ) const

inline

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

TRegion::Count

(generated from Symbian Developer Library)

◆ RectangleListW()

IMPORT_C TRect * TRegion::RectangleListW ( )

protected

◆ SetListSize()

TBool TRegion::SetListSize ( TInt aCount )

protected

Ensure that the region is big enough to hold aCount rectangles.

Parameters

aCount number of rectangles the region is expected to hold

(generated from Symbian Developer Library)

◆ ShrinkRegion()

void TRegion::ShrinkRegion ( )

protected

After an RRegion's iCount has reduced try to release some memory.

Hysteresis rule: reduce allocated memory to iCount, but only if the released memory will also be at least the granularity.

(generated from Symbian Developer Library)

◆ Sort() [1/2]

IMPORT_C TInt TRegion::Sort ( )

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.

(generated from Symbian Developer Library)

◆ Sort() [2/2]

IMPORT_C TInt TRegion::Sort ( const TPoint & aOffset )

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

aOffset A point whose iX and iY members determine the order of the sort.

(generated from Symbian Developer Library)

◆ SubRect()

IMPORT_C void TRegion::SubRect	(	const TRect &	aRect,
		TRegion *	aSubtractedRegion = `NULL`
	)

Removes a rectangle from this region.

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

Parameters

aRect	The rectangular area to be removed from this region.
aSubtractedRegion	A pointer to a region. If this is supplied, the removed rectangle is added to it. By default this pointer is NULL.

(generated from Symbian Developer Library)

◆ SubRegion()

IMPORT_C void TRegion::SubRegion	(	const TRegion &	aRegion,
		TRegion *	aSubtractedRegion = `NULL`
	)

Removes a region.

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

Parameters

aRegion	The region to be removed from this region. If aRegion's error flag is set, then this region is cleared, freeing up any allocated memory, and the error flag is set.
aSubtractedRegion	If specified, then on return contains the area removed from this region.

(generated from Symbian Developer Library)

◆ SubtractRegion()

void TRegion::SubtractRegion	(	const TRegion &	aRegion,
		TRegion *	aSubtractedRegion = `NULL`
	)

protected

Removes a region.

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

Parameters

aRegion	The region to be removed from this region. If aRegion's error flag is set, then this region is cleared, freeing up any allocated memory, and the error flag is set.
aSubtractedRegion	If specified, then on return contains the area removed from this region.

(generated from Symbian Developer Library)

◆ Tidy()

IMPORT_C void TRegion::Tidy ( )

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

The function subsequently checks for allocated but unused memory, if this memory is at least as large as the granularity it is released to the system.

(generated from Symbian Developer Library)

◆ Union()

IMPORT_C void TRegion::Union ( const TRegion & aRegion )

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

aRegion The region to be joined to this region.

(generated from Symbian Developer Library)

Member Data Documentation

◆ iAllocedRects

TInt TRegion::iAllocedRects

protected

Definition at line 2815 of file e32std.h.

◆ iCount

TInt TRegion::iCount

protected

Definition at line 2813 of file e32std.h.

◆ iError

TBool TRegion::iError

protected

Definition at line 2814 of file e32std.h.

The documentation for this class was generated from the following files:

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ anonymous enum

Constructor & Destructor Documentation

◆ TRegion() [1/2]

◆ TRegion() [2/2]

Member Function Documentation

◆ AddRect()

◆ AppendRect()

◆ AppendRegion()

◆ BoundingRect()

◆ CheckError()

◆ Clear()

◆ ClipRect()

◆ Contains()

◆ Copy()

◆ Count()

◆ DeleteRect()

◆ ExpandRegion()

◆ ForceError()

◆ Intersect()

◆ Intersection()

◆ Intersects()

◆ IsContainedBy()

◆ IsEmpty()

◆ MergeRect()

◆ Offset() [1/2]

◆ Offset() [2/2]

◆ operator[]()

◆ RectangleList()

◆ RectangleListW()

◆ SetListSize()

◆ ShrinkRegion()

◆ Sort() [1/2]

◆ Sort() [2/2]

◆ SubRect()

◆ SubRegion()

◆ SubtractRegion()

◆ Tidy()

◆ Union()

Member Data Documentation

◆ iAllocedRects

◆ iCount

◆ iError