Resource managment functions
[Functions]

Functions

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

  Register a device-dependent bitmap from a file.
  

• 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.
  

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

  Register a device-dependent bitmap to bitmap cache.
  

• MG_EXPORT const BITMAP *GUIAPI RetrieveRes (const char *file)

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

• MG_EXPORT void GUIAPI UnregisterRes (const char *file)

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

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

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

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

  Unregister a BITMAP object from BITMAP cache.
  

• MG_EXPORT int SetResPath (const char *path)

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

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

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

• MG_EXPORT int RegisterResType (int type, RES_TYPE_OPS *ops)

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

• MG_EXPORT int UnregisterResType (int type)

  Unregister a user-defined resource type.
  

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

  Load a resouce from disk or memory.
  

• MG_EXPORT void * GetResource (RES_KEY key)

  Retrive and return a buffered resouce by the key.
  

• MG_EXPORT int AddResRef (RES_KEY key)

  Increase the reference count of a buffered resouce.
  

• MG_EXPORT int ReleaseRes (RES_KEY key)

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

• MG_EXPORT RES_KEY Str2Key (const char *str)

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

---

Function Documentation

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

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

Parameters:

	inner_res	The pointer to the incore resouce.
	count	The bytes count of inner_res.
	copy	TRUE indicate that resouce manager will copy the value of inner_res array, otherwise, resouce manager just save the pointer to inner_res.

Returns:

RES_RET_OK for success or error code.

int AddResRef

(

RES_KEY

key

)

Increase the reference count of a buffered resouce.

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

Parameters:

key

The key of resouce (use Str2Key(res_name) to get the key).

Returns:

The reference count; -1 if the resouce does not exist.

See also:

LoadResouce, GetResouce, ReleaseRes, Str2Key

void * GetResource

(

RES_KEY

key

)

Retrive and return a buffered resouce by the key.

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

Parameters:

key

The key of the resouce.

Returns:

the pointer to the resouce; NULL if the resource does not exist.

See also:

LoadResouce, Str2Key

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

Load a resouce from disk or memory.

This function loads a resource from disk or memory. If the resouce 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_name	The resouce name. If res_name is an absolute path (the leading character is '/'), it will load resouce 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
	type	The 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_param	The 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 resouce, see the parameter type.

See also:

enum emResType, MEM_RES, SetResPath, AddInnerRes, RegisterResType, GetResouce

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:

	file	The name of image file. The suffix indicates image type such as bmp, png, jpg etc.
	bmp	The pointer to a BITMAP object.

Returns:

TRUE on success, FALSE on error.

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:

	hdc	The device context.
	file	The name of image file. The suffix indicates image type such as bmp, png, jpg etc.

Returns:

TRUE on success, FALSE on error.

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:

	hdc	The device context.
	file	The name of image file. The suffix indicates image type such as bmp, png, jpg etc.
	data	The pointer to image data.
	data_size	The size of image data.

Returns:

TRUE on success, FALSE on error.

int RegisterResType	(	int	type,
		RES_TYPE_OPS *	ops
	)

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

Parameters:

	type	The user-defined type. It must >=RES_TYPE_USER and <RES_TYPE_USER_MAX
	ops	the operations of the resouce.

Returns:

RES_RET_OK for success or error code

See also:

RES_TYPE_OPS, enum emResType, UnregisterResType

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:

	hdc	The device context.
	rdr_name	The name of window element renderer. NULL for default renderer.
	id	The id of system image.

Returns:

TRUE on success, FALSE on error.

int ReleaseRes

(

RES_KEY

key

)

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

Parameters:

key

The key of the resouce (use Str2Key(res_name) to get the key).

Returns:

The reference count; -1 if the resouce does not exist.

See also:

LoadResouce, GetResouce, AddResRef, Str2Key

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:

file

The specified file name.

Returns:

a BITMAP object for success, NULL for error.

int SetResPath

(

const char *

path

)

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

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

Parameters:

path

The path which store the resouces. It can be an absolute path or relative path.

Returns:

RES_RET_OK for success or error code.

RES_KEY Str2Key

(

const char *

str

)

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

Parameters:

str

The name of resouce. Normaly, it's a path and filename of the resouce.

Returns:

The key.

See also:

GetResouce, AddResRef, ReleaseRes

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:

file

The specified file name.

Returns:

None.

int UnregisterResType

(

int

type

)

Unregister a user-defined resource type.

Parameters:

type

The user-defined type registered by calling RegisterResType.

Returns:

RES_RET_OK or error code

See also:

RegisterResType

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:

	hdc	The device context.
	rdr_name	The name of window element renderer. NULL for default renderer.
	id	The id of system image.