mCtrl
Typedefs | Functions
value.h File Reference

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

Go to the source code of this file.

Macros

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_COLORREF   9
 ID for color RGB triplet.
 
#define MC_VALUETYPEID_HICON   10
 ID for icon handle (HICON).
 
Unicode Resolution
#define MC_VALUETYPEID_STRING   MCTRL_NAME_AW(MC_VALUETYPEID_STRING)
 Unicode-resolution alias.
 
#define MC_VALUETYPEID_IMMSTRING   MCTRL_NAME_AW(MC_VALUETYPEID_IMMSTRING)
 Unicode-resolution alias.
 
#define mcValue_CreateFromString   MCTRL_NAME_AW(mcValue_CreateFromString)
 Unicode-resolution alias.
 
#define mcValue_CreateFromImmString   MCTRL_NAME_AW(mcValue_CreateFromImmString)
 Unicode-resolution alias.
 
#define mcValue_GetString   MCTRL_NAME_AW(mcValue_GetString)
 Unicode-resolution alias.
 
#define mcValue_GetImmString   MCTRL_NAME_AW(mcValue_GetImmString)
 Unicode-resolution alias.
 

Typedefs

typedef const void * MC_HVALUETYPE
 
typedef void * MC_HVALUE
 

Functions

MC_HVALUETYPE MCTRL_API mcValueType_GetBuiltin (int id)
 Retrieve Handle of a value type implemented in mCtrl.
 
Factory Functions
BOOL MCTRL_API mcValue_CreateFromInt32 (MC_HVALUE *phValue, INT iValue)
 Create a value holding 32-bit signed integer.
 
BOOL MCTRL_API mcValue_CreateFromUInt32 (MC_HVALUE *phValue, UINT uValue)
 Create a value holding 32-bit unsigned integer.
 
BOOL MCTRL_API mcValue_CreateFromInt64 (MC_HVALUE *phValue, INT64 i64Value)
 Create a value holding 64-bit signed integer.
 
BOOL MCTRL_API mcValue_CreateFromUInt64 (MC_HVALUE *phValue, UINT64 u64Value)
 Create a value holding 64-bit unsigned integer.
 
BOOL MCTRL_API mcValue_CreateFromStringW (MC_HVALUE *phValue, LPCWSTR lpStr)
 Create a value holding unicode string.
 
BOOL MCTRL_API mcValue_CreateFromStringA (MC_HVALUE *phValue, LPCSTR lpStr)
 Create a value holding ANSI string.
 
BOOL MCTRL_API mcValue_CreateFromImmStringW (MC_HVALUE *phValue, LPCWSTR lpStr)
 Create a value holding immutable Unicode string.
 
BOOL MCTRL_API mcValue_CreateFromImmStringA (MC_HVALUE *phValue, LPCSTR lpStr)
 Create a value holding immutable ANSI string.
 
BOOL MCTRL_API mcValue_CreateFromColorref (MC_HVALUE *phValue, COLORREF crColor)
 Create a value holding immutable RGB triplet (COLORREF).
 
BOOL MCTRL_API mcValue_CreateFromHIcon (MC_HVALUE *phValue, HICON hIcon)
 Create a value holding a handle to icon (HICON).
 
Getter Functions
INT MCTRL_API mcValue_GetInt32 (const MC_HVALUE hValue)
 Getter for 32-bit signed integer values.
 
UINT MCTRL_API mcValue_GetUInt32 (const MC_HVALUE hValue)
 Getter for 32-bit unsigned integer values.
 
INT64 MCTRL_API mcValue_GetInt64 (const MC_HVALUE hValue)
 Getter for 64-bit signed integer values.
 
UINT64 MCTRL_API mcValue_GetUInt64 (const MC_HVALUE hValue)
 Getter for 64-bit unsigned integer values.
 
LPCWSTR MCTRL_API mcValue_GetStringW (const MC_HVALUE hValue)
 Getter for unicode string values.
 
LPCSTR MCTRL_API mcValue_GetStringA (const MC_HVALUE hValue)
 Getter for ANSI string values.
 
LPCWSTR MCTRL_API mcValue_GetImmStringW (const MC_HVALUE hValue)
 Getter for immutable unicode string values.
 
LPCSTR MCTRL_API mcValue_GetImmStringA (const MC_HVALUE hValue)
 Getter for immutable ANSI string values.
 
COLORREF MCTRL_API mcValue_GetColorref (const MC_HVALUE hValue)
 Getter for color RGB triplet.
 
HICON MCTRL_API mcValue_GetHIcon (const MC_HVALUE hValue)
 Getter for icon handle.
 
