MiniGUI API Reference (MiniGUI-Standalone)  v3.2.0
A mature and proven cross-platform GUI system for embedded and smart IoT devices
Macros | Typedefs | Functions
General DC operations

Macros

#define HDC_SCREEN   ((HDC)0)
 Handle to the device context of the whole screen. More...
 
#define HDC_INVALID   ((HDC)-1)
 Indicates an invalid handle to device context. More...
 
#define CreateCompatibleDC(hdc)   CreateCompatibleDCEx(hdc, 0, 0)
 Creates a memory DC which is compatible with a given DC. More...
 
#define DeleteCompatibleDC(hdc)   DeleteMemDC(hdc)
 Deletes a memory DC. More...
 

Typedefs

typedef void(* CB_DIRECT_DRAW_RECT) (HDC hdc, Uint8 *pixels, int pitch, int bytesPerPixel, const RECT *rc, void *context)
 Type of directly access pixels hook function. More...
 
typedef int(* ON_UPDATE_SECONDARYDC) (HWND hwnd, HDC secondary_dc, HDC real_dc, const RECT *secondary_rc, const RECT *real_rc, const RECT *main_update_rc)
 The callback type of on updating secondary DC. More...
 

Functions

MG_EXPORT unsigned int GUIAPI GetGDCapability (HDC hdc, int iItem)
 Returns a capability of a DC. More...
 
MG_EXPORT HDC GUIAPI GetDC (HWND hwnd)
 Gets a window DC of a window. More...
 
MG_EXPORT HDC GUIAPI GetClientDC (HWND hwnd)
 Gets a client DC of a window. More...
 
MG_EXPORT HDC GUIAPI GetSubDC (HDC hdc, int off_x, int off_y, int width, int height)
 This function gets a sub DC which is compliant to the specified client DC. More...
 
MG_EXPORT void GUIAPI ReleaseDC (HDC hdc)
 Releases a DC from DC pool. More...
 
MG_EXPORT HWND GUIAPI WindowFromDC (HDC hdc)
 Get the window handle from DC. More...
 
MG_EXPORT int GUIAPI SaveDC (HDC hdc)
 Saves the current state of a device context. More...
 
MG_EXPORT BOOL GUIAPI RestoreDC (HDC hdc, int saved_dc)
 Restores a device context (DC) to the specified state. More...
 
MG_EXPORT HDC GUIAPI CreateCompatibleDCEx (HDC hdc, int width, int height)
 Creates a memory DC which is compatible with the specified reference DC. More...
 
MG_EXPORT BOOL GUIAPI IsCompatibleDC (HDC hdc1, HDC hdc2)
 Check whether a given DC is compliant to a specific DC. More...
 
MG_EXPORT HDC GUIAPI CreateMemDCEx (int width, int height, int depth, DWORD flags, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask, void *bits, int pitch)
 Creates a memory DC. More...
 
static HDC GUIAPI CreateMemDC (int width, int height, int depth, DWORD flags, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask)
 Creates a memory DC. More...
 
MG_EXPORT HDC GUIAPI CreateSubMemDC (HDC parent, int off_x, int off_y, int width, int height, BOOL comp_to_parent)
 Creates a sub memory DC in the given memory DC. More...
 
MG_EXPORT HDC GUIAPI CreateMemDCFromBitmap (HDC hdc, const BITMAP *bmp)
 Creates a memory DC from a reference DC and a BITMAP object. More...
 
MG_EXPORT HDC GUIAPI CreateMemDCFromMyBitmap (const MYBITMAP *my_bmp, const RGB *pal)
 Creates a memory DC from a device independent MYBITMAP object. More...
 
MG_EXPORT BOOL GUIAPI ConvertMemDC (HDC mem_dc, HDC ref_dc, DWORD flags)
 Converts a memory DC to have a same format as a reference DC. More...
 
MG_EXPORT BOOL GUIAPI SetMemDCAlpha (HDC mem_dc, DWORD flags, Uint8 alpha)
 Sets the alpha value for the entire surface of a DC, as opposed to using the alpha component of each pixel. More...
 
MG_EXPORT BOOL GUIAPI SetMemDCColorKey (HDC mem_dc, DWORD flags, Uint32 color_key)
 Sets the color key (transparent pixel) of a memory DC. More...
 
MG_EXPORT void GUIAPI DeleteMemDC (HDC mem_dc)
 Deletes a memory DC. More...
 
MG_EXPORT Uint8 *GUIAPI LockDC (HDC hdc, const RECT *rw_rc, int *width, int *height, int *pitch)
 Locks a dc to get direct access to pixels in the DC. More...
 
