MiniGUI API Reference (MiniGUI-Threads)  v3.2.0
A mature and proven cross-platform GUI system for embedded and smart IoT devices
Data Structures | Macros | Typedefs | Functions
Region operations

Data Structures

struct  _CLIPRECT
 
struct  _CLIPRGN
 

Macros

#define InitFreeClipRectList(heap, size)   InitBlockDataHeap (heap, sizeof (CLIPRECT), size)
 Initializes the private block data heap used to allocate clipping rectangles. More...
 
#define ClipRectAlloc(heap)   BlockDataAlloc (heap)
 Allocates a clipping rectangles from the private block data heap. More...
 
#define FreeClipRect(heap, cr)   BlockDataFree (heap, cr);
 Frees a clipping rectangle which is allocated from the private block data heap. More...
 
#define DestroyFreeClipRectList(heap)   DestroyBlockDataHeap (heap);
 Destroys the private block data heap used to allocate clipping rectangles. More...
 
#define UnionRectWithRegion   AddClipRect
 Is an alias of AddClipRect. More...
 
#define CopyRegion   ClipRgnCopy
 Is an alias of ClipRgnCopy. More...
 
#define IntersectRegion   ClipRgnIntersect
 Is an alias of ClipRgnIntersect. More...
 

Typedefs

typedef struct _CLIPRECT CLIPRECT
 
typedef struct _CLIPRGN CLIPRGN
 
typedef CLIPRGNPCLIPRGN
 Data type of the pointer to a CLIPRGN. More...
 

Functions

MG_EXPORT void GUIAPI InitClipRgn (PCLIPRGN pRgn, PBLOCKHEAP pFreeList)
 Initializes a clipping region. More...
 
MG_EXPORT void GUIAPI EmptyClipRgn (PCLIPRGN pRgn)
 Empties a clipping region. More...
 
MG_EXPORT PCLIPRGN GUIAPI CreateClipRgn (void)
 Creates a clipping region. More...
 
MG_EXPORT void GUIAPI DestroyClipRgn (PCLIPRGN pRgn)
 Empties and destroys a clipping region. More...
 
MG_EXPORT BOOL GUIAPI ClipRgnCopy (PCLIPRGN pDstRgn, const CLIPRGN *pSrcRgn)
 Copies one region to another. More...
 
MG_EXPORT BOOL GUIAPI ClipRgnIntersect (PCLIPRGN pRstRgn, const CLIPRGN *pRgn1, const CLIPRGN *pRgn2)
 Intersects two region. More...
 
MG_EXPORT void GUIAPI GetClipRgnBoundRect (PCLIPRGN pRgn, PRECT pRect)
 Gets the bounding rectangle of a region. More...
 
MG_EXPORT BOOL GUIAPI SetClipRgn (PCLIPRGN pRgn, const RECT *pRect)
 Sets a region to contain only one rect. More...
 
MG_EXPORT BOOL GUIAPI IsEmptyClipRgn (const CLIPRGN *pRgn)
 Determines whether a region is an empty region. More...
 
MG_EXPORT BOOL GUIAPI AddClipRect (PCLIPRGN pRgn, const RECT *pRect)
 Unions one rectangle to a region. More...
 
MG_EXPORT BOOL GUIAPI IntersectClipRect (PCLIPRGN pRgn, const RECT *pRect)
 Intersects a rectangle with a region. More...
 
MG_EXPORT BOOL GUIAPI SubtractClipRect (PCLIPRGN pRgn, const RECT *pRect)
 Subtracts a rectangle from a region. More...
 
MG_EXPORT BOOL GUIAPI PtInRegion (PCLIPRGN region, int x, int y)
 Determines whether a point is in a region. More...
 
MG_EXPORT BOOL GUIAPI RectInRegion (PCLIPRGN region, const RECT *rect)
 Determines whether a rectangle is intersected with a region. More...
 
MG_EXPORT void GUIAPI OffsetRegionEx (PCLIPRGN region, const RECT *rcClient, const RECT *rcScroll, int x, int y)
 Offsets the region in the specified window's scroll area. More...
 
MG_EXPORT void GUIAPI OffsetRegion (PCLIPRGN region, int x, int y)
 Offsets the region. More...
 
