MiniGUI API Reference (MiniGUI-Threads)  v3.2.0
A mature and proven cross-platform GUI system for embedded and smart IoT devices
Functions
Resource managment functions

Functions

MG_EXPORT BOOL GUIAPI RegisterResFromFile (HDC hdc, const char *file)
 Register a device-dependent bitmap from a file. More...
 
MG_EXPORT BOOL GUIAPI RegisterResFromMem (HDC hdc, const char *file, const unsigned char *data, size_t data_size)
 Register a device-dependent bitmap to bitmap cache from memory. More...
 
MG_EXPORT BOOL GUIAPI RegisterResFromBitmap (const char *file, const BITMAP *bmp)
 Register a device-dependent bitmap to bitmap cache. More...
 
MG_EXPORT const BITMAP *GUIAPI RetrieveRes (const char *file)
 Get a BITMAP object from cache according to the specified resource file name. More...
 
MG_EXPORT void GUIAPI UnregisterRes (const char *file)
 Unregister the BITMAP object from cache according to the specified resource file name. More...
 
MG_EXPORT BOOL GUIAPI RegisterSystemBitmap (HDC hdc, const char *rdr_name, const char *id)
 Register a device-dependent bitmap from id to BITMAP cache. More...
 
MG_EXPORT void GUIAPI UnregisterSystemBitmap (HDC hdc, const char *rdr_name, const char *id)
 Unregister a BITMAP object from BITMAP cache. More...
 
MG_EXPORT const char * GetResPath (void)
 Get the currrent user's resource path. More...
 
MG_EXPORT int SetResPath (const char *path)
 Set user's resource path into the search paths of resource manager. More...
 
MG_EXPORT int AddInnerRes (INNER_RES *inner_res, int count, BOOL copy)
 Add some incore resource into the resource manager in order to call LoadResource to get those resource. More...
 
MG_EXPORT int RegisterResType (int type, RES_TYPE_OPS *ops)
 Register a new user-defined type into resource manager, so that the LoadResource can load the special resource automatically. More...
 
MG_EXPORT int UnregisterResType (int type)
 Unregister a user-defined resource type. More...
 
MG_EXPORT void * LoadResource (const char *res_name, int type, DWORD usr_param)
 Load a resource from disk or memory. More...
 
MG_EXPORT void * GetResource (RES_KEY key)
 Retrive and return a buffered resource by the key. More...
 
MG_EXPORT int AddResRef (RES_KEY key)
 Increase the reference count of a buffered resource. More...
 
MG_EXPORT int ReleaseRes (RES_KEY key)
 Release the buffered resource. It will decrease the reference count of the resource. If the reference count is less then 0, the resource will be released. More...
 
MG_EXPORT RES_KEY Str2Key (const char *str)
 Translate a string to an unsigned long (RES_KEY), which is used to find a resource in the resource manager. More...
 

Detailed Description

Function Documentation

int AddInnerRes ( INNER_RES *  inner_res,
int  count,
BOOL  copy 
)

Add some incore resource into the resource manager in order to call LoadResource to get those resource.

Parameters
inner_resThe pointer to the incore resource.
countThe bytes count of inner_res.
copyTRUE indicate that resource manager will copy the value of inner_res array, otherwise, resource manager just save the pointer to inner_res.
Returns
RES_RET_OK for success or error code.

Referenced by GetWindowInfo().

int AddResRef ( RES_KEY  key)

Increase the reference count of a buffered resource.

When you get a resource, you should call this function to ensure that the resource can not be unloaded when you still use it. This function must be called after LoadResource.

Parameters
keyThe key of resource (use Str2Key(res_name) to get the key).
Returns
The reference count; -1 if the resource does not exist.
See also
LoadResource, GetResource, ReleaseRes, Str2Key

Referenced by GetWindowInfo().

void * GetResource ( RES_KEY  key)

Retrive and return a buffered resource by the key.

You should call LoadResource firstly, and then call GetResource when you need it. Note that GetResource will not increase the reference count automatically.

Parameters
keyThe key of the resource (use Str2Key(res_name) to get the key).
Returns
the pointer to the resource; NULL if the resource does not exist.
See also
LoadResource, Str2Key

Referenced by GetWindowInfo().

const char * GetResPath ( void  )

Get the currrent user's resource path.

Returns
the user's resource path; NULL if have not been set.
See also
SetResPath

Referenced by GetWindowInfo().

void * LoadResource ( const char *  res_name,
int  type,
DWORD  usr_param 
)

Load a resource from disk or memory.

This function loads a resource from disk or memory. If the resource is loaded, it will return the buffered one and increase the reference count. This function will try to find a loader for the resource first according to type.

Parameters
res_nameThe resource name. If res_name is an absolute path (the leading character is '/'), it will load resource from disk directly, else it will:
  • step 1) try to find the resource in loaded buffer.
  • step 2) if step 1 failed, try to load from incore memory.
  • step 3) if step 2 failed, try to find the file in the path set by SetResPath and load it.
  • step 4) if step 3 failed, try to find the file in the path where MiniGUI.cfg locates.
  • step 5) return NULL if all steps faild
