mCtrl/value.h File Reference

Polymorphic data (MC_VALUETYPE and MC_VALUE). More...

Go to the source code of this file.

Defines
ID of Built-in Value Types
Use these constants to get corresponding MC_VALUETYPE with function mcValueType_GetBuiltin().
#define	MC_VALUETYPE_ID_UNDEFINED   0
#define	MC_VALUETYPE_ID_INT32   1
	ID for 32-bit signed integer value type.
#define	MC_VALUETYPE_ID_UINT32   2
	ID for 32-bit unsigned integer value type.
#define	MC_VALUETYPE_ID_INT64   3
	ID for 64-bit signed integer value type.
#define	MC_VALUETYPE_ID_UINT64   4
	ID for 64-bit unsigned integer value type.
#define	MC_VALUETYPE_ID_STRINGW   5
	ID for unicode string value type.
#define	MC_VALUETYPE_ID_STRINGA   6
	ID for ANSI string value type.
#define	MC_VALUETYPE_ID_IMMSTRINGW   7
	ID for immutable Unicode string value type.
#define	MC_VALUETYPE_ID_IMMSTRINGA   8
	ID for immutable ANSI string value type.
#define	MC_VALUETYPE_ID_COLORREF   9
	ID for color RGB triplet.
#define	MC_VALUETYPE_ID_HICON   10
	ID for icon handle (HICON).
Unicode Resolution
#define	MC_VALUETYPE_ID_STRING   MC_VALUETYPE_ID_STRINGW
	Unicode-resolution alias.
#define	MC_VALUETYPE_ID_IMMSTRING   MC_VALUETYPE_ID_IMMSTRINGW
	Unicode-resolution alias.
#define	mcValue_CreateFromString   mcValue_CreateFromStringW
	Unicode-resolution alias.
#define	mcValue_CreateFromImmString   mcValue_CreateFromImmStringW
	Unicode-resolution alias.
#define	mcValue_GetString   mcValue_GetStringW
	Unicode-resolution alias.
#define	mcValue_GetImmString   mcValue_GetImmStringW
	Unicode-resolution alias.
Typedefs
typedef const void *	MC_VALUETYPE
typedef void *	MC_VALUE
Functions
MC_VALUETYPE MCTRL_API	mcValueType_GetBuiltin (int id)
	Retrieve Handle of a value type implemented in mCtrl.
Factory Functions
BOOL MCTRL_API	mcValue_CreateFromInt32 (MC_VALUE *phValue, INT iValue)
	Create a value holding 32-bit signed integer.
BOOL MCTRL_API	mcValue_CreateFromUInt32 (MC_VALUE *phValue, UINT uValue)
	Create a value holding 32-bit unsigned integer.
BOOL MCTRL_API	mcValue_CreateFromInt64 (MC_VALUE *phValue, INT64 i64Value)
	Create a value holding 64-bit signed integer.
BOOL MCTRL_API	mcValue_CreateFromUInt64 (MC_VALUE *phValue, UINT64 u64Value)
	Create a value holding 64-bit unsigned integer.
BOOL MCTRL_API	mcValue_CreateFromStringW (MC_VALUE *phValue, LPCWSTR lpStr)
	Create a value holding unicode string.
BOOL MCTRL_API	mcValue_CreateFromStringA (MC_VALUE *phValue, LPCSTR lpStr)
	Create a value holding ANSI string.
BOOL MCTRL_API	mcValue_CreateFromImmStringW (MC_VALUE *phValue, LPCWSTR lpStr)
	Create a value holding immutable Unicode string.
BOOL MCTRL_API	mcValue_CreateFromImmStringA (MC_VALUE *phValue, LPCSTR lpStr)
	Create a value holding immutable ANSI string.
BOOL MCTRL_API	mcValue_CreateFromColorref (MC_VALUE *phValue, COLORREF crColor)
	Create a value holding immutable RGB triplet (COLORREF).
BOOL MCTRL_API	mcValue_CreateFromHIcon (MC_VALUE *phValue, HICON hIcon)
	Create a value holding a handle to icon (HICON).
Getter Functions
INT MCTRL_API	mcValue_GetInt32 (const MC_VALUE hValue)
	Getter for 32-bit signed integer values.
UINT MCTRL_API	mcValue_GetUInt32 (const MC_VALUE hValue)
	Getter for 32-bit unsigned integer values.
INT64 MCTRL_API	mcValue_GetInt64 (const MC_VALUE hValue)
	Getter for 64-bit signed integer values.
UINT64 MCTRL_API	mcValue_GetUInt64 (const MC_VALUE hValue)
	Getter for 64-bit unsigned integer values.
LPCWSTR MCTRL_API	mcValue_GetStringW (const MC_VALUE hValue)
	Getter for unicode string values.