MG_EXPORT BOOL GUIAPI UnionRegion (PCLIPRGN dst, const CLIPRGN *src1, const CLIPRGN *src2)
 Unions two regions. More...
 
MG_EXPORT BOOL GUIAPI SubtractRegion (CLIPRGN *rgnD, const CLIPRGN *rgnM, const CLIPRGN *rgnS)
 Substrcts a region from another. More...
 
MG_EXPORT BOOL GUIAPI XorRegion (CLIPRGN *dst, const CLIPRGN *src1, const CLIPRGN *src2)
 Does the XOR operation between two regions. More...
 
MG_EXPORT BOOL GUIAPI InitCircleRegion (PCLIPRGN dst, int x, int y, int r)
 Initializes a region to be an enclosed circle. More...
 
MG_EXPORT BOOL GUIAPI InitEllipseRegion (PCLIPRGN dst, int x, int y, int rx, int ry)
 Initializes a region to be an enclosed ellipse. More...
 
MG_EXPORT BOOL GUIAPI InitPolygonRegion (PCLIPRGN dst, const POINT *pts, int vertices)
 Initializes a region to be an enclosed polygon. More...
 

Detailed Description

A Region is simply an area, as the name implies, and is implemented as a "y-x-banded" array of rectangles. To explain: Each Region is made up of a certain number of rectangles sorted by y coordinate first, and then by x coordinate.

Furthermore, the rectangles are banded such that every rectangle with a given upper-left y coordinate (y1) will have the same lower-right y coordinate (y2) and vice versa. If a rectangle has scanlines in a band, it will span the entire vertical distance of the band. This means that some areas that could be merged into a taller rectangle will be represented as several shorter rectangles to account for shorter rectangles to its left or right but within its "vertical scope".

An added constraint on the rectangles is that they must cover as much horizontal area as possible. E.g. no two rectangles in a band are allowed to touch.

Whenever possible, bands will be merged together to cover a greater vertical distance (and thus reduce the number of rectangles). Two bands can be merged only if the bottom of one touches the top of the other and they have rectangles in the same places (of the same width, of course). This maintains the y-x-banding that's so nice to have...

Example:

#ifdef _USE_NEWGAL
static BLOCKHEAP my_cliprc_heap;
static BOOL ch_inited = FALSE;
static void GDIDemo_Region (HWND hWnd, HDC hdc)
{
CLIPRGN my_cliprgn1;
CLIPRGN my_cliprgn2;
if (!ch_inited) {
/* Init the heap used by our region. */
InitFreeClipRectList (&my_cliprc_heap, 100);
ch_inited = TRUE;
}
InitClipRgn (&my_cliprgn1, &my_cliprc_heap);
InitClipRgn (&my_cliprgn2, &my_cliprc_heap);
/* Create one circle region. */
InitCircleRegion (&my_cliprgn1, 100, 100, 60);
/* Create one ellipse region. */
InitEllipseRegion (&my_cliprgn2, 100, 100, 50, 70);
/* Fill a box to earase the background. */
FillBox (hdc, 0, 0, DEFAULT_WIDTH, 200);
/* Get the difference between two regions. */
SubtractRegion (&my_cliprgn1, &my_cliprgn1, &my_cliprgn2);
/* Select the difference region as the current visible region of DC. */
SelectClipRegion (hdc, &my_cliprgn1);
/* Fill a box, but you will only see red color in the different region. */
FillBox (hdc, 0, 0, 180, 200);
/* Do more with XorRegion. */
InitCircleRegion (&my_cliprgn1, 300, 100, 60);
OffsetRegion (&my_cliprgn2, 200, 0);
XorRegion (&my_cliprgn1, &my_cliprgn1, &my_cliprgn2);
SelectClipRegion (hdc, &my_cliprgn1);
FillBox (hdc, 200, 0, 180, 200);
/* Do more with IntersectRegion. */
InitCircleRegion (&my_cliprgn1, 500, 100, 60);
OffsetRegion (&my_cliprgn2, 200, 0);
IntersectRegion (&my_cliprgn1, &my_cliprgn1, &my_cliprgn2);
SelectClipRegion (hdc, &my_cliprgn1);
FillBox (hdc, 400, 0, 180, 200);
/*
* Empty two clipping region to free the clipping rectangles used
* by them.
*/
EmptyClipRgn (&my_cliprgn1);
EmptyClipRgn (&my_cliprgn2);
/*
* You should not forget to destroy the FreeClipRectList in your
* applications.
* Here we do not destroy the heap because we will use it in next call.
*
* DestroyFreeClipRectList (&my_cliprc_heap);
* ch_inited = FALSE;
*
*/
}
#endif /* _USE_NEWGAL */