MG_EXPORT BOOL GUIAPI LockDCEx (HDC hdc, const PCLIPRGN region, void *context, CB_DIRECT_DRAW_RECT cb)
 directly access the pixels in a DC. More...
 
MG_EXPORT void GUIAPI UnlockDC (HDC hdc)
 Unlocks a locked DC. More...
 
MG_EXPORT HDC GUIAPI CreatePrivateDC (HWND hwnd)
 Creates a private window DC of a window. More...
 
MG_EXPORT HDC GUIAPI CreatePrivateClientDC (HWND hwnd)
 Creates a private client DC of a window. More...
 
HDC GUIAPI CreatePrivateSubDC (HDC hdc, int off_x, int off_y, int width, int height)
 Creates a private SubDC of a window. More...
 
MG_EXPORT HDC GUIAPI GetPrivateClientDC (HWND hwnd)
 Returns the private client DC of a window. More...
 
MG_EXPORT void GUIAPI DeletePrivateDC (HDC hdc)
 Deletes the DC returned by CreatePrivateDC or CreatePrivateClientDC or CreatePrivateSubDC. More...
 
MG_EXPORT HDC GUIAPI CreateSecondaryDC (HWND hwnd)
 Creates a secondary window DC of a window. More...
 
MG_EXPORT HDC GUIAPI SetSecondaryDC (HWND hwnd, HDC secondary_dc, ON_UPDATE_SECONDARYDC on_update_secondarydc)
 Set a window's secondary DC and the callback procedure for the secondary DC update. More...
 
MG_EXPORT HDC GUIAPI GetSecondaryDC (HWND hwnd)
 Retrives and returns the secondary DC of a specific window. More...
 
MG_EXPORT HDC GUIAPI GetSecondaryClientDC (HWND hwnd)
 Retrives and returns the client secondary DC of a specific window. More...
 
MG_EXPORT void GUIAPI ReleaseSecondaryDC (HWND hwnd, HDC hdc)
 Release the DC returned by GetSecondaryDC or GetSecondaryClientDC. More...
 
MG_EXPORT void GUIAPI DeleteSecondaryDC (HWND hwnd)
 Deletes the secondary DC of the window. More...
 

Detailed Description

DC means Device Context, just like Graphics Context (GC) of X Lib. DC represents a rectangle area on the actual screen or a virtual screen created in memory. We call the rectangle area as "surface" of the DC.

You can call a GDI function and pass a DC to the function to draw lines, circles, or text. Commonly, you should call a function like GetClientDC or CreateCompatibleDC to get or create a DC, then call GDI functions to draw objects, e.g. MoveTo and LineTo. After finishing drawing, you should call ReleaseDC or DeleteMemDC function to release or destroy the DC.

MiniGUI reserved an global DC called HDC_SCREEN. You can use this DC directly without getting/creating or releasing/destroying.

For main windows or controls, MiniGUI will send a MSG_PAINT message to the window when the whole or part of window area have been invalidated. You should call BegainPaint function to get the DC, then repaint the window, and call EndPaint function to release the DC at the last.

Example:

case MSG_PAINT:
{
HDC hdc;
hdc = BeginPaint (hWnd);
// Draw a line.
MoveTo (hdc, 0, 0);
LineTo (hdc, 100, 100);
EndPaint (hWnd, hdc);
return 0;
}

Macro Definition Documentation

#define CreateCompatibleDC (   hdc)    CreateCompatibleDCEx(hdc, 0, 0)

Creates a memory DC which is compatible with a given DC.

This function creates a memory DC fully compatible with the reference DC hdc, including pixel format and geomatry.

Parameters
hdcThe reference DC.
Returns
The handle to the memory DC, HDC_INVALID indicates an error.
See also
CreateCompatibleDCEx, DeleteMemDC

Definition at line 1637 of file gdi.h.

#define DeleteCompatibleDC (   hdc)    DeleteMemDC(hdc)

Deletes a memory DC.

This function deletes a memory DC created by CreateCompatibleDC.

Parameters
hdcThe device context to be deleted.
See also
CreateCompatibleDC, DeleteMemDC

Definition at line 1649 of file gdi.h.

#define HDC_INVALID   ((HDC)-1)

Indicates an invalid handle to device context.

Definition at line 1126 of file gdi.h.

#define HDC_SCREEN   ((HDC)0)

Handle to the device context of the whole screen.

This DC is a special one. MiniGUI uses it to draw popup menus and other global objects. You can also use this DC to draw lines or text on the screen directly, and there is no need to get or release it.

