Polymorphic data (MC_HVALUETYPE and MC_HVALUE). More...

Typedefs
typedef const void *	MC_HVALUETYPE

typedef void *	MC_HVALUE

ID of Built-in Value Types
Use these constants to get corresponding MC_HVALUETYPE with function mcValueType_GetBuiltin().
#define	MC_VALUETYPEID_UNDEFINED 0

#define	MC_VALUETYPEID_INT32 1
	ID for 32-bit signed integer value type.

#define	MC_VALUETYPEID_UINT32 2
	ID for 32-bit unsigned integer value type.

#define	MC_VALUETYPEID_INT64 3
	ID for 64-bit signed integer value type.

#define	MC_VALUETYPEID_UINT64 4
	ID for 64-bit unsigned integer value type.

#define	MC_VALUETYPEID_STRINGW 5
	ID for unicode string value type.

#define	MC_VALUETYPEID_STRINGA 6
	ID for ANSI string value type.

#define	MC_VALUETYPEID_IMMSTRINGW 7
	ID for immutable Unicode string value type.

#define	MC_VALUETYPEID_IMMSTRINGA 8
	ID for immutable ANSI string value type.

#define	MC_VALUETYPEID_COLOR 9
	ID for color RGB triplet.

#define	MC_VALUETYPEID_ICON 10
	ID for icon (`HICON`).

Value Type Functions
MC_HVALUETYPE	mcValueType_GetBuiltin (int id)
	Retrieve Handle of a value type implemented in mCtrl.

Value Functions
MC_HVALUETYPE	mcValue_Type (const MC_HVALUE hValue)
	Gets a type of the value.

MC_HVALUE	mcValue_Duplicate (const MC_HVALUE hValue)
	Creates a duplicate of the value.

void	mcValue_Destroy (MC_HVALUE hValue)
	Destroys a value.

Int32 Value Functions
MC_HVALUE	mcValue_CreateInt32 (INT iValue)
	Int32 factory function.

INT	mcValue_GetInt32 (const MC_HVALUE hValue)
	Int32 getter function.

UInt32 Value Functions
MC_HVALUE	mcValue_CreateUInt32 (UINT uValue)
	UInt32 factory function.

UINT	mcValue_GetUInt32 (const MC_HVALUE hValue)
	UInt32 getter function.

Int64 Value Functions
MC_HVALUE	mcValue_CreateInt64 (INT iValue)
	Int64 factory function.

INT	mcValue_GetInt64 (const MC_HVALUE hValue)
	Int64 getter function.

UInt64 Value Functions
MC_HVALUE	mcValue_CreateUInt64 (UINT uValue)
	UInt64 factory function.

UINT	mcValue_GetUInt64 (const MC_HVALUE hValue)
	UInt64 getter function.

Unicode String Value Functions
MC_HVALUE	mcValue_CreateStringW (const WCHAR *lpszStr)
	Unicode string factory function.

const WCHAR *	mcValue_GetStringW (const MC_HVALUE hValue)
	Unicode string getter function.

@c ANSII String Value Functions
MC_HVALUE	mcValue_CreateStringA (const char *lpszStr)
	ANSII string factory function.

const char *	mcValue_GetStringA (const MC_HVALUE hValue)
	ANSII string getter function.

Unicode Immutable String Value Functions
MC_HVALUE	mcValue_CreateImmStringW (const WCHAR *lpszStr)
	Unicode immutable string factory function.

const WCHAR *	mcValue_GetImmStringW (const MC_HVALUE hValue)
	Unicode immutable string getter function.

ANSII Immutable String Value Functions
MC_HVALUE	mcValue_CreateImmStringA (const char *lpszStr)
	ANSII immutable string factory function.

const char *	mcValue_GetImmStringA (const MC_HVALUE hValue)
	ANSII immutable string getter function.

Color Value Functions
MC_HVALUE	mcValue_CreateColor (COLORREF color)
	Color factory function.

COLORREF	mcValue_GetColor (const MC_HVALUE hValue)
	Color getter function.

Icon Value Functions
MC_HVALUE	mcValue_CreateIcon (HICON hIcon)
	Icon factory function.

HICON	mcValue_GetIcon (const MC_HVALUE hValue)
	Icon getter function.

Unicode Resolution
#define	MC_VALUETYPEID_STRING MCTRL_NAME_AW(MC_VALUETYPEID_STRING)

#define	MC_VALUETYPEID_IMMSTRING MCTRL_NAME_AW(MC_VALUETYPEID_IMMSTRING)

#define	mcValue_CreateString MCTRL_NAME_AW(mcValue_CreateString)

#define	mcValue_GetString MCTRL_NAME_AW(mcValue_GetString)

#define	mcValue_CreateImmString MCTRL_NAME_AW(mcValue_CreateImmString)