Macro Definition Documentation

#define ClipRectAlloc (   heap)    BlockDataAlloc (heap)

Allocates a clipping rectangles from the private block data heap.

Parameters
heapThe pointer to the initialized BLOCKHEAP structure.
Note
This macro is defined to call BlockDataAlloc function.
See also
BlockDataAlloc

Definition at line 660 of file gdi.h.

#define CopyRegion   ClipRgnCopy

Is an alias of ClipRgnCopy.

See also
ClipRgnCopy

Definition at line 1013 of file gdi.h.

#define DestroyFreeClipRectList (   heap)    DestroyBlockDataHeap (heap);

Destroys the private block data heap used to allocate clipping rectangles.

Parameters
heapThe pointer to the BLOCKHEAP structure.
Note
This macro is defined to call DestroyBlockDataHeap function.
See also
DestroyBlockDataHeap

Definition at line 687 of file gdi.h.

#define FreeClipRect (   heap,
  cr 
)    BlockDataFree (heap, cr);

Frees a clipping rectangle which is allocated from the private block data heap.

Parameters
heapThe pointer to the initialized BLOCKHEAP structure.
crThe pointer to the clipping rectangle to be freed.
Note
This macro is defined to call BlockDataFree function.
See also
BlockDataFree

Definition at line 674 of file gdi.h.

#define InitFreeClipRectList (   heap,
  size 
)    InitBlockDataHeap (heap, sizeof (CLIPRECT), size)

Initializes the private block data heap used to allocate clipping rectangles.

Parameters
heapThe pointer to a BLOCKHEAP structure.
sizeThe size of the heap.
Note
This macro is defined to call InitBlockDataHeap function with bd_size set to sizeof(CLIPRECT).
See also
InitBlockDataHeap

Definition at line 647 of file gdi.h.

#define IntersectRegion   ClipRgnIntersect

Is an alias of ClipRgnIntersect.

See also
ClipRgnIntersect

Definition at line 1020 of file gdi.h.

#define UnionRectWithRegion   AddClipRect

Is an alias of AddClipRect.

See also
AddClipRect

Definition at line 1006 of file gdi.h.

Typedef Documentation

typedef struct _CLIPRECT CLIPRECT

Clipping rectangle structure.

typedef struct _CLIPRGN CLIPRGN

Clipping region structure, alos used for general regions.

typedef CLIPRGN * PCLIPRGN

Data type of the pointer to a CLIPRGN.

See also
CLIPRGN

Definition at line 632 of file gdi.h.

Function Documentation

BOOL GUIAPI AddClipRect ( PCLIPRGN  pRgn,
const RECT pRect 
)

Unions one rectangle to a region.

This function unions a rectangle to the region pointed to by pRgn.

Parameters
pRgnThe pointer to the region.
pRectThe pointer to the rectangle.
Returns
TRUE on success, otherwise FALSE.
See also
IntersectClipRect, SubtractClipRect
BOOL GUIAPI ClipRgnCopy ( PCLIPRGN  pDstRgn,
const CLIPRGN pSrcRgn 
)

Copies one region to another.

This function copies the region pointed to by pSrcRgn to the region pointed to by pDstRgn.

Parameters
pDstRgnThe destination region.
pSrcRgnThe source region.
Returns
TRUE on success, otherwise FALSE.
Note
This function will empty the region pDstRgn first.
See also
EmptyClipRgn, ClipRgnIntersect, UnionRegion, SubtractRegion, XorRegion
BOOL GUIAPI ClipRgnIntersect ( PCLIPRGN  pRstRgn,
const CLIPRGN pRgn1,
const CLIPRGN pRgn2 
)

Intersects two region.