If you do not want to create any main window, but you want to draw on the screen, you can use this DC.

Note
MiniGUI does not do any clipping operation for this DC, so use this DC may make a mess of other windows.

Definition at line 1114 of file gdi.h.

Typedef Documentation

typedef void(* CB_DIRECT_DRAW_RECT)(HDC hdc, Uint8 *pixels, int pitch, int bytesPerPixel, const RECT *rc, void *context)

Type of directly access pixels hook function.

This function is invoked by LockDCEx, application should implement this function in which could directly read and write the pixels in a DC.

Parameters
hdcthe device context.
pixelsthe pixels addr point to the rc's left-top in DC.
pitch(the bytes of one scan line) of the DC.
bytesPerPixelbytes per pixel.
rcthe rectangle to draw, the field left of which is mapped to pixels.
contextthe context provided by application.

Definition at line 1707 of file gdi.h.

typedef int(* ON_UPDATE_SECONDARYDC)(HWND hwnd, HDC secondary_dc, HDC real_dc, const RECT *secondary_rc, const RECT *real_rc, const RECT *main_update_rc)

The callback type of on updating secondary DC.

Parameters
hwndThe handle to the updated window.
secondary_dcThe update src dc.
real_dcThe update dst dc.
secondary_rcThe rectangle relative to secondary_dc.
real_rcThe rectangle relative to real_dc.
main_update_dcThe rectangle relative to main window.
Returns
The update result.

Definition at line 1892 of file gdi.h.

Function Documentation

BOOL GUIAPI ConvertMemDC ( HDC  mem_dc,
HDC  ref_dc,
DWORD  flags 
)

Converts a memory DC to have a same format as a reference DC.

This function converts a memory DC mem_dc in order to let it have the same pixel format as the reference DC ref_dc. This function will try to create a new surface for mem_dc, and then copies and maps the surface of ref_dc to it so the blit of the converted memory DC will be as fast as possible.

The flags parameter has the same semantics as CreateMemDC. You can also pass MEMDC_FLAG_RLEACCEL in the flags parameter and MiniGUI will try to RLE accelerate colorkey and alpha blits in the resulting memory DC.

Parameters
mem_dcThe device context to be converted.
ref_dcThe reference device context.
flagsThe memory DC flags, has the same semantics as CreateMemDC.
Returns
TRUE on success, otherwise FALSE.
See also
CreateMemDC, DeleteMemDC

Referenced by CreateMemDC().

HDC GUIAPI CreateCompatibleDCEx ( HDC  hdc,
int  width,
int  height 
)

Creates a memory DC which is compatible with the specified reference DC.

This function creates a memory DC which have the same pixel format as the specified reference DC hdc. The same pixel format means that the memory DC will have the same pixel depth, the same RGB composition, or the same palette as the reference DC. Note that the memdc will have the same DC attributes as the reference DC.

Parameters
hdcThe handle to the reference DC.
widthThe expected width of the result memory DC. If it is zero, the width will be equal to the width of the reference DC.
heightThe expected height of the result memory DC. If it is zero, the height will be equal to the height of the reference DC.
Returns
The handle to the memory DC, HDC_INVALID indicates an error.
See also
CreateCompatibleDC
HDC GUIAPI CreateMemDC ( int  width,
int  height,
int  depth,
DWORD  flags,
Uint32  Rmask,
Uint32  Gmask,
Uint32  Bmask,
Uint32  Amask 
)
inlinestatic

Creates a memory DC.

This function creates a memory DC which have the specified flags and pixel format.

Parameters
widthThe expected width of the result memory DC.
heightThe expected height of the result memory DC.
depthThe expected color depth of the memory DC.
flagsThe memory DC flags, can be or'ed values of the following flags:
  • MEMDC_FLAG_SWSURFACE
    Creates the surface of memory DC in the system memory.
  • MEMDC_FLAG_HWSURFACE
    Creates the surface of memory DC in the video memory.
  • MEMDC_FLAG_SRCCOLORKEY
    The created memory DC will use a source color key to blit to other DC.
  • MEMDC_FLAG_SRCALPHA
    The created memory DC will use a source alpha blending to blit to other DC.
  • MEMDC_FLAG_RLEACCEL
    The memory DC will be RLE encoded.
Parameters
RmaskThe bit-masks of the red components in a pixel value.
GmaskThe bit-masks of the green components in a pixel value.
BmaskThe bit-masks of the blue components in a pixel value.
AmaskThe bit-masks of the alpha components in a pixel value.
Returns
The handle to the memory DC, HDC_INVALID indicates an error.
See also
CreateMemDCEx, CreateMemDCFromBitmap, CreateMemDCFromMyBitmap, CreateCompatibleDCEx

