Clipping operations

Functions
MG_EXPORT void GUIAPI	ExcludeClipRect (HDC hdc, const RECT *prc)
	Excludes the specified rectangle from the current visible region of a DC. More...
MG_EXPORT void GUIAPI	IncludeClipRect (HDC hdc, const RECT *prc)
	Includes the specified rectangle to the current visible region of a DC. More...
MG_EXPORT BOOL GUIAPI	PtVisible (HDC hdc, int x, int y)
	Checks whether a point is visible. More...
MG_EXPORT void GUIAPI	ClipRectIntersect (HDC hdc, const RECT *prc)
	Intersects the specified rectangle with the visible region of the DC. More...
MG_EXPORT void GUIAPI	SelectClipRect (HDC hdc, const RECT *prc)
	Sets the visible region of a DC to be a rectangle. More...
MG_EXPORT int GUIAPI	SelectClipRegionEx (HDC hdc, const CLIPRGN *pRgn, int fnMode)
	Combines the specified region with the current clipping region using the specified mode. More...
MG_EXPORT void GUIAPI	SelectClipRegion (HDC hdc, const CLIPRGN *pRgn)
	Sets the visible region of a DC to be a region. More...
MG_EXPORT int GUIAPI	OffsetClipRegion (HDC hdc, int nXOffset, int nYOffset)
	Moves the clipping region of a device context by the specified offsets. More...
MG_EXPORT void GUIAPI	GetBoundsRect (HDC hdc, RECT *pRect)
	Retrieves the bounding rectangle of the current visible region of a DC. More...
MG_EXPORT BOOL GUIAPI	RectVisible (HDC hdc, const RECT *pRect)
	Checks whether the specified rectangle is visible. More...
MG_EXPORT int GUIAPI	GetClipBox (HDC hdc, RECT *clipbox)
	Retrieves the bounding rectangle of the current clipping region of a DC. More...
MG_EXPORT int GUIAPI	GetClipRegion (HDC hdc, CLIPRGN *cliprgn)
	Gets the current clipping region of a DC. More...

Detailed Description

Function Documentation

void GUIAPI ClipRectIntersect	(	HDC	hdc,
		const RECT *	prc
	)

Intersects the specified rectangle with the visible region of the DC.

This function intersects the specified rectangle prc with the visible region of the device context hdc.

Parameters

hdc	The device context.
prc	Pointer to the rectangle.

See also

IncludeClipRect, ExcludeClipRect, Region operations

void GUIAPI ExcludeClipRect	(	HDC	hdc,
		const RECT *	prc
	)

Excludes the specified rectangle from the current visible region of a DC.

This function excludes the specified rect prc from the current visible region of the device context hdc.

Parameters

hdc	The device context.
prc	The rectangle to be excluded.

See also

IncludeClipRect, Region operations

void GUIAPI GetBoundsRect	(	HDC	hdc,
		RECT *	pRect
	)

Retrieves the bounding rectangle of the current visible region of a DC.

This function retrieves the bounding rectangle of the current visible region of the specified device context hdc, and returned through pRect.

Parameters

hdc	The device context.
pRect	The bounding rectangle will be returned through this buffer.

See also

Region operations

int GetClipBox	(	HDC	hdc,
		RECT *	clipbox
	)

Retrieves the bounding rectangle of the current clipping region of a DC.

This function retrieves the bounding rectangle of the current clipping region of the specified device context hdc, and returned through clipbox.

Parameters

hdc	The device context.
clipbox	The bounding rectangle will be returned through this buffer.

Returns

-1 for error, else the type of clipping region, can be one of the following values:

• NULLREGION
  A null region.
• SIMPLEREGION
  A simple region.
• COMPLEXREGION
  A complex region.

See also

GetBoundsRect

int GetClipRegion	(	HDC	hdc,
		CLIPRGN *	cliprgn
	)

Gets the current clipping region of a DC.

This function gets the current clipping region of the specified device context hdc, and returned through cliprgn.

Parameters

hdc	The device context.
cliprgn	The clipping region will be returned through this buffer.

Returns

-1 for error, else the type of clipping region, can be one of the following values:

• NULLREGION
  A null region.
• SIMPLEREGION
  A simple region.
• COMPLEXREGION
  A complex region.

See also

GetClipBox, SelectClipRegion

void GUIAPI IncludeClipRect	(	HDC	hdc,
		const RECT *	prc
	)

Includes the specified rectangle to the current visible region of a DC.

This function includes the specified rectangle prc to the current visible region of the device context hdc.