This function gets the intersection of two regions pointed to by pRgn1 and pRgn2 respectively and puts the result to the region pointed to by pRstRgn.

Parameters
pRstRgnThe intersected result region.
pRgn1The first region.
pRgn2The second region.
Returns
TRUE on success, otherwise FALSE.
Note
If pRgn1 does not intersected with pRgn2, the result region will be a emgty region.
See also
EmptyClipRgn, ClipRgnCopy, UnionRegion, SubtractRegion, XorRegion
PCLIPRGN GUIAPI CreateClipRgn ( void  )

Creates a clipping region.

Returns
The pointer to the clip region.
See also
InitClipRgn, EmptyClipRgn, DestroyClipRgn.
void GUIAPI DestroyClipRgn ( PCLIPRGN  pRgn)

Empties and destroys a clipping region.

This function empties and destroys a clipping region pointed to by pRgn.

Parameters
pRgnThe pointer to the region.
See also
InitClipRgn, CreateClipRgn
void GUIAPI EmptyClipRgn ( PCLIPRGN  pRgn)

Empties a clipping region.

This function empties a clipping region pointed to by pRgn.

Parameters
pRgnThe pointer to the region.
See also
InitClipRgn
void GUIAPI GetClipRgnBoundRect ( PCLIPRGN  pRgn,
PRECT  pRect 
)

Gets the bounding rectangle of a region.

This function gets the bounding rect of the region pointed to by pRgn, and returns the rect in the rect pointed to by pRect.

Parameters
pRgnThe pointer to the region.
pRectThe pointer to the result rect.
See also
IsEmptyClipRgn
BOOL GUIAPI InitCircleRegion ( PCLIPRGN  dst,
int  x,
int  y,
int  r 
)

Initializes a region to be an enclosed circle.

Parameters
dstThe pointer to the region to be initialized.
xx,y: The center of the circle.
yx,y: The center of the circle.
rThe radius of the circle.
Returns
TRUE on success, otherwise FALSE.
See also
InitEllipseRegion, InitPolygonRegion
void GUIAPI InitClipRgn ( PCLIPRGN  pRgn,
PBLOCKHEAP  pFreeList 
)

Initializes a clipping region.

Before intializing a clipping region, you should initialize a private block data heap first. The region operations, such as UnionRegion function, will allocate/free the clipping rectangles from/to the heap. This function will set the heap field of pRgn to be pFreeList, and empty the region.

Parameters
pRgnThe pointer to the CLIPRGN structure to be initialized.
pFreeListThe pointer to the initialized private block data heap.
See also
InitFreeClipRectList, EmptyClipRgn.

Example:

static BLOCKHEAP sg_MyFreeClipRectList;
...
CLIPRGN my_region
InitFreeClipRectList (&sg_MyFreeClipRectList, 20);
InitClipRgn (&my_regioni, &sg_MyFreeClipRectList);
BOOL GUIAPI InitEllipseRegion ( PCLIPRGN  dst,
int  x,
int  y,
int  rx,
int  ry 
)

Initializes a region to be an enclosed ellipse.

Parameters
dstThe pointer to the region to be initialized.
xx,y: The center of the ellipse.
yx,y: The center of the ellipse.
rxThe x-radius of the ellipse.
ryThe y-radius of the ellipse.
Returns
TRUE on success, otherwise FALSE.
See also
InitCircleRegion, InitPolygonRegion
BOOL GUIAPI InitPolygonRegion ( PCLIPRGN  dst,
const POINT pts,
int  vertices 
)

Initializes a region to be an enclosed polygon.

Parameters
dstThe pointer to the region to be initialized.
ptsThe vertex array of the polygon.
verticesThe number of the vertices.
Returns
TRUE on success, otherwise FALSE.
See also
InitCircleRegion, InitEllipseRegion
BOOL GUIAPI IntersectClipRect ( PCLIPRGN  pRgn,
const RECT pRect 
)

Intersects a rectangle with a region.

This function intersects the region pointed to by pRgn with a rect pointed to by pRect.

Parameters
pRgnThe pointer to the region.
pRectThe pointer to the rectangle.
Returns
TRUE on success, otherwise FALSE.
See also
AddClipRect, SubtractClipRect
BOOL GUIAPI IsEmptyClipRgn ( const CLIPRGN pRgn)

