mCtrl/value.h File Reference

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

Go to the source code of this file.

Detailed Description

Polymorphic data (MC_VALUETYPE and MC_VALUE).

Some controls are able to cope with large and extensible set of data types. For example grid control (ref MC_WC_GRID) is able to present a table of cells where each cell contains another kind of data.

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

MC_VALUE is 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 indirectly.

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.

Basic Usage

Most applications will be quite happy with the ability to create (and free) the values and provide them to some control for displaying them and manipulating them.

There is quite a large set of factory functions which create values of some type. The type is determined implicitly by the factory function used.

Then the value is just passed to the control which will display it and potentially alter it. Then in some moment (e.g. when user clicks on OK button) your application can retrieve the value from the control, call a getter function on it to get the actual data from the value.

Please note you have to use a getter method which corresponds to the type of the value. Otherwise the behavior is undefined and your application can even crash.

This is also the case when any universal function manipulating with the value is called. Such function expect MC_VALUETYPE as their first parameter.

When you are done with the value you have to release any resources taken by it with mcValueRelease(). This function also expects MC_VALUETYPE as its first parameter.

Defining New Value Type

Your application can provide new types of values if there is no appropriate built-in type. This in effect extends functionality of controls which work with the values.


Derived Value Types

Furthermore there are functions which create new value types in run time by deriving them from an existing type.

For example it is possible to create a new enumeration type of some basic type (e.g. string). The values of the new type then can only be set to a value equal to one of the values named during deriving of the type.


Built-in Types

int 32-bit signed integermcValueCreateInt()mcValueGetInt()
UINT 32-bit unsigned integermcValueCreateUInt()mcValueGetUInt()
INT64 64-bit signed integermcValueCreateInt64()mcValueGetInt64()
UINT64 64-bit unsigned integermcValueCreateUInt64()mcValueGetUInt64()
LPCWSTR Unicode stringmcValueCreateStringW()mcValueGetStringW()
LPCSTR ANSI stringmcValueCreateStringA()mcValueGetStringA()
LPCWSTR Unicode immutable stringmcValueCreateImmStringW()mcValueGetImmStringW()
LPCSTR ANSI immutable stringmcValueCreateImmStringA()mcValueGetImmStringA()
COLORREF Color RGB tripletmcValueCreateColorref()mcValueGetColorref()