Parameters

hdc	The device context.
prc	The rectangle to be included.

See also

ExcludeClipRect, Region operations

int GUIAPI OffsetClipRegion	(	HDC	hdc,
		int	off_x,
		int	off_y
	)

Moves the clipping region of a device context by the specified offsets.

This function moves the clipping region of a device context hdc by the specified offsets (off_x, off_y).

Parameters

hdc	Handle to the device context.
off_x	Specifies the number of device units to move left or right.
off_y	pecifies the number of device units to move up or down.

Returns

The return value specifies the new clipping region's complexity; it can be one of the following values.

Return values

NULLREGION	Region is empty.
SIMPLEREGION	Region is a single rectangle.
COMPLEXREGION	Region is more than one rectangle.
-1	An error occurred.

See also

SelectClipRegion

BOOL GUIAPI PtVisible	(	HDC	hdc,
		int	x,
		int	y
	)

Checks whether a point is visible.

This function checks whether the point specified by (x,y) is visible, i.e. it is within the current visible clipping region of the device context hdc.

Parameters

hdc	The device context.
x	x,y: The coordinates of the point.
y	x,y: The coordinates of the point.

Returns

TRUE for visible, else for not.

See also

RectVisible, Region operations

BOOL GUIAPI RectVisible	(	HDC	hdc,
		const RECT *	pRect
	)

Checks whether the specified rectangle is visible.

This function checks whether the rectangle pointed to by pRect is visible, i.e. it is intersected with the current visible region of the device context hdc.

Parameters

hdc	The device context.
pRect	Pointer to the rectangle.

See also

PtVisible, Region operations

Example:

/*
 * Use RectVisible to optimize the repaint of the window.
 */
case MSG_PAINT:
{
        HDC hdc = BeginPaint (hWnd);

        for (j = 0; j < 10; j ++) {
                if (RectVisible  (hdc, rcs + j)) {
                        FillBox (hdc, rcs[j].left, rcs[j].top, rcs [j].right, rcs [j].bottom);
                }
        }

        EndPaint (hWnd, hdc);
        return 0;
}

void GUIAPI SelectClipRect	(	HDC	hdc,
		const RECT *	prc
	)

Sets the visible region of a DC to be a rectangle.

This function sets the visible region of the device context hdc to the rectangle pointed to by prc.

Parameters

hdc	The device context.
prc	Pointer to the rectangle.

See also

SelectClipRegion, Region operations

void GUIAPI SelectClipRegion	(	HDC	hdc,
		const CLIPRGN *	pRgn
	)

Sets the visible region of a DC to be a region.

This function sets the visible region of the device context hdc to the region pointed to by pRgn.

Parameters

hdc	The device context.
pRgn	Pointer to the region.

See also

SelectClipRect, GetClipRegion, Region operations

int GUIAPI SelectClipRegionEx	(	HDC	hdc,
		const CLIPRGN *	pRgn,
		int	fnMode
	)

Combines the specified region with the current clipping region using the specified mode.

This function combines the specified region with the current clipping region using the specified mode.

If an error occurs when this function is called, the previous clipping region for the specified device context is not affected.

The SelectClipRegionEx function assumes that the coordinates for the specified region are specified in device units.

Only a copy of the region identified by the pRgn parameter is used. The region itself can be reused after this call or it can be deleted.

Parameters

hdc	Handle to the device context.
pRgn	Pointer to the region to be selected. This handle can only be NULL when the RGN_COPY mode is specified.
fnMode	Specifies the operation to be performed. It must be one of the following values:

• RGN_AND
  The new clipping region combines the overlapping areas of the current clipping region and the region identified by pRgn.
• RGN_COPY
  The new clipping region is a copy of the region identified by pRgn. This is identical to SelectClipRegion. If the region identified by pRgn is NULL, the new clipping region is the default clipping region (the default clipping region is a null region).
• RGN_DIFF
  The new clipping region combines the areas of the current clipping region with those areas excluded from the region identified by hrgn.
• RGN_OR
  The new clipping region combines the current clipping region and the region identified by hrgn.
• RGN_XOR
  The new clipping region combines the current clipping region and the region identified by hrgn but excludes any overlapping areas.

Returns

The return value specifies the new clipping region's complexity; it can be one of the following values.

Return values

NULLREGION	Region is empty.
SIMPLEREGION	Region is a single rectangle.
COMPLEXREGION	Region is more than one rectangle.
-1	An error occurred.

See also

SelectClipRect, SelectClipRegion, GetClipRegion, Region operations