Definition at line 1455 of file gdi.h.

References ConvertMemDC(), CreateMemDCEx(), CreateMemDCFromBitmap(), CreateMemDCFromMyBitmap(), CreateSubMemDC(), DeleteMemDC(), NULL, SetMemDCAlpha(), and SetMemDCColorKey().

HDC GUIAPI CreateMemDCEx ( int  width,
int  height,
int  depth,
DWORD  flags,
Uint32  Rmask,
Uint32  Gmask,
Uint32  Bmask,
Uint32  Amask,
void *  bits,
int  pitch 
)

Creates a memory DC.

This function creates a memory DC which have the specified flags and pixel format, and uses the pre-allocated buffer as the surface if bits is not NULL.

Parameters
widthThe expected width of the result memory DC.
heightThe expected height of the result memory DC.
depthThe expected color depth of the memory DC.
flagsThe memory DC flags, can be or'ed values of the following flags:
  • MEMDC_FLAG_SWSURFACE
    Creates the surface of memory DC in the system memory.
  • MEMDC_FLAG_HWSURFACE
    Creates the surface of memory DC in the video memory.
  • MEMDC_FLAG_SRCCOLORKEY
    The created memory DC will use a source color key to blit to other DC.
  • MEMDC_FLAG_SRCALPHA
    The created memory DC will use a source alpha blending to blit to other DC.
  • MEMDC_FLAG_RLEACCEL
    The memory DC will be RLE encoded.
Parameters
RmaskThe bit-masks of the red components in a pixel value.
GmaskThe bit-masks of the green components in a pixel value.
BmaskThe bit-masks of the blue components in a pixel value.
AmaskThe bit-masks of the alpha components in a pixel value.
bitsThe pointer to the pre-allocated surface. If this is NULL, MiniGUI will try to allocate the surface from video memory or system memory.
pitchThe pitch (the number of bytes of one scan line) of the surface.
Returns
The handle to the memory DC, HDC_INVALID indicates an error.
Note
If you pass a pre-allocated surface buffer to this function, MiniGUI will not free the buffer when you delete the memdc by calling DeleteMemDC.
See also
CreateMemDC, CreateMemDCFromBitmap, CreateMemDCFromMyBitmap, CreateCompatibleDCEx

Referenced by CreateMemDC().

HDC GUIAPI CreateMemDCFromBitmap ( HDC  hdc,
const BITMAP bmp 
)

Creates a memory DC from a reference DC and a BITMAP object.

This function creates a memory DC compatible with the specified DC, and use the bits of the BITMAP object as the surface of the memory DC. The created memory DC will have the same geometry as the BITMAP object.

Parameters
hdcThe reference DC.
bmpThe BITMAP object.
Returns
The handle to the memory DC, HDC_INVALID indicates an error.
See also
CreateMemDCFromMyBitmap, DeleteMemDC, BITMAP

Referenced by CreateMemDC().

HDC GUIAPI CreateMemDCFromMyBitmap ( const MYBITMAP my_bmp,
const RGB pal 
)

Creates a memory DC from a device independent MYBITMAP object.

This function creates a memory DC which have the same pixel format as the MYBITMAP object my_bmp, and use the bits of the MYBITMAP object as the surface of the memory DC. The created memory DC will have the same geometry as the MYBITMAP object. If the depth of my_bmp is 8-bit, the function will use pal to initialize the palette of the memory DC.

Note that the color depth of a memory DC can not be less than 8. Thefore, if the color depth of the MYBITMAP object is less than 8, this function will return HDC_INVALID.

Note that if the MYBITMAP object has the flag MYBMP_FLOW_UP, this function will return HDC_INVALID as well.

Parameters
my_bmpThe device independent MYBITMAP object.
palThe palette of the MYBITMAP object. If the depth of my_bmp is larger than 8-bit, this argument can be NULL.
Returns
The handle to the memory DC, HDC_INVALID indicates an error.
See also
CreateMemDCFromBitmap, DeleteMemDC, MYBITMAP

Referenced by CreateMemDC().

HDC GUIAPI CreatePrivateClientDC ( HWND  hwnd)

Creates a private client DC of a window.

This function creates a private client DC of the window hwnd and returns the handle to the DC.

When you calling CreatePrivateClientDC function to create a private client DC, MiniGUI will create the DC in the system heap, rather than allocate one from the DC pool. Thus, you can keep up the DC in the life cycle of the window, and are not needed to release it for using by other windows.