#define	mcValue_GetImmString MCTRL_NAME_AW(mcValue_GetImmString)

Detailed Description

Polymorphic data (MC_HVALUETYPE and MC_HVALUE).

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_HVALUETYPE and MC_HVALUE is exactly the abstraction bringing this power to mCtrl. On one side MC_HVALUE can contain various kinds of data (according to some MC_HVALUETYPE), on the other side the abstraction allows the grid control to manage the values through a single interface.

The type MC_HVALUE 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_HVALUETYPE 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 (or vtable in short).

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

Value Life Time

As said above, from applications point of view the values are represented by an opaque type MC_HVALUE. It is just an handle to the value.

It is usually usewful to pass the handle here or there in application but the applcation has to be designed in a way that it is clear who owns the handle, i.e. when it can be safely destroyed.

Also note the when an application asks for a value from some control (e.g. grid, ref MC_WC_GRID) or a data model (e.g. table, MC_HTABLE), it usually gets a const MC_HVALUE. It is directly the handle managed by the control, not its copy. The application should not store the value handle as there is no guaranty when the control or data model respectivelly will reset the value, or even destroy it.

If the application needs to store the information represented by the value, it is supposed to make a duplicate of the value with mcValue_Duplicate(), or call (appropriate) getter value and store the information itself.

Built-in Value Types

mCtrl provides value types for some very common kinds of data like integer numbers, strings etc.

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

String Values

There are four value types designed to hold strings, identified by the constants: – "Ordinary strings" MC_VALUETYPEID_STRINGW and MC_VALUETYPEID_STRINGA – "Immutable strings" MC_VALUETYPEID_IMMSTRINGW and MC_VALUETYPEID_IMMSTRINGA

There are also two Unicode/ANSI resolution macros MC_VALUETYPEID_STRING and MC_VALUETYPEID_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 but can bring a penalty of higher memory usage, while work with the immutable strings make the application responsible to guarantee immutability of the underlying string buffers pointed by them.

Macro Definition Documentation

#define MC_VALUETYPEID_INT32 1

ID for 32-bit signed integer value type.

#define MC_VALUETYPEID_UINT32 2

ID for 32-bit unsigned integer value type.

#define MC_VALUETYPEID_INT64 3

ID for 64-bit signed integer value type.

#define MC_VALUETYPEID_UINT64 4

ID for 64-bit unsigned integer value type.

#define MC_VALUETYPEID_STRINGW 5

ID for unicode string value type.

#define MC_VALUETYPEID_STRINGA 6

ID for ANSI string value type.

#define MC_VALUETYPEID_IMMSTRINGW 7

ID for immutable Unicode string value type.

#define MC_VALUETYPEID_IMMSTRINGA 8

ID for immutable ANSI string value type.

#define MC_VALUETYPEID_COLOR 9

ID for color RGB triplet.

#define MC_VALUETYPEID_ICON 10

ID for icon (HICON).

#define MC_VALUETYPEID_STRING MCTRL_NAME_AW(MC_VALUETYPEID_STRING)

Unicode-resolution alias.

See Also: MC_VALUETYPEID_STRINGW MC_VALUETYPEID_STRINGA

#define MC_VALUETYPEID_IMMSTRING MCTRL_NAME_AW(MC_VALUETYPEID_IMMSTRING)

Unicode-resolution alias.

See Also: MC_VALUETYPEID_IMMSTRINGW MC_VALUETYPEID_IMMSTRINGA

#define mcValue_CreateString MCTRL_NAME_AW(mcValue_CreateString)

Unicode-resolution alias.

See Also: mcValue_CreateStringW mcValue_CreateStringA

#define mcValue_GetString MCTRL_NAME_AW(mcValue_GetString)

Unicode-resolution alias.

See Also: mcValue_GetStringW mcValue_GetStringA

#define mcValue_CreateImmString MCTRL_NAME_AW(mcValue_CreateImmString)

Unicode-resolution alias.

See Also: mcValue_CreateImmStringW mcValue_CreateImmStringA

#define mcValue_GetImmString MCTRL_NAME_AW(mcValue_GetImmString)

Unicode-resolution alias.

See Also: mcValue_GetImmStringW mcValue_GetImmStringA

Typedef Documentation

typedef const void* MC_HVALUETYPE

An opaque type representing the value type.

typedef void* MC_HVALUE

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

Function Documentation

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

MC_HVALUETYPE mcValue_Type ( const MC_HVALUE hValue )

Gets a type of the value.

Parameters

[in] hValue The value.

Returns: The value type handle, or NULL on failure.

MC_HVALUE mcValue_Duplicate ( const MC_HVALUE hValue )

Creates a duplicate of the value.

Parameters

[in] hValue The value.