LPCSTR MCTRL_API	mcValue_GetStringA (const MC_VALUE hValue)
	Getter for ANSI string values.
LPCWSTR MCTRL_API	mcValue_GetImmStringW (const MC_VALUE hValue)
	Getter for immutable unicode string values.
LPCSTR MCTRL_API	mcValue_GetImmStringA (const MC_VALUE hValue)
	Getter for immutable ANSI string values.
COLORREF MCTRL_API	mcValue_GetColorref (const MC_VALUE hValue)
	Getter for color RGB triplet.
HICON MCTRL_API	mcValue_GetHIcon (const MC_VALUE hValue)
	Getter for icon handle.
Other Value Functions
BOOL MCTRL_API	mcValue_Duplicate (MC_VALUETYPE hType, MC_VALUE *phDest, const MC_VALUE hSrc)
	Duplicates a value.
void MCTRL_API	mcValue_Destroy (MC_VALUETYPE hType, MC_VALUE hValue)
	Destroys a value handle.

---

Detailed Description

Polymorphic data (MC_VALUETYPE and MC_VALUE).

Some controls are able to cope with data of multiple kinds. For example grid control (ref MC_WC_GRID) is able to present a table of cells where each cell contains another kind of data, e.g. string, numbers or some images (either bitmaps or icons) and much more.

MC_VALUETYPE and MC_VALUE is exactly the abstraction bringing this power to mCtrl. On one side MC_VALUE can contain various kinds of data (according to some MC_VALUETYPE), on the other side the abstraction allows the grid control to manage the values through single interface.

The type MC_VALUE is just an opaque type. It is in effect a handle of the particular piece of data. Therefore the application code cannot manipulate with the data directly but only through some functions.

MC_VALUETYPE is also an opaque type which determines how the values of that type behave. If you are familiar with object oriented programming you can imagine the type is a virtual method table, with the exception that here a pointer to the vtable is not part of the MC_VALUE data itself.

MC_VALUETYPE determines how the data of that type exactly behave. Almost all functions manipulating with some data take both, the MC_VALUE and MC_VALUETYPE as their parameters.

Note:

This is because MC_VALUE does not keep reference to its MC_VALUETYPE. On one side it would be more comfortable but it would make many useful value types much more memory hungry. Often some collections of data require all of their data to be of single type and in such cases tere can be only one variable of MC_VALUETYPE determining type of all data in the collection.

If you are familiar with object-oriented programming, you can roughly understand the MC_VALUETYPE as a class and MC_VALUE as an instance.

After the value is no longer needed, mcValue_Destroy() can be used to release any resources taken by the value.

Built-in Value Types

mCtrl provides value types for some very common kinds of data (e.g. integer numbers, strings etc.).

Values of each of these built-in value types can be created by the corresponding factory function. There is also a corresponding getter function which allows to get the data held by the value.

Note that for any given value you can only use the getter function corresponding to the value's type. Otherwise the behavior is undefined: it can even lead to an application crash.

ID	Factory function	Getter function	Description
MC_VALUETYPE_ID_UNDEFINED			Invalid type
MC_VALUETYPE_ID_INT32	mcValue_CreateFromInt32()	mcValue_GetInt32()	32-bit signed integer
MC_VALUETYPE_ID_UINT32	mcValue_CreateFromUInt32()	mcValue_GetUInt32()	32-bit unsigned integer
MC_VALUETYPE_ID_INT64	mcValue_CreateFromInt64()	mcValue_GetInt64()	64-bit signed integer
MC_VALUETYPE_ID_UINT64	mcValue_CreateFromUInt64()	mcValue_GetUInt64()	64-bit unsigned integer
MC_VALUETYPE_ID_STRINGW	mcValue_CreateFromStringW()	mcValue_GetStringW()	Unicode string
MC_VALUETYPE_ID_STRINGA	mcValue_CreateFromStringA()	mcValue_GetStringA()	ANSI string
MC_VALUETYPE_ID_IMMSTRINGW	mcValue_CreateFromImmStringW()	mcValue_GetImmStringW()	Unicode immutable string
MC_VALUETYPE_ID_IMMSTRINGA	mcValue_CreateFromImmStringA()	mcValue_GetImmStringA()	ANSI immutable string
MC_VALUETYPE_ID_COLORREF	mcValue_CreateFromColorref()	mcValue_GetColorref()	Color RGB triplet
MC_VALUETYPE_ID_HICON	mcValue_CreateFromHIcon()	mcValue_GetHIcon()	Icon handle

String Values

As the table of built-in value types above shows, there are four value types designed to hold strings, identified by the constants: -- "Ordinary strings" MC_VALUETYPE_ID_STRINGW and MC_VALUETYPE_ID_STRINGA -- "Immutable strings" MC_VALUETYPE_ID_IMMSTRINGW and MC_VALUETYPE_ID_IMMSTRINGA