Parameters
hwndThe handle to the window.
Returns
The handle to the DC, HDC_INVALID indicates an error.
See also
DeletePrivateDC
HDC GUIAPI CreatePrivateDC ( HWND  hwnd)

Creates a private window DC of a window.

This function creates a private window DC of the window hwnd and returns the handle to the DC.

When you calling CreatePrivateDC function to create a private DC, MiniGUI will create the DC in the system heap, rather than allocate one from the DC pool. Thus, you can keep up the private DC in the life cycle of the window, and are not needed to release it for using by other windows.

Parameters
hwndThe handle to the window.
Returns
The handle to the DC, HDC_INVALID indicates an error.
See also
DeletePrivateDC
HDC GUIAPI CreatePrivateSubDC ( HDC  hdc,
int  off_x,
int  off_y,
int  width,
int  height 
)

Creates a private SubDC of a window.

This function creates a private SubDC of the DC and returns the handle of the SubDC.

When you calling CreatePrivateSubDC function to create a private Sub DC, MiniGUI will create the DC in the system heap, rather than allocate one from the DC pool. Thus, you can keep up the DC in the life cycle of the window, and are not needed to release it for using by other windows.

Parameters
hdcThe handle of the DC.
off_xThe x-coordinate of the sub DC in the parent DC (in device coordinate system).
off_yThe y-coordinate of the sub DC in the parent DC (in device coordinate system).
widthThe expected width of the sub DC.
heightThe expected height of the sub DC.
Returns
The handle to SubDC, HDC_INVALID indicates an error.
See also
DeletePrivateDC
HDC GUIAPI CreateSecondaryDC ( HWND  hwnd)

Creates a secondary window DC of a window.

This function creates a secondary DC for the main window hwnd and returns the handle to the secondary DC.

When you calling CreateSecondaryDC function, MiniGUI will create a memory DC which is compatible with HDC_SCREEN.

When a main window have the extended style WS_EX_AUTOSECONDARYDC, MiniGUI will create a Secondary DC for this main window in the creation progress of the main window, and destroy the DC when you destroy the window. MiniGUI will use this Secondary DC and its sub DCs to render the window content and childen.

Parameters
hwndThe handle to the window.
Returns
The handle to the DC, HDC_INVALID indicates an error.
See also
DeleteSecondaryDC
HDC GUIAPI CreateSubMemDC ( HDC  parent,
int  off_x,
int  off_y,
int  width,
int  height,
BOOL  comp_to_parent 
)

Creates a sub memory DC in the given memory DC.

This function creates a sub memory DC in the given memory DC (the parent memory DC). Note that the new sub memdc will have the same DC attributes as the parent memdc.

Parameters
parentThe handle to the parent memory DC.
off_xThe x-coordinate of the sub memory DC in the parent DC (in device coordinate system).
off_yThe y-coordinate of the sub memory DC in the parent DC (in device coordinate system).
widthThe expected width of the sub memory DC.
heightThe expected height of the sub memory DC.
comp_to_parentThe flag indicates whether the sub memdc is compliant to the parent dc.
Returns
The handle to the memory DC; HDC_INVALID indicates an error.
Note
Only defined for _USE_NEWGAL.
See also
CreateMemDC

Referenced by CreateMemDC().

void GUIAPI DeleteMemDC ( HDC  mem_dc)

Deletes a memory DC.

This function deletes the memory DC mem_dc, and frees the surface of the DC. For the memory DC created from BITMAP object or MYBITMAP object, the bits used by the surface of the DC will be reserved.

Parameters
mem_dcThe device context to be deleted.
See also
CreateMemDC, CreateMemDCFromBitmap, CreateMemDCFromMyBitmap

Referenced by CreateMemDC().

void GUIAPI DeletePrivateDC ( HDC  hdc)

Deletes the DC returned by CreatePrivateDC or CreatePrivateClientDC or CreatePrivateSubDC.

Parameters
hdcThe handle to the DC.
See also
CreatePrivateDC, CreatePrivateClientDC
void GUIAPI DeleteSecondaryDC ( HWND  hwnd)

Deletes the secondary DC of the window.

Parameters
hwndThe handle to the window.
See also
CreateSecondaryDC
HDC GUIAPI GetClientDC ( HWND  hwnd)

Gets a client DC of a window.

This function gets a client DC of the specified hwnd, and returns the handle to the DC. MiniGUI will try to return an unused DC from the internal DC pool, rather than allocate a new one from the system heap. Thus, you should release the DC when you finish drawing as soon as possible.