Returns: Duplicate of the value, or NULL on failure.

void mcValue_Destroy ( MC_HVALUE hValue )

Destroys a value.

Parameters

[in] hValue The value.

MC_HVALUE mcValue_CreateInt32 ( INT iValue )

Int32 factory function.

Parameters

[in] iValue The integer.

Returns: The value or NULL on failure.

INT mcValue_GetInt32 ( const MC_HVALUE hValue )

Int32 getter function.

Parameters

[in] hValue The value.

Returns: The integer, or -1 on failure.

Note: You may need to call GetLastError() to distinguish whether -1 is the value or an error indication.

MC_HVALUE mcValue_CreateUInt32 ( UINT uValue )

UInt32 factory function.

Parameters

[in] uValue The integer.

Returns: The value or NULL on failure.

UINT mcValue_GetUInt32 ( const MC_HVALUE hValue )

UInt32 getter function.

Parameters

[in] hValue The value.

Returns: The integer, or 0xffffffff on failure.

Note: You may need to call GetLastError() to distinguish whether 0xffffffff is the value or an error indication.

MC_HVALUE mcValue_CreateInt64 ( INT iValue )

Int64 factory function.

Parameters

[in] iValue The integer.

Returns: The value or NULL on failure.

INT mcValue_GetInt64 ( const MC_HVALUE hValue )

Int64 getter function.

Parameters

[in] hValue The value.

Returns: The integer, or -1 on failure.

Note: You may need to call GetLastError() to distinguish whether -1 is the value or an error indication.

MC_HVALUE mcValue_CreateUInt64 ( UINT uValue )

UInt64 factory function.

Parameters

[in] uValue The integer.

Returns: The value or NULL on failure.

UINT mcValue_GetUInt64 ( const MC_HVALUE hValue )

UInt64 getter function.

Parameters

[in] hValue The value.

Returns: The integer, or 0xffffffff on failure.

Note: You may need to call GetLastError() to distinguish whether 0xffffffff is the value or an error indication.

MC_HVALUE mcValue_CreateStringW ( const WCHAR * lpszStr )

Unicode string factory function.

Parameters

[in] lpszStr The string.

Returns: The value or NULL on failure.

const WCHAR* mcValue_GetStringW ( const MC_HVALUE hValue )

Unicode string getter function.

Parameters

[in] hValue The value.

Returns: The string, or NULL on failure.

MC_HVALUE mcValue_CreateStringA ( const char * lpszStr )

ANSII string factory function.

Parameters

[in] lpszStr The string.

Returns: The value or NULL on failure.

const char* mcValue_GetStringA ( const MC_HVALUE hValue )

ANSII string getter function.

Parameters

[in] hValue The value.

Returns: The string, or NULL on failure.

MC_HVALUE mcValue_CreateImmStringW ( const WCHAR * lpszStr )

Unicode immutable string factory function.

Parameters

[in] lpszStr The string.

Returns: The value or NULL on failure.

const WCHAR* mcValue_GetImmStringW ( const MC_HVALUE hValue )

Unicode immutable string getter function.

Parameters

[in] hValue The value.

Returns: The string, or NULL on failure.

MC_HVALUE mcValue_CreateImmStringA ( const char * lpszStr )

ANSII immutable string factory function.

Parameters

[in] lpszStr The string.

Returns: The value or NULL on failure.

const char* mcValue_GetImmStringA ( const MC_HVALUE hValue )

ANSII immutable string getter function.

Parameters

[in] hValue The value.

Returns: The string, or NULL on failure.

MC_HVALUE mcValue_CreateColor ( COLORREF color )

Color factory function.

Parameters

[in] color The color.

Returns: The value or NULL on failure.

COLORREF mcValue_GetColor ( const MC_HVALUE hValue )

Color getter function.

Parameters

[in] hValue The value.

Returns: The color, or MC_CLR_NONE on failure.

MC_HVALUE mcValue_CreateIcon ( HICON hIcon )

Icon factory function.

Parameters

[in] hIcon The icon.

Returns: The value or NULL on failure.

HICON mcValue_GetIcon ( const MC_HVALUE hValue )

Icon getter function.

Parameters

[in] hValue The value.

Returns: The icon, or NULL on failure.

Typedefs

ID of Built-in Value Types

Value Type Functions

Value Functions

Int32 Value Functions

UInt32 Value Functions

Int64 Value Functions

UInt64 Value Functions

Unicode String Value Functions

@c ANSII String Value Functions

Unicode Immutable String Value Functions

ANSII Immutable String Value Functions

Color Value Functions

Icon Value Functions

Unicode Resolution

Detailed Description

Value Life Time

Built-in Value Types

String Values

Macro Definition Documentation

Typedef Documentation

Function Documentation