Determines whether a region is an empty region.

This function determines whether the region pointed to by pRgn is an empty region.

Parameters
pRgnThe pointer to the region.
Returns
TRUE for empty one, else for not empty region.
See also
EmptyClipRgn
void GUIAPI OffsetRegion ( PCLIPRGN  region,
int  x,
int  y 
)

Offsets the region.

This function offsets a given region pointed to by region.

Parameters
regionThe pointer to the region.
xx,y: Offsets on x and y coodinates.
yx,y: Offsets on x and y coodinates.
void GUIAPI OffsetRegionEx ( PCLIPRGN  region,
const RECT rcClient,
const RECT rcScroll,
int  x,
int  y 
)

Offsets the region in the specified window's scroll area.

This function offsets a given region pointed to by region in the specified window's scroll area.

Parameters
regionThe pointer to the region.
rcClientThe client area which the region belongs to.
rcScrollThe rectangle of the area in which the region will be offset.
xx,y: Offsets on x and y coodinates.
yx,y: Offsets on x and y coodinates.
BOOL GUIAPI PtInRegion ( PCLIPRGN  region,
int  x,
int  y 
)

Determines whether a point is in a region.

This function determines whether a point (x,y) is in the region pointed to by region.

Parameters
regionThe pointer to the region.
xx,y: The point.
yx,y: The point.
Returns
TRUE for in the region, otherwise FALSE.
See also
RectInRegion
BOOL GUIAPI RectInRegion ( PCLIPRGN  region,
const RECT rect 
)

Determines whether a rectangle is intersected with a region.

This function determines whether the rect rect is intersected with the region pointed to by region.

Parameters
regionThe pointer to the region.
rectThe pointer to the rect.
Returns
TRUE for in the region, otherwise FALSE.
See also
PtInRegion
BOOL GUIAPI SetClipRgn ( PCLIPRGN  pRgn,
const RECT pRect 
)

Sets a region to contain only one rect.

This function sets the region pRgn to contain only a rect pointed to by pRect.

Parameters
pRgnThe pointer to the region.
pRectThe pointer to the rect.
Returns
TRUE on success, otherwise FALSE.
Note
This function will empty the region pRgn first.
See also
EmptyClipRgn
BOOL GUIAPI SubtractClipRect ( PCLIPRGN  pRgn,
const RECT pRect 
)

Subtracts a rectangle from a region.

This function subtracts a rect pointed to by pRect from the region pointed to by pRgn.

Parameters
pRgnThe pointer to the region.
pRectThe pointer to the rect.
Returns
TRUE on success, otherwise FALSE.
See also
AddClipRect, IntersectClipRect
BOOL GUIAPI SubtractRegion ( CLIPRGN rgnD,
const CLIPRGN rgnM,
const CLIPRGN rgnS 
)

Substrcts a region from another.

This function subtracts rgnS from rgnM and leave the result in rgnD.

Parameters
rgnDThe pointer to the difference region.
rgnMThe pointer to the minuend region.
rgnSThe pointer to the subtrahend region.
Returns
TRUE on success, otherwise FALSE.
See also
UnionRegion, XorRegion
BOOL GUIAPI UnionRegion ( PCLIPRGN  dst,
const CLIPRGN src1,
const CLIPRGN src2 
)

Unions two regions.

This function unions two regions pointed to by src1 and src2 respectively and puts the result to the region pointed to by dst.

Parameters
dstThe pointer to the result region.
src1src1,src2: Two regions will be unioned.
src2src1,src2: Two regions will be unioned.
Returns
TRUE on success, otherwise FALSE.
See also
SubtractRegion, XorRegion
BOOL GUIAPI XorRegion ( CLIPRGN dst,
const CLIPRGN src1,
const CLIPRGN src2 
)

Does the XOR operation between two regions.

This function does the XOR operation between two regions pointed to by src1 and src2 and puts the result to the region pointed to by dst.

Parameters
dstThe pointer to the result region.
src1src1,src2: Two regions will be xor'ed.
src2src1,src2: Two regions will be xor'ed.
Returns
TRUE on success, otherwise FALSE.
See also
UnionRegion, SubtractRegion