Parameters
hwndThe handle to the window.
Returns
The handle to the DC, HDC_INVALID indicates an error.
Note
You should call ReleaseDC to release the DC when you are done.
See also
GetDC, ReleaseDC
HDC GUIAPI GetDC ( HWND  hwnd)

Gets a window DC of a window.

This function gets a window DC of the specified hwnd, and returns the handle to the DC. MiniGUI will try to return an unused DC from the internal DC pool, rather than allocate a new one from the system heap. Thus, you should release the DC when you finish drawing as soon as possible.

Parameters
hwndThe handle to the window.
Returns
The handle to the DC, HDC_INVALID indicates an error.
Note
You should call ReleaseDC to release the DC when you are done.
See also
GetClientDC, ReleaseDC
unsigned int GUIAPI GetGDCapability ( HDC  hdc,
int  iItem 
)

Returns a capability of a DC.

This function returns the capability of the specified item iItem of the DC hdc.

Parameters
hdcThe handle to the DC.
iItemAn integer presents the capablity, can be one of the following values:
  • GDCAP_COLORNUM
    Tell GetGDCapability to return the colors number of the DC. Note the for a DC with 32-bit depth, the function will return 0xFFFFFFFF, not 0x100000000.
  • GDCAP_HPIXEL
    Tell GetGCapability to return the horizontal resolution of the DC.
  • GDCAP_VPIXEL
    Tell GetGDCapability to return the vertical resolution of the DC.
  • GDCAP_MAXX
    Tell GetGDCapability to return the maximal visible x value of the DC.
  • GDCAP_MAXY
    Tell GetGDCapability to return the maximal visible y value of the DC.
  • GDCAP_DEPTH
    Tell GetGDCapability to return the color depth of the DC. The returned value can be 1, 4, 8, 15, 16, 24, or 32.
  • GDCAP_BITSPP
    Tell GetGDCapability to return the bits number for storing a pixle in the DC.
  • GDCAP_BPP
    Tell GetGDCapability to return the bytes number for storing a pixle in the DC.
  • GDCAP_RMASK
    Tell GetGDCapability to return the pixel red color mask for the DC.
  • GDCAP_GMASK
    Tell GetGDCapability to return the pixel green color mask for the DC.
  • GDCAP_BMASK
    Tell GetGDCapability to return the pixel blue color mask for the DC.
  • GDCAP_AMASK
    Tell GetGDCapability to return the pixel alpha color mask for the DC.
  • GDCAP_PITCH
    Tell GetGDCapability to return the pitch (the bytes of one scan line) of the DC.
Returns
The capbility.
HDC GUIAPI GetPrivateClientDC ( HWND  hwnd)

Returns the private client DC of a window.

This function returns the private client DC of the window hwnd which have extended style WS_EX_USEPRIVATECDC.

When a main window have the extended style WS_EX_USEPRIVATECDC, or a control class have the style CS_OWNDC, MiniGUI will create a private client DC for this window in the creation progress of the window, and destroy the DC when you destroy the window, and use this private client DC in default message handlers. So there will be some improvments on drawing/repaint performance. You can alos call this function to get the private client DC, and use it to draw anything in your window.

Parameters
hwndThe handle to the window.
Returns
The handle to the private client DC, HDC_INVALID indicates an error.
See also
CreatePrivateClientDC
HDC GUIAPI GetSecondaryClientDC ( HWND  hwnd)

Retrives and returns the client secondary DC of a specific window.

This function retrives and returns the client secondary DC of the main window hwnd.

When a main window have the secondary DC, MiniGUI will use this secondary DC and its sub DCs to render the content of the window and its children.

Parameters
hwndThe handle to the main window.
Returns
The handle to the client secondary DC, HDC_SCREEN indicates that the main window has no secondary DC.
See also
ReleaseSecondaryDC, SetSecondaryDC
HDC GUIAPI GetSecondaryDC ( HWND  hwnd)

Retrives and returns the secondary DC of a specific window.

This function retrives and returns the secondary DC of the window hwnd.

When a main window have the secondary DC, MiniGUI will use this secondary DC and its sub DCs to render the content of the window and its children.

Parameters
hwndThe handle to the window.
Returns
The handle to the secondary DC, HDC_SCREEN indicates that the window has no secondary DC.
See also
ReleaseSecondaryDC, SetSecondaryDC
HDC GUIAPI GetSubDC ( HDC  hdc,
int  off_x,
int  off_y,
int  width,
int  height 
)

This function gets a sub DC which is compliant to the specified client DC.