typeThe resource type what you want to load. It must be one of the following values:
  • RES_TYPE_IMAGE: A BITMAP object (BITMAP*).
  • RES_TYPE_MYBITMAP: A MYBITMAP object (MYBITMAP*).
  • RES_TYPE_ICON: An icon (HICON).
  • RES_TYPE_CURSOR: A cursor (HCURSOR).
  • RES_TYPE_ETC: A configuration (GHANDLE).
  • RES_TYPE_TEXT: NOT implemented.
  • RES_TYPE_MENU: NOT implemented.
  • RES_TYPE_WINDOW: NOT implemented.
  • RES_TYPE_MEM_RES: A in-memory resource (MEM_RES*).
  • RES_TYPE_USER ~ RES_TYPE_USER_MAX: A user-defined resource type (void*).
usr_paramThe param pass to RES_TYPE_OPS.get_res_data. For resource type RES_TYPE_IMAGE and RES_TYPE_ICON, it must be a handle to DC.
Returns
The pointer of resource, see the parameter type.
See also
enum emResType, MEM_RES, SetResPath, AddInnerRes, RegisterResType, GetResource

Referenced by GetWindowInfo().

BOOL GUIAPI RegisterResFromBitmap ( const char *  file,
const BITMAP bmp 
)

Register a device-dependent bitmap to bitmap cache.

This function register a device-dependent bitmap to bitmap cache.

Parameters
fileThe name of image file. The suffix indicates image type such as bmp, png, jpg etc.
bmpThe pointer to a BITMAP object.
Returns
TRUE on success, FALSE on error.

Referenced by GetWindowInfo().

BOOL GUIAPI RegisterResFromFile ( HDC  hdc,
const char *  file 
)

Register a device-dependent bitmap from a file.

This function load a device-dependent bitmap from a file and register it to bitmap cache.

Parameters
hdcThe device context.
fileThe name of image file. The suffix indicates image type such as bmp, png, jpg etc.
Returns
TRUE on success, FALSE on error.

Referenced by GetWindowInfo().

BOOL GUIAPI RegisterResFromMem ( HDC  hdc,
const char *  file,
const unsigned char *  data,
size_t  data_size 
)

Register a device-dependent bitmap to bitmap cache from memory.

This function load a device-dependent bitmap from memory and register it to bitmap cache.

Parameters
hdcThe device context.
fileThe name of image file. The suffix indicates image type such as bmp, png, jpg etc.
dataThe pointer to image data.
data_sizeThe size of image data.
Returns
TRUE on success, FALSE on error.

Referenced by GetWindowInfo().

int RegisterResType ( int  type,
RES_TYPE_OPS *  ops 
)

Register a new user-defined type into resource manager, so that the LoadResource can load the special resource automatically.

Parameters
typeThe user-defined type. It must >=RES_TYPE_USER and <RES_TYPE_USER_MAX
opsthe operations of the resource.
Returns
RES_RET_OK for success or error code
See also
RES_TYPE_OPS, enum emResType, UnregisterResType

Referenced by GetWindowInfo().

BOOL GUIAPI RegisterSystemBitmap ( HDC  hdc,
const char *  rdr_name,
const char *  id 
)

Register a device-dependent bitmap from id to BITMAP cache.

This function load a device-dependent bitmap from id and register it to BITMAP cache.

Parameters
hdcThe device context.
rdr_nameThe name of window element renderer. NULL for default renderer.
idThe id of system image.
Returns
TRUE on success, FALSE on error.

Referenced by GetWindowInfo().

int ReleaseRes ( RES_KEY  key)

Release the buffered resource. It will decrease the reference count of the resource. If the reference count is less then 0, the resource will be released.

Parameters
keyThe key of the resource (use Str2Key(res_name) to get the key).
Returns
The reference count; -1 if the resource does not exist.
See also
LoadResource, GetResource, AddResRef, Str2Key

Referenced by GetWindowInfo().

MG_EXPORT const BITMAP * RetrieveRes ( const char *  file)

Get a BITMAP object from cache according to the specified resource file name.

This function gets a BITMAP object from cache according to the specified resource file name file.

Parameters
fileThe specified file name.
Returns
a BITMAP object for success, NULL for error.

Referenced by GetWindowInfo().

int SetResPath ( const char *  path)

Set user's resource path into the search paths of resource manager.

If you set this value, resource mamanger will try to find a resource in the path.

Parameters
pathThe path which store the resources. It can be an absolute path or relative path.
Returns
RES_RET_OK for success or error code.
See also
GetResPath

Referenced by GetWindowInfo().

RES_KEY Str2Key ( const char *  str)

Translate a string to an unsigned long (RES_KEY), which is used to find a resource in the resource manager.

Parameters
strThe name of resource. Normaly, it's a path and filename of the resource.
Returns
The key.
See also
GetResource, AddResRef, ReleaseRes

Referenced by GetWindowInfo().

void UnregisterRes ( const char *  file)

Unregister the BITMAP object from cache according to the specified resource file name.

This function unregister the BITMAP object from cache according to the specified resource file name file and the BITMAP bmp.

Parameters
fileThe specified file name.
Returns
None.

Referenced by GetWindowInfo().

int UnregisterResType ( int  type)

Unregister a user-defined resource type.

Parameters
typeThe user-defined type registered by calling RegisterResType.
Returns
RES_RET_OK or error code
See also
RegisterResType

Referenced by GetWindowInfo().

void GUIAPI UnregisterSystemBitmap ( HDC  hdc,
const char *  rdr_name,
const char *  id 
)

Unregister a BITMAP object from BITMAP cache.

This function unregister a BITMAP object from BITMAP cache.

Parameters
hdcThe device context.
rdr_nameThe name of window element renderer. NULL for default renderer.
idThe id of system image.

Referenced by GetWindowInfo().