Other Value Functions
BOOL MCTRL_API mcValue_Duplicate (MC_HVALUETYPE hType, MC_HVALUE *phDest, const MC_HVALUE hSrc)
 Duplicates a value.
 
void MCTRL_API mcValue_Destroy (MC_HVALUETYPE hType, MC_HVALUE hValue)
 Destroys a value handle.
 

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 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, with the exception that here a pointer to the vtable is not part of the MC_HVALUE data itself.

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

Note
This is because MC_HVALUE does not keep reference to its MC_HVALUETYPE. 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_HVALUETYPE determining type of all data in the collection.

If you are familiar with object-oriented programming, you can roughly understand the MC_HVALUETYPE as a class and MC_HVALUE 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.

IDFactory functionGetter functionDescription
MC_VALUETYPEID_UNDEFINED Invalid type
MC_VALUETYPEID_INT32mcValue_CreateFromInt32()mcValue_GetInt32()32-bit signed integer
MC_VALUETYPEID_UINT32mcValue_CreateFromUInt32()mcValue_GetUInt32()32-bit unsigned integer
MC_VALUETYPEID_INT64mcValue_CreateFromInt64()mcValue_GetInt64()64-bit signed integer
MC_VALUETYPEID_UINT64mcValue_CreateFromUInt64()mcValue_GetUInt64()64-bit unsigned integer
MC_VALUETYPEID_STRINGWmcValue_CreateFromStringW()mcValue_GetStringW()Unicode string
MC_VALUETYPEID_STRINGAmcValue_CreateFromStringA()mcValue_GetStringA()ANSI string
MC_VALUETYPEID_IMMSTRINGWmcValue_CreateFromImmStringW()mcValue_GetImmStringW()Unicode immutable string
MC_VALUETYPEID_IMMSTRINGAmcValue_CreateFromImmStringA()mcValue_GetImmStringA()ANSI immutable string
MC_VALUETYPEID_COLORREFmcValue_CreateFromColorref()mcValue_GetColorref()Color RGB triplet
MC_VALUETYPEID_HICONmcValue_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_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, 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.

Macro Definition Documentation

#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_CreateFromString   MCTRL_NAME_AW(mcValue_CreateFromString)

Unicode-resolution alias.

See Also
mcValue_CreateFromStringW mcValue_CreateFromStringA
#define mcValue_CreateFromImmString   MCTRL_NAME_AW(mcValue_CreateFromImmString)
#define mcValue_GetString   MCTRL_NAME_AW(mcValue_GetString)

Unicode-resolution alias.

See Also
mcValue_GetStringW mcValue_GetStringA
#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 MCTRL_API mcValueType_GetBuiltin ( int  id)

Retrieve Handle of a value type implemented in mCtrl.

Parameters
[in]idThe 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_HVALUE phValue,
INT  iValue 
)

Create a value holding 32-bit signed integer.

Parameters
[out]phValueFilled with new value handle.
[in]iValueThe integer.
Returns
TRUE on success, FALSE on failure.
BOOL MCTRL_API mcValue_CreateFromUInt32 ( MC_HVALUE phValue,
UINT  uValue 
)

Create a value holding 32-bit unsigned integer.

Parameters
[out]phValueFilled with new value handle.
[in]uValueThe integer.
Returns
TRUE on success, FALSE on failure.
BOOL MCTRL_API mcValue_CreateFromInt64 ( MC_HVALUE phValue,
INT64  i64Value 
)

Create a value holding 64-bit signed integer.

Parameters
[out]phValueFilled with new value handle.
[in]i64ValueThe integer.
Returns
TRUE on success, FALSE on failure.
BOOL MCTRL_API mcValue_CreateFromUInt64 ( MC_HVALUE phValue,
UINT64  u64Value 
)

Create a value holding 64-bit unsigned integer.

Parameters
[out]phValueFilled with new value handle.
[in]u64ValueThe integer.
Returns
TRUE on success, FALSE on failure.
BOOL MCTRL_API mcValue_CreateFromStringW ( MC_HVALUE phValue,
LPCWSTR  lpStr 
)

Create a value holding unicode string.

Parameters
[out]phValueFilled with new value handle.
[in]lpStrThe string.
Returns
TRUE on success, FALSE on failure.
BOOL MCTRL_API mcValue_CreateFromStringA ( MC_HVALUE phValue,
LPCSTR  lpStr 
)

Create a value holding ANSI string.