This function creates a sub client DC, which is restricted in the specified rectangle and compliant to the specified client DC hdc. Note that you should release the returned dc by calling ReleaseDC.

Parameters
hdcThe handle to the parent client DC.
off_xThe x-coordinate of the sub DC in the parent DC (in device coordinate system).
off_yThe y-coordinate of the sub DC in the parent DC (in device coordinate system).
widthThe expected width of the sub DC.
heightThe expected height of the sub DC.
Returns
The handle to the new sub DC, HDC_INVALID indicates an error.
Note
You should call ReleaseDC to release the DC when you are done.
See also
GetDC, GetClientDC, ReleaseDC
BOOL GUIAPI IsCompatibleDC ( HDC  hdc1,
HDC  hdc2 
)

Check whether a given DC is compliant to a specific DC.

This function checks whether a give DC hdc2 is compliant to the specific DC hdc1.

Parameters
hdc1The handle to a DC.
hdc2The handle to another DC.
Returns
TRUE when hdc2 is compiliant to hdc1, otherwise FALSE.
See also
CreateCompatibleDCEx
Uint8 *GUIAPI LockDC ( HDC  hdc,
const RECT rw_rc,
int *  width,
int *  height,
int *  pitch 
)

Locks a dc to get direct access to pixels in the DC.

Calling this function will try to lock the DC hdc to directly access the pixels of the DC. You should tell this function the rectangle to be accessed, and the function will return the requested width, height and pitch of the DC. The access beyond requested width and height will be invalid.

Locking a DC which uses screen surface will lock some global objects, such as mouse cursor, and so on. All GDI calls of other threads (in MiniGUI-Threads) or other process (in MiniGUI-Processes) will be blocked as well. So you should call UnlockDC to unlock the DC as soon as possible, and should not call any system function in the duration of locking the DC.

Parameters
hdcThe handle to the device context.
rw_rcThe rectangle in device coordinate system to be accessed in the DC.
widthThe width of the effective rectangle can access will be returned through this pointer.
heightThe height of the effective rectangle can access will be returned through this pointer.
pitchThe pitch of the scan line of the DC will be returned through this pointer. Pitch means the length of the scan line in bytes.
Returns
The bits pointer to the upper-left corner of the requested rectangle, NULL on error.
See also
UnlockDC, LockDCEx

Example:

/*
* lock the dc and draw the scan line with random color.
*/
int i, width, height, pitch;
RECT rc = {0, 0, 200, 200};
int bpp = GetGDCapability (hdc, GDCAP_BPP);
Uint8* frame_buffer = LockDC (hdc, &rc, &width, &height, &pitch);
Uint8* row = frame_buffer;
for (i = 0; i < *height; i++) {
memset (row, rand ()%0x100, *width * bpp);
row += *pitch;
}
UnlockDC (hdc);
BOOL GUIAPI LockDCEx ( HDC  hdc,
const PCLIPRGN  region,
void *  context,
CB_DIRECT_DRAW_RECT  cb 
)

directly access the pixels in a DC.

This function fill region by function cb that directly accesses pixels in a DC. This function is used to draw region more effiently. The function that lock __mg_gdilock should not be invoked any more after invoking this function, or else it will cause deadlock. UnlockDC should be invoked after invoking this function that will call back CB_DIRECT_DRAW_RECT, other process could not draw any more until the DC has been unlocked.

Parameters
hdcthe device context.
regionthe visible region to draw.
contextthe context provided by application, which is as a parameter of cb.
cbthe direct draw function that directly accesses pixels which should be implemented by application. if cb is NULL, the region will be filled by current brush color.
Returns
if LockDCEx success return TRUE, else return FALSE;
See also
UnlockDC, LockDC
void GUIAPI ReleaseDC ( HDC  hdc)

Releases a DC from DC pool.

This function releases the DC returned by GetDC or GetClientDC.

Parameters
hdcThe handle to the DC.
See also
GetDC, GetClientDC, GetSubDC
void GUIAPI ReleaseSecondaryDC ( HWND  hwnd,
HDC  hdc 
)

Release the DC returned by GetSecondaryDC or GetSecondaryClientDC.

Parameters
hwndThe handle to the window.
hdcThe handle to the secondary DC.
Returns
void
See also
GetSecondaryDC, GetSecondaryClientDC
BOOL GUIAPI RestoreDC ( HDC  hdc,
int  saved_dc 
)

Restores a device context (DC) to the specified state.

This function restores a device context (DC) to the specified state. The DC is restored by popping state information off a stack created by earlier calls to the SaveDC function.