There are also two Unicode/ANSI resolution macros MC_VALUETYPE_ID_STRING and MC_VALUETYPE_ID_IMMSTRING, one for the ordinary strings, the letter for the immutable ones.

The ordinary strings keep copies of the string buffers used during value creation, while the immutable strings only store pointers to original string buffers and they expect the buffer does not change during lifetime of the value.

As it is obvious from the description, the ordinary strings can be used for any strings, while work with the immutable strings can be much more effective but the application is responsible to guarantee immutability of the underlying string buffers pointed by them.

Values and @c NULL

Each value type guarantees that NULL is valid value of that type. Furthermore all the value types provide a guaranty that calling mcValue_Destroy() for NULL values is noop.

However it depends on the particular value type, how NULL values are interpreted. For the built-in types, it usually corresponds to 0 (zero), an empty string or NULL handle, depending on the nature of the value type.

---

Define Documentation

#define MC_VALUETYPE_ID_STRING   MC_VALUETYPE_ID_STRINGW

Unicode-resolution alias.

See also:

MC_VALUETYPE_ID_STRINGW MC_VALUETYPE_ID_STRINGA

#define MC_VALUETYPE_ID_IMMSTRING   MC_VALUETYPE_ID_IMMSTRINGW

Unicode-resolution alias.

See also:

MC_VALUETYPE_ID_IMMSTRINGW MC_VALUETYPE_ID_IMMSTRINGA

#define mcValue_CreateFromString   mcValue_CreateFromStringW

Unicode-resolution alias.

See also:

mcValue_CreateFromStringW mcValue_CreateFromStringA

#define mcValue_CreateFromImmString   mcValue_CreateFromImmStringW

Unicode-resolution alias.

See also:

mcValue_CreateFromImmStringW mcValue_CreateFromImmStringA

#define mcValue_GetString   mcValue_GetStringW

Unicode-resolution alias.

See also:

mcValue_GetStringW mcValue_GetStringA

#define mcValue_GetImmString   mcValue_GetImmStringW

Unicode-resolution alias.

See also:

mcValue_GetImmStringW mcValue_GetImmStringA

---

Typedef Documentation

typedef const void* MC_VALUETYPE

An opaque type representing the value type.

typedef void* MC_VALUE

An opaque type representing the value itself. The application is responsible to remember what's the type of the value.

---

Function Documentation

MC_VALUETYPE MCTRL_API mcValueType_GetBuiltin

(

int

id

)

Retrieve Handle of a value type implemented in mCtrl.

Parameters:

[in]

id

The identifier of the requested value type.

Returns:

The type handle corresponding to the id, or NULL. if the id is not supported.

BOOL MCTRL_API mcValue_CreateFromInt32	(	MC_VALUE *	phValue,
		INT	iValue
	)

Create a value holding 32-bit signed integer.

Parameters:

[out]	phValue	Filled with new value handle.
[in]	iValue	The integer.

Returns:

TRUE on success, FALSE on failure.

BOOL MCTRL_API mcValue_CreateFromUInt32	(	MC_VALUE *	phValue,
		UINT	uValue
	)

Create a value holding 32-bit unsigned integer.

Parameters:

[out]	phValue	Filled with new value handle.
[in]	uValue	The integer.

Returns:

TRUE on success, FALSE on failure.

BOOL MCTRL_API mcValue_CreateFromInt64	(	MC_VALUE *	phValue,
		INT64	i64Value
	)

Create a value holding 64-bit signed integer.

Parameters:

[out]	phValue	Filled with new value handle.
[in]	i64Value	The integer.

Returns:

TRUE on success, FALSE on failure.

BOOL MCTRL_API mcValue_CreateFromUInt64	(	MC_VALUE *	phValue,
		UINT64	u64Value
	)

Create a value holding 64-bit unsigned integer.

Parameters:

[out]	phValue	Filled with new value handle.
[in]	u64Value	The integer.

Returns:

TRUE on success, FALSE on failure.

BOOL MCTRL_API mcValue_CreateFromStringW	(	MC_VALUE *	phValue,
		LPCWSTR	lpStr
	)

Create a value holding unicode string.

Parameters:

[out]	phValue	Filled with new value handle.
[in]	lpStr	The string.

Returns:

TRUE on success, FALSE on failure.

BOOL MCTRL_API mcValue_CreateFromStringA	(	MC_VALUE *	phValue,
		LPCSTR	lpStr
	)

Create a value holding ANSI string.

Parameters:

[out]	phValue	Filled with new value handle.
[in]	lpStr	The string.

Returns:

TRUE on success, FALSE on failure.

