mCtrl  0.9.2
Typedefs
value.h File Reference

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

Go to the source code of this file.

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. More...
 
#define MC_VALUETYPEID_UINT32   2
 ID for 32-bit unsigned integer value type. More...
 
#define MC_VALUETYPEID_INT64   3
 ID for 64-bit signed integer value type. More...
 
#define MC_VALUETYPEID_UINT64   4
 ID for 64-bit unsigned integer value type. More...
 
#define MC_VALUETYPEID_STRINGW   5
 ID for unicode string value type. More...
 
#define MC_VALUETYPEID_STRINGA   6
 ID for ANSI string value type. More...
 
#define MC_VALUETYPEID_IMMSTRINGW   7
 ID for immutable Unicode string value type. More...
 
#define MC_VALUETYPEID_IMMSTRINGA   8
 ID for immutable ANSI string value type. More...
 
#define MC_VALUETYPEID_COLOR   9
 ID for color RGB triplet. More...
 
#define MC_VALUETYPEID_ICON   10
 ID for icon (HICON). More...
 

Value Type Functions

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

Value Functions

MC_HVALUETYPE mcValue_Type (const MC_HVALUE hValue)
 Gets a type of the value. More...
 
MC_HVALUE mcValue_Duplicate (const MC_HVALUE hValue)
 Creates a duplicate of the value. More...
 
void mcValue_Destroy (MC_HVALUE hValue)
 Destroys a value. More...
 

Int32 Value Functions

MC_HVALUE mcValue_CreateInt32 (INT iValue)
 Int32 factory function. More...
 
INT mcValue_GetInt32 (const MC_HVALUE hValue)
 Int32 getter function. More...
 

UInt32 Value Functions

MC_HVALUE mcValue_CreateUInt32 (UINT uValue)
 UInt32 factory function. More...
 
UINT mcValue_GetUInt32 (const MC_HVALUE hValue)
 UInt32 getter function. More...
 

Int64 Value Functions

MC_HVALUE mcValue_CreateInt64 (INT iValue)
 Int64 factory function. More...
 
INT mcValue_GetInt64 (const MC_HVALUE hValue)
 Int64 getter function. More...
 

UInt64 Value Functions

MC_HVALUE mcValue_CreateUInt64 (UINT uValue)
 UInt64 factory function. More...
 
UINT mcValue_GetUInt64 (const MC_HVALUE hValue)
 UInt64 getter function. More...
 

Unicode String Value Functions

MC_HVALUE mcValue_CreateStringW (const WCHAR *lpszStr)
 Unicode string factory function. More...
 
const WCHAR * mcValue_GetStringW (const MC_HVALUE hValue)
 Unicode string getter function. More...
 

@c ANSII String Value Functions

MC_HVALUE mcValue_CreateStringA (const char *lpszStr)
 ANSII string factory function. More...
 
const char * mcValue_GetStringA (const MC_HVALUE hValue)
 ANSII string getter function. More...
 

Unicode Immutable String Value Functions

MC_HVALUE mcValue_CreateImmStringW (const WCHAR *lpszStr)
 Unicode immutable string factory function. More...
 
const WCHAR * mcValue_GetImmStringW (const MC_HVALUE hValue)
 Unicode immutable string getter function. More...
 

ANSII Immutable String Value Functions

MC_HVALUE mcValue_CreateImmStringA (const char *lpszStr)
 ANSII immutable string factory function. More...
 
const char * mcValue_GetImmStringA (const MC_HVALUE hValue)
 ANSII immutable string getter function. More...
 

Color Value Functions

MC_HVALUE mcValue_CreateColor (COLORREF color)
 Color factory function. More...
 
COLORREF mcValue_GetColor (const MC_HVALUE hValue)
 Color getter function. More...
 

Icon Value Functions

MC_HVALUE mcValue_CreateIcon (HICON hIcon)
 Icon factory function. More...
 
HICON mcValue_GetIcon (const MC_HVALUE hValue)
 Icon getter function. More...
 

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]idThe 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]hValueThe 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]hValueThe value.
Returns
Duplicate of the value, or NULL on failure.
void mcValue_Destroy ( MC_HVALUE  hValue)

Destroys a value.

Parameters
[in]hValueThe value.
MC_HVALUE mcValue_CreateInt32 ( INT  iValue)

Int32 factory function.

Parameters
[in]iValueThe integer.
Returns
The value or NULL on failure.
INT mcValue_GetInt32 ( const MC_HVALUE  hValue)

Int32 getter function.

Parameters
[in]hValueThe 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]uValueThe integer.
Returns
The value or NULL on failure.
UINT mcValue_GetUInt32 ( const MC_HVALUE  hValue)

UInt32 getter function.

Parameters
[in]hValueThe 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]iValueThe integer.
Returns
The value or NULL on failure.
INT mcValue_GetInt64 ( const MC_HVALUE  hValue)

Int64 getter function.

Parameters
[in]hValueThe 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]uValueThe integer.
Returns
The value or NULL on failure.
UINT mcValue_GetUInt64 ( const MC_HVALUE  hValue)

UInt64 getter function.

Parameters
[in]hValueThe 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]lpszStrThe string.
Returns
The value or NULL on failure.
const WCHAR* mcValue_GetStringW ( const MC_HVALUE  hValue)

Unicode string getter function.

Parameters
[in]hValueThe value.
Returns
The string, or NULL on failure.
MC_HVALUE mcValue_CreateStringA ( const char *  lpszStr)

ANSII string factory function.

Parameters
[in]lpszStrThe string.
Returns
The value or NULL on failure.
const char* mcValue_GetStringA ( const MC_HVALUE  hValue)

ANSII string getter function.

Parameters
[in]hValueThe value.
Returns
The string, or NULL on failure.
MC_HVALUE mcValue_CreateImmStringW ( const WCHAR *  lpszStr)

Unicode immutable string factory function.

Parameters
[in]lpszStrThe string.
Returns
The value or NULL on failure.
const WCHAR* mcValue_GetImmStringW ( const MC_HVALUE  hValue)

Unicode immutable string getter function.

Parameters
[in]hValueThe value.
Returns
The string, or NULL on failure.
MC_HVALUE mcValue_CreateImmStringA ( const char *  lpszStr)

ANSII immutable string factory function.

Parameters
[in]lpszStrThe string.
Returns
The value or NULL on failure.
const char* mcValue_GetImmStringA ( const MC_HVALUE  hValue)

ANSII immutable string getter function.

Parameters
[in]hValueThe value.
Returns
The string, or NULL on failure.
MC_HVALUE mcValue_CreateColor ( COLORREF  color)

Color factory function.

Parameters
[in]colorThe color.
Returns
The value or NULL on failure.
COLORREF mcValue_GetColor ( const MC_HVALUE  hValue)

Color getter function.

Parameters
[in]hValueThe value.
Returns
The color, or MC_CLR_NONE on failure.
MC_HVALUE mcValue_CreateIcon ( HICON  hIcon)

Icon factory function.

Parameters
[in]hIconThe icon.
Returns
The value or NULL on failure.
HICON mcValue_GetIcon ( const MC_HVALUE  hValue)

Icon getter function.

Parameters
[in]hValueThe value.
Returns
The icon, or NULL on failure.