Parameters
[out]phValueFilled with new value handle.
[in]lpStrThe string.
Returns
TRUE on success, FALSE on failure.
BOOL MCTRL_API mcValue_CreateFromImmStringW ( MC_HVALUE phValue,
LPCWSTR  lpStr 
)

Create a value holding immutable Unicode string.

Parameters
[out]phValueFilled with new value handle.
[in]lpStrThe string.
Returns
TRUE on success, FALSE on failure.
BOOL MCTRL_API mcValue_CreateFromImmStringA ( MC_HVALUE phValue,
LPCSTR  lpStr 
)

Create a value holding immutable ANSI string.

Parameters
[out]phValueFilled with new value handle.
[in]lpStrThe string.
Returns
TRUE on success, FALSE on failure.
BOOL MCTRL_API mcValue_CreateFromColorref ( MC_HVALUE phValue,
COLORREF  crColor 
)

Create a value holding immutable RGB triplet (COLORREF).

Parameters
[out]phValueFilled with new value handle.
[in]crColorThe RGB triplet.
Returns
TRUE on success, FALSE on failure.
BOOL MCTRL_API mcValue_CreateFromHIcon ( MC_HVALUE phValue,
HICON  hIcon 
)

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

Parameters
[out]phValueFilled with new value handle.
[in]hIconThe icon handle.
Returns
TRUE on success, FALSE on failure.
INT MCTRL_API mcValue_GetInt32 ( const MC_HVALUE  hValue)

Getter for 32-bit signed integer values.

Parameters
[in]hValueThe value. It must be of type MC_VALUETYPEID_INT32.
Returns
The integer.
UINT MCTRL_API mcValue_GetUInt32 ( const MC_HVALUE  hValue)

Getter for 32-bit unsigned integer values.

Parameters
[in]hValueThe value. It must be of type MC_VALUETYPEID_UINT32.
Returns
The integer.
INT64 MCTRL_API mcValue_GetInt64 ( const MC_HVALUE  hValue)

Getter for 64-bit signed integer values.

Parameters
[in]hValueThe value. It must be of type MC_VALUETYPEID_INT64.
Returns
The integer.
UINT64 MCTRL_API mcValue_GetUInt64 ( const MC_HVALUE  hValue)

Getter for 64-bit unsigned integer values.

Parameters
[in]hValueThe value. It must be of type MC_VALUETYPEID_UINT64.
Returns
The integer.
LPCWSTR MCTRL_API mcValue_GetStringW ( const MC_HVALUE  hValue)

Getter for unicode string values.

Parameters
[in]hValueThe value. It must be of type MC_VALUETYPEID_STRINGW.
Returns
Pointer to the buffer of the string.
LPCSTR MCTRL_API mcValue_GetStringA ( const MC_HVALUE  hValue)

Getter for ANSI string values.

Parameters
[in]hValueThe value. It must be of type MC_VALUETYPEID_STRINGA.
Returns
Pointer to the buffer of the string.
LPCWSTR MCTRL_API mcValue_GetImmStringW ( const MC_HVALUE  hValue)

Getter for immutable unicode string values.

Parameters
[in]hValueThe value. It must be of type MC_VALUETYPEID_IMMSTRINGW.
Returns
Pointer to the buffer of the string.
LPCSTR MCTRL_API mcValue_GetImmStringA ( const MC_HVALUE  hValue)

Getter for immutable ANSI string values.

Parameters
[in]hValueThe value. It must be of type MC_VALUETYPEID_IMMSTRINGA.
Returns
Pointer to the buffer of the string.
COLORREF MCTRL_API mcValue_GetColorref ( const MC_HVALUE  hValue)

Getter for color RGB triplet.

Parameters
[in]hValueThe value. It must be of type MC_VALUETYPEID_COLORREF.
Returns
The color RGB triplet.
HICON MCTRL_API mcValue_GetHIcon ( const MC_HVALUE  hValue)

Getter for icon handle.

Parameters
[in]hValueThe value. It must be of type MC_VALUETYPEID_HICON.
Returns
The icon handle.
BOOL MCTRL_API mcValue_Duplicate ( MC_HVALUETYPE  hType,
MC_HVALUE phDest,
const MC_HVALUE  hSrc 
)

Duplicates a value.

Parameters
[in]hTypeType of both the source and target value handles.
[out]phDestFilled with new value handle.
[in]hSrcSource value handle.
Returns
TRUE on success, FALSE on failure.
void MCTRL_API mcValue_Destroy ( MC_HVALUETYPE  hType,
MC_HVALUE  hValue 
)

Destroys a value handle.

Parameters
[in]hTypeType of the source value.
[in]hValueThe value.