BOOL MCTRL_API mcValue_CreateFromImmStringW	(	MC_VALUE *	phValue,
		LPCWSTR	lpStr
	)

Create a value holding immutable Unicode string.

Parameters:

[out]	phValue	Filled with new value handle.
[in]	lpStr	The string.

Returns:

TRUE on success, FALSE on failure.

BOOL MCTRL_API mcValue_CreateFromImmStringA	(	MC_VALUE *	phValue,
		LPCSTR	lpStr
	)

Create a value holding immutable ANSI string.

Parameters:

[out]	phValue	Filled with new value handle.
[in]	lpStr	The string.

Returns:

TRUE on success, FALSE on failure.

BOOL MCTRL_API mcValue_CreateFromColorref	(	MC_VALUE *	phValue,
		COLORREF	crColor
	)

Create a value holding immutable RGB triplet (COLORREF).

Parameters:

[out]	phValue	Filled with new value handle.
[in]	crColor	The RGB triplet.

Returns:

TRUE on success, FALSE on failure.

BOOL MCTRL_API mcValue_CreateFromHIcon	(	MC_VALUE *	phValue,
		HICON	hIcon
	)

Create a value holding a handle to icon (HICON).

Parameters:

[out]	phValue	Filled with new value handle.
[in]	hIcon	The icon handle.

Returns:

TRUE on success, FALSE on failure.

INT MCTRL_API mcValue_GetInt32

(

const MC_VALUE

hValue

)

Getter for 32-bit signed integer values.

Parameters:

[in]

hValue

The value. It must be of type MC_VALUETYPE_ID_INT32.

Returns:

The integer.

UINT MCTRL_API mcValue_GetUInt32

(

const MC_VALUE

hValue

)

Getter for 32-bit unsigned integer values.

Parameters:

[in]

hValue

The value. It must be of type MC_VALUETYPE_ID_UINT32.

Returns:

The integer.

INT64 MCTRL_API mcValue_GetInt64

(

const MC_VALUE

hValue

)

Getter for 64-bit signed integer values.

Parameters:

[in]

hValue

The value. It must be of type MC_VALUETYPE_ID_INT64.

Returns:

The integer.

UINT64 MCTRL_API mcValue_GetUInt64

(

const MC_VALUE

hValue

)

Getter for 64-bit unsigned integer values.

Parameters:

[in]

hValue

The value. It must be of type MC_VALUETYPE_ID_UINT64.

Returns:

The integer.

LPCWSTR MCTRL_API mcValue_GetStringW

(

const MC_VALUE

hValue

)

Getter for unicode string values.

Parameters:

[in]

hValue

The value. It must be of type MC_VALUETYPE_ID_STRINGW.

Returns:

Pointer to the buffer of the string.

LPCSTR MCTRL_API mcValue_GetStringA

(

const MC_VALUE

hValue

)

Getter for ANSI string values.

Parameters:

[in]

hValue

The value. It must be of type MC_VALUETYPE_ID_STRINGA.

Returns:

Pointer to the buffer of the string.

LPCWSTR MCTRL_API mcValue_GetImmStringW

(

const MC_VALUE

hValue

)

Getter for immutable unicode string values.

Parameters:

[in]

hValue

The value. It must be of type MC_VALUETYPE_ID_IMMSTRINGW.

Returns:

Pointer to the buffer of the string.

LPCSTR MCTRL_API mcValue_GetImmStringA

(

const MC_VALUE

hValue

)

Getter for immutable ANSI string values.

Parameters:

[in]

hValue

The value. It must be of type MC_VALUETYPE_ID_IMMSTRINGA.

Returns:

Pointer to the buffer of the string.

COLORREF MCTRL_API mcValue_GetColorref

(

const MC_VALUE

hValue

)

Getter for color RGB triplet.

Parameters:

[in]

hValue

The value. It must be of type MC_VALUETYPE_ID_COLORREF.

Returns:

The color RGB triplet.

HICON MCTRL_API mcValue_GetHIcon

(

const MC_VALUE

hValue

)

Getter for icon handle.

Parameters:

[in]

hValue

The value. It must be of type MC_VALUETYPE_ID_HICON.

Returns:

The icon handle.

BOOL MCTRL_API mcValue_Duplicate	(	MC_VALUETYPE	hType,
		MC_VALUE *	phDest,
		const MC_VALUE	hSrc
	)

Duplicates a value.

Parameters:

[in]	hType	Type of both the source and target value handles.
[out]	phDest	Filled with new value handle.
[in]	hSrc	Source value handle.

Returns:

TRUE on success, FALSE on failure.

void MCTRL_API mcValue_Destroy	(	MC_VALUETYPE	hType,
		MC_VALUE	hValue
	)

Destroys a value handle.

Parameters:

[in]	hType	Type of the source value.
[in]	hValue	The value.