Parameters
hdcThe handle to the DC.
saved_dcSpecifies the saved state to be restored. If this parameter is positive, saved_dc represents a specific instance of the state to be restored. If this parameter is negative, saved_dc represents an instance relative to the current state. For example, -1 restores the most recently saved state.
Returns
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.
Note
The stack can contain the state information for several instances of the DC. If the state specified by the specified parameter is not at the top of the stack, RestoreDC deletes all state information between the top of the stack and the specified instance.
See also
SaveDC
int GUIAPI SaveDC ( HDC  hdc)

Saves the current state of a device context.

This function saves the current state of the specified device context (DC) by copying data describing selected objects and graphic modes (such as pen, brush, palette, font, pen, region, drawing mode, and mapping mode) to a context stack.

Parameters
hdcThe handle to the DC whose state is to be saved.
Returns
If the function succeeds, the return value identifies the saved state. If the function fails, the return value is zero.
Note
This function can be used any number of times to save any number of instances of the DC state. A saved state can be restored by using the RestoreDC function.
See also
RestoreDC
BOOL GUIAPI SetMemDCAlpha ( HDC  mem_dc,
DWORD  flags,
Uint8  alpha 
)

Sets the alpha value for the entire surface of a DC, as opposed to using the alpha component of each pixel.

This function sets the alpha value for the entire surface of the DC mem_dc, as opposed to using the alpha component of each pixel. This value measures the range of transparency of the surface, 0 being completely transparent to 255 being completely opaque. An alpha value of 255 causes blits to be opaque, the source pixels copied to the destination (the default). Note that per-surface alpha can be combined with colorkey transparency.

If flags is 0, alpha blending is disabled for the surface. If flags is MEMDC_FLAG_SRCALPHA, alpha blending is enabled for the surface. OR'ing the flag with MEMDC_FLAG_RLEACCEL requests RLE acceleration for the surface; if MEMDC_FLAG_RLEACCEL is not specified, the RLE acceleration will be removed. If flags is MEMDC_FLAG_SRCPIXELALPHA, per-pixel alpha blending is enabled for the surface.

Parameters
mem_dcThe device context.
flagsThe alpha value specific memory DC flags.
alphathe alpha value for the entire surface of the DC mem_dc.
Returns
TRUE on success, otherwise FALSE.
See also
SetMemDCColorKey

Referenced by CreateMemDC().

BOOL GUIAPI SetMemDCColorKey ( HDC  mem_dc,
DWORD  flags,
Uint32  color_key 
)

Sets the color key (transparent pixel) of a memory DC.

This function sets the color key (transparent pixel) of the memory DC mem_dc. If flags is MEMDC_FLAG_SRCCOLORKEY (optionally OR'ed with MEMDC_FLAG_RLEACCEL), color_key will be the transparent pixel in the source DC of a blit. MEMDC_FLAG_RLEACCEL requests RLE acceleration for the source of the DC if present, and removes RLE acceleration if absent. If flags is 0, this function clears any current color key.

Parameters
mem_dcThe device context.
flagsThe color key specific memory DC flags.
color_keyThe color_key of the memory DC.
Returns
TRUE on success, otherwise FALSE.
See also
SetMemDCAlpha

Referenced by CreateMemDC().

HDC GUIAPI SetSecondaryDC ( HWND  hwnd,
HDC  secondary_dc,
ON_UPDATE_SECONDARYDC  on_update_secondarydc 
)

Set a window's secondary DC and the callback procedure for the secondary DC update.

This function set the secondary DC of the main window hwnd and returns the handle to the old seconadary DC.

Parameters
hwndThe handle to the main window.
secondary_dcThe secondary DC which will be the new secondary DC of the main window.
on_update_secondarydcThe callback procedure for the secondary DC update. You can pass one of two sepcial values:
  • ON_UPDSECDC_DEFAULT
    The default operation to update the secondary DC to the real DC of the main window.
  • ON_UPDSECDC_DONOTHING
    No any operation occures.
Returns
The handle to the old secondary DC, HDC_SCREEN indicates the main window has no secondary DC before calling this function.
See also
DeleteSecondaryDC
void GUIAPI UnlockDC ( HDC  hdc)

Unlocks a locked DC.

Parameters
hdcThe locked DC.
See also
LockDC, LockDCEx
HWND GUIAPI WindowFromDC ( HDC  hdc)

Get the window handle from DC.

This function returns the handle to a window according to the handle to DC of the window.

Parameters
hdcThe handle to the DC.
Note
Do not call this function on memory DC.
See also
GetDC.