Detailed Description

Chart control (MC_WC_CHART).

The chart control is intended to display large sets of numerical data in a visually illustrative way.

Attention: The chart control requires GDIPLUS.DLL version 1.0 or newer to work correctly. See DLL Dependencies for more info.

In general, the control is able to hold a multiple series of data (data sets). Each series typically denotes some quantity evolving in time or its dependency on other quantity. In the chart each series is represented with a different color, and accompanied with a legend text.

The chart control supports charts of many types, depending on the used control style. The type determines how the control presents the data.

Data Sets

To inset, delete or reset the data set values, use messages MC_CHM_INSERTDATASET, MC_CHM_DELETEDATASET or MC_CHM_DELETEALLDATASETS and MC_CHM_SETDATASET respectively.

Data sets can have the data only virtually. That is application can provide to the control only an information the data set exists and how large it is. Whenever the control paints and needs really the data, it asks for them with MC_CHN_GETDISPINFO message. This is useful especially if the data for the chart are really large as it avoids duplication of the data in program memory.

To set various other attributes of the data set, you may use MC_CHM_SETDATASETLEGEND to set its legend or MC_CHM_SETDATASETCOLOR to set the color representing the values form the data set.

Axes

The control has a concept of two axes, the primary and secondary one. It depends on particular chart type though, whether and how the control uses them.

Usually (for chart types where it gives any sense), the primary axis corresponds to the index of data set and in most cases is displayed as the horizontal (X) axis, and the secondary one corresponds to values in a data set and in most cases is displayed as the vertical (Y) axis. An important exception to this rule of thumb are bar (MC_CHS_BAR) and stacked bar (MC_CHS_STACKEDBAR) charts which are similar to the (stacked) column chart, but with horizontal and vertical axes swapped.

Each axis has some attributes associated with it that determine the value tags along the axis.

The factor exponent is an integer value in the range (-9 to +9), and it it is used when painting values for the given axis. An integer value is multiplied with (10 ^ exp), where ^ marks power and exp the exponent.

This is especially useful for charts with non-integer values as negative factor exponent actually turns the data set values into fixed point numbers.

For example with factor exponent -2, data set with values { 5, 100, 101, 102 } would be displayed as { 0.05, 1.00, 1.01, 1.02 }.

To set or get the factor exponent, use messages MC_CHM_SETFACTOREXPONENT and MC_CHM_GETFACTOREXPONENT respectively.

Other import axis attribute is a value offset. The offset specifies a number which is added to an index. This way, application can set the offset of the axis for example to 2003, and hence, the value tags along the axis shall be 2003, 2004, 2005, etc. This can be used, for example, in charts which show some time development of some values across, e.g. several years.

To set or get the axis offset, use messages MC_CHM_SETAXISOFFSET and MC_CHM_GETAXISOFFSET respectively.

Chart Types

Attention: Different types of chart have different requirements about the data and if the application does not follow these requirements, the chart can just display gibberish, or change the output in future mCtrl versions.

The pie chart (MC_CHS_PIE) expects each data set consisting of a single non-negative value. It does not display any axis, but factor exponent of the primary one is used for displaying data set values.

Note: The pie chart visually differs quite a lot from majority of the other chart types this control provides. Many control attributes settable by control messages actually have no impact to the pie chart.

The scatter chart (MC_CHS_SCATTER) expects to have all data set sizes of even count of values. Unlike the other chart types, the sizes of the data sets can differ. The scatter chart interprets each data set as a set of value pairs. Each value with odd index corresponds with the primary (X) axis, and even index with secondary (Y) axis respectively.

The line chart (MC_CHS_LINE), the area chart (MC_CHS_AREA), the column chart (MC_CHS_COLUMN) and the bar chart (MC_CHS_BAR) only expect that all the data sets are of the same size.

Stacked variants of the charts above (MC_CHS_STACKEDLINE, MC_CHS_STACKEDAREA, MC_CHS_STACKEDCOLUMN and MC_CHS_STACKEDBAR) additionally expect all the data in all data sets are positive. Actually the charts work for negative values, but the result can be confusing for the user.

Standard Messages

These standard messages are handled by the control:

WM_GETTEXT
WM_SETTEXT
CCM_SETNOTIFYWINDOW

These standard notifications are sent by the control:

NM_OUTOFMEMORY
NM_TOOLTIPSCREATED

Data Structures
struct	MC_CHDATASET
	Structure for manipulating with a data set. More...

struct	MC_NMCHDISPINFO
	Structure for notification MC_CHN_GETDISPINFO. More...

Initialization Functions
BOOL	mcChart_Initialize (void)

void	mcChart_Terminate (void)

Window Class
#define	MC_WC_CHARTW L"mCtrl.chart"

#define	MC_WC_CHARTA "mCtrl.chart"

Control Styles
#define	MC_CHS_PIE 0x0000
	Pie chart. More...

#define	MC_CHS_SCATTER 0x0001
	Scatter chart. More...

#define	MC_CHS_LINE 0x0002
	Line chart. More...

#define	MC_CHS_STACKEDLINE 0x0003
	Stacked line chart. More...

#define	MC_CHS_AREA 0x0004
	Area chart. More...

#define	MC_CHS_STACKEDAREA 0x0005
	Stacked area chart. More...

#define	MC_CHS_COLUMN 0x0006
	Column chart. More...

#define	MC_CHS_STACKEDCOLUMN 0x0007
	Stacked column chart. More...

#define	MC_CHS_BAR 0x0008
	Bar chart. More...

#define	MC_CHS_STACKEDBAR 0x0009
	Stacked bar chart. More...

#define	MC_CHS_TYPEMASK 0x003f
	This is not actually a valid style, it's the bit-mask of chart type. More...

#define	MC_CHS_NOTOOLTIPS 0x0040
	Disables a tooltip window. More...

#define	MC_CHS_DOUBLEBUFFER 0x0080
	Enable painting with double buffering. More...

MC_NMCHDISPINFO::fMask Bits

#define	MC_CHDIM_VALUES (1 << 0)
	The control asks for MC_NMCHDISPINFO::piValues. More...

Control Messages
#define	MC_CHM_GETDATASETCOUNT (MC_CHM_FIRST + 0)
	Get count of data sets. More...

#define	MC_CHM_DELETEALLDATASETS (MC_CHM_FIRST + 1)
	Delete all data sets. More...

#define	MC_CHM_INSERTDATASET (MC_CHM_FIRST + 2)
	Insert a data set. More...

#define	MC_CHM_DELETEDATASET (MC_CHM_FIRST + 3)
	Delete a data set. More...

#define	MC_CHM_GETDATASET (MC_CHM_FIRST + 4)
	Get a data set. More...

#define	MC_CHM_SETDATASET (MC_CHM_FIRST + 5)
	Set a data set. More...

#define	MC_CHM_GETDATASETCOLOR (MC_CHM_FIRST + 6)
	Get a color representing the data set in the chart. More...

#define	MC_CHM_SETDATASETCOLOR (MC_CHM_FIRST + 7)
	Set a color representing the data set in the chart. More...

#define	MC_CHM_GETDATASETLEGENDW (MC_CHM_FIRST + 8)
	Get legend text of the data set (Unicode variant). More...

#define	MC_CHM_GETDATASETLEGENDA (MC_CHM_FIRST + 9)
	Get legend text of the data set (ANSI variant). More...

#define	MC_CHM_SETDATASETLEGENDW (MC_CHM_FIRST + 10)
	Set legend text of the data set (Unicode variant). More...

#define	MC_CHM_SETDATASETLEGENDA (MC_CHM_FIRST + 11)
	Set legend text of the data set (ANSI variant). More...

#define	MC_CHM_GETFACTOREXPONENT (MC_CHM_FIRST + 12)
	Gets factor exponent of a primary or secondary axis. More...

#define	MC_CHM_SETFACTOREXPONENT (MC_CHM_FIRST + 13)
	Sets factor exponent of a primary or secondary axis. More...

#define	MC_CHM_GETAXISOFFSET (MC_CHM_FIRST + 14)
	Gets offset of a primary or secondary axis. More...

#define	MC_CHM_SETAXISOFFSET (MC_CHM_FIRST + 15)
	Sets offset of a primary or secondary axis. More...

#define	MC_CHM_SETTOOLTIPS (MC_CHM_FIRST + 16)
	Associate a tooltip window with the chart control. More...

#define	MC_CHM_GETTOOLTIPS (MC_CHM_FIRST + 17)
	Get tooltip associated with the control. More...

#define	MC_CHM_GETAXISLEGENDW (MC_CHM_FIRST + 18)
	Get legend text of the axis (Unicode variant). More...

#define	MC_CHM_GETAXISLEGENDA (MC_CHM_FIRST + 19)
	Get legend text of the axis (ANSI variant). More...

#define	MC_CHM_SETAXISLEGENDW (MC_CHM_FIRST + 20)
	Set legend text of axis (Unicode variant). More...

#define	MC_CHM_SETAXISLEGENDA (MC_CHM_FIRST + 21)
	Set legend text of axis (ANSI variant). More...

Control Notifications
#define	MC_CHN_GETDISPINFO (MC_CHN_FIRST + 0)
	Fired when the control needs some data from its parent. More...

Unicode Resolution
#define	MC_WC_CHART MCTRL_NAME_AW(MC_WC_CHART)

#define	MC_CHM_GETDATASETLEGEND MCTRL_NAME_AW(MC_CHM_GETDATASETLEGEND)

#define	MC_CHM_SETDATASETLEGEND MCTRL_NAME_AW(MC_CHM_SETDATASETLEGEND)

#define	MC_CHM_GETAXISLEGEND MCTRL_NAME_AW(MC_CHM_GETAXISLEGEND)

#define	MC_CHM_SETAXISLEGEND MCTRL_NAME_AW(MC_CHM_SETAXISLEGEND)

Data Structure Documentation

struct MC_CHDATASET

Structure for manipulating with a data set.

On input, set dwCount to a count of values in the data set (when inserting or setting a data set), or to a number of values which can be written to the buffer pointed by piValues (when getting a data set).

If inserting or setting a data set and if piValues is set to NULL, then the control will retrieve the data dynamically from its parent through a notification MC_CHN_GETDISPINFO.

See also: MC_CHM_INSERTDATASET MC_CHM_GETDATASET MC_CHM_SETDATASET

Data Fields
DWORD	dwCount	Count of values in the data set.
int *	piValues	Pointer to an array of values in the data set.

struct MC_NMCHDISPINFO

Structure for notification MC_CHN_GETDISPINFO.

Data Fields
NMHDR	hdr	Standard notification structure header.
DWORD	fMask	Mask of members the control asks for. See MC_CHDIF_xxxx.
int	iDataSet	Data set index.
int	iValueFirst	Index of a first value the controls asks for.
int	iValueLast	Index of last value the controls asks for.
int *	piValues	Pointer to a buffer where application fills the values.

Macro Definition Documentation

#define MC_WC_CHARTW L"mCtrl.chart"

Window class name (Unicode variant).

#define MC_WC_CHARTA "mCtrl.chart"

Window class name (ANSI variant).

#define MC_CHS_PIE 0x0000

Pie chart.

#define MC_CHS_SCATTER 0x0001

Scatter chart.

#define MC_CHS_LINE 0x0002

Line chart.

#define MC_CHS_STACKEDLINE 0x0003

Stacked line chart.

#define MC_CHS_AREA 0x0004

Area chart.

#define MC_CHS_STACKEDAREA 0x0005

Stacked area chart.

#define MC_CHS_COLUMN 0x0006

Column chart.

#define MC_CHS_STACKEDCOLUMN 0x0007

Stacked column chart.

#define MC_CHS_BAR 0x0008

Bar chart.

#define MC_CHS_STACKEDBAR 0x0009

Stacked bar chart.

#define MC_CHS_TYPEMASK 0x003f

This is not actually a valid style, it's the bit-mask of chart type.

#define MC_CHS_NOTOOLTIPS 0x0040

Disables a tooltip window.

When having a tooltip window associated, the control uses to show additional information about the pointed value in the chart. By default the control creates its own control when this style is not set.

See also: MC_CHM_SETTOOLTIPS

#define MC_CHS_DOUBLEBUFFER 0x0080

Enable painting with double buffering.

It prevents flickering when the control is being continuously resized.

#define MC_CHDIM_VALUES (1 << 0)

The control asks for MC_NMCHDISPINFO::piValues.

The application is responsible to fill the buffer piValues with values of data set determined by iDataSet, corresponding to the value indexes in the interval from iValueFirst to iValueLast (including).

The control guarantees the buffer piValues is large enough for (iValueLast-iValueFirst+ 1) integers.

#define MC_CHM_GETDATASETCOUNT (MC_CHM_FIRST + 0)

Get count of data sets.

Parameters

wParam	Reserved, set to zero.
lParam	Reserved, set to zero.

Returns: (int) Count of data sets.

#define MC_CHM_DELETEALLDATASETS (MC_CHM_FIRST + 1)

Delete all data sets.

Parameters

wParam	Reserved, set to zero.
lParam	Reserved, set to zero.

Returns: (BOOL) TRUE on success, FALSE otherwise.

See also: MC_CHM_DELETEDATASET

#define MC_CHM_INSERTDATASET (MC_CHM_FIRST + 2)

Insert a data set.

If the MC_CHDATASET::piValues is set to NULL, the control will retrieve the data dynamically from its parent through a notification MC_CHN_GETDISPINFO.

Parameters

[in]	wParam	(`int`) Index of the new data set.
[in]	lParam	(MC_CHDATASET*) Pointer to a data of the new data set.

Returns: (int) Index of the new data set, or -1 on failure.

#define MC_CHM_DELETEDATASET (MC_CHM_FIRST + 3)

Delete a data set.

Parameters

[in]	wParam	(`int`) Index of the data set.
	lParam	Reserved, set to zero.

Returns: (BOOL) TRUE on success, FALSE otherwise.

#define MC_CHM_GETDATASET (MC_CHM_FIRST + 4)

Get a data set.

Parameters

[in]	wParam	(`int`) Index of the data set.
[in,out]	lParam	(MC_CHDATASET*) Pointer to a data of the new data set. On input, its member `dwCount` must be set to indicate how many values can be written to the buffer pointed by `piValues`. In output, the `dwCount` is updated to a count of values written into the `piValues`. You may also set `lParam` to `NULL` to just get number of values in the data set.

Returns: (int) Number of values in the data set, or -1 on failure.

Note: If the data set holds its value only virtually (i.e. if the MC_CHDATASET::piValues was NULL when the dataset was set), then this message just sets MC_CHDATASET::dwCount to zero.

#define MC_CHM_SETDATASET (MC_CHM_FIRST + 5)

Set a data set.

If the MC_CHDATASET::piValues is set to NULL, the control will retrieve the data dynamically from its parent through a notification MC_CHN_GETDISPINFO.

Parameters

[in]	wParam	(`int`) Index of the data set to change.
[in]	lParam	(MC_CHDATASET*) Pointer to a data of the new data set.

Returns: (BOOL) TRUE on success, FALSE otherwise.

#define MC_CHM_GETDATASETCOLOR (MC_CHM_FIRST + 6)

Get a color representing the data set in the chart.

Parameters

[in]	wParam	(`int`) Index of the data set.
	lParam	Reserved, set to zero.

Returns: (COLORREF) The color, or -1 on failure.

#define MC_CHM_SETDATASETCOLOR (MC_CHM_FIRST + 7)

Set a color representing the data set in the chart.

Parameters

[in]	wParam	(`int`) Index of the data set.
[in]	lParam	(`COLORREF`) The color. It may be MC_CLR_DEFAULT.

Returns: (BOOL) TRUE on success, FALSE otherwise.

#define MC_CHM_GETDATASETLEGENDW (MC_CHM_FIRST + 8)

Get legend text of the data set (Unicode variant).

Parameters

[in]	wParam	(`DWORD`) Low word specifies index of the data set. High word specifies size of the buffer provided within `lParam`.
[out]	lParam	(`WCHAR*`) Pointer to a buffer that is to receive the text. If the buffer is too small, the text is truncated.

Returns: (BOOL) TRUE on success, FALSE otherwise.

#define MC_CHM_GETDATASETLEGENDA (MC_CHM_FIRST + 9)

Get legend text of the data set (ANSI variant).

Parameters

[in]	wParam	(`DWORD`) Low word specifies index of the data set. High word specifies size of the buffer provided within `lParam`.
[out]	lParam	(`char*`) Pointer to a buffer that is to receive the text. If the buffer is too small, the text is truncated.

Returns: (BOOL) TRUE on success, FALSE otherwise.

#define MC_CHM_SETDATASETLEGENDW (MC_CHM_FIRST + 10)

Set legend text of the data set (Unicode variant).

Parameters

[in]	wParam	(`int`) Index of the data set.
[in]	lParam	(`WCHAR*`) The legend string.

Returns: (BOOL) TRUE on success, FALSE otherwise.

#define MC_CHM_SETDATASETLEGENDA (MC_CHM_FIRST + 11)

Set legend text of the data set (ANSI variant).

Parameters

[in]	wParam	(`int`) Index of the data set.
[in]	lParam	(`char*`) The legend string.

Returns: (BOOL) TRUE on success, FALSE otherwise.

#define MC_CHM_GETFACTOREXPONENT (MC_CHM_FIRST + 12)

Gets factor exponent of a primary or secondary axis.

Parameters

[in]	wParam	(`int`) Set to `1` to retrieve the exponent of primary axis, or `2` to set secondary axis.
	lParam	Reserved, set to zero.

Returns: (int) The value of the exponent, or -666 on failure.

#define MC_CHM_SETFACTOREXPONENT (MC_CHM_FIRST + 13)

Sets factor exponent of a primary or secondary axis.

Parameters

[in]	wParam	(`int`) Set to `0` to set the exponent for both axes, `1` to set primary axis, or `2` to set secondary axis.
[in]	lParam	(`int`) The exponent. Only values from `-9` to `+9` (inclusive) are allowed.

Returns: (BOOL) TRUE on success, FALSE otherwise.

#define MC_CHM_GETAXISOFFSET (MC_CHM_FIRST + 14)

Gets offset of a primary or secondary axis.

Parameters

[in]	wParam	(`int`) Set to `1` to retrieve the exponent of primary axis, or `2` to set secondary axis.
	lParam	Reserved, set to zero.

Returns: (int) The offset, or -666 on failure.

#define MC_CHM_SETAXISOFFSET (MC_CHM_FIRST + 15)

Sets offset of a primary or secondary axis.

Parameters

[in]	wParam	(`int`) Set to `1` to set primary axis, or `2` to set secondary axis.
[in]	lParam	(`int`) The offset.

Returns: (BOOL) TRUE on success, FALSE otherwise.

#define MC_CHM_SETTOOLTIPS (MC_CHM_FIRST + 16)

Associate a tooltip window with the chart control.

Parameters

[in]	wParam	(`HWND`) Handle of the tooltip window.
	lParam	Reserved, set to zero.

Returns: (HWND) Handle of previous tooltip window or NULL if no tooltip was associated with the control.

See also: MC_CHS_NOTOOLTIPS

#define MC_CHM_GETTOOLTIPS (MC_CHM_FIRST + 17)

Get tooltip associated with the control.

Parameters

wParam	Reserved, set to zero.
lParam	Reserved, set to zero.

Returns: (HWND) Handle of the tooltip window or NULL if no tooltip is associated with the control.

#define MC_CHM_GETAXISLEGENDW (MC_CHM_FIRST + 18)

Get legend text of the axis (Unicode variant).

Parameters

[in]	wParam	(`DWORD`) Low word specifies index of the axis. Use `1` to set primary axis, or `2` to set secondary axis. High word specifies size of the buffer provided within `lParam`.
[out]	lParam	(`WCHAR*`) Pointer to a buffer that is to receive the text. If the buffer is too small, the text is truncated.

Returns: (BOOL) TRUE on success, FALSE otherwise.

#define MC_CHM_GETAXISLEGENDA (MC_CHM_FIRST + 19)

Get legend text of the axis (ANSI variant).

Parameters

[in]	wParam	(`DWORD`) Low word specifies index of the axis. Use `1` to set primary axis, or `2` to set secondary axis. High word specifies size of the buffer provided within `lParam`.
[out]	lParam	(`char*`) Pointer to a buffer that is to receive the text. If the buffer is too small, the text is truncated.

Returns: (BOOL) TRUE on success, FALSE otherwise.

#define MC_CHM_SETAXISLEGENDW (MC_CHM_FIRST + 20)

Set legend text of axis (Unicode variant).

Note that pie chart does not paint the axis legend.

Parameters

[in]	wParam	(`int`) Set to `1` to set primary axis, or `2` to set secondary axis.
[in]	lParam	(`WCHAR*`) The legend string.

Returns: (BOOL) TRUE on success, FALSE otherwise.

#define MC_CHM_SETAXISLEGENDA (MC_CHM_FIRST + 21)

Set legend text of axis (ANSI variant).

Note that pie chart does not paint the axis legend.

Parameters

[in]	wParam	(`int`) Set to `1` to set primary axis, or `2` to set secondary axis.
[in]	lParam	(`char*`) The legend string.

Returns: (BOOL) TRUE on success, FALSE otherwise.

#define MC_CHN_GETDISPINFO (MC_CHN_FIRST + 0)

Fired when the control needs some data from its parent.

When the control itself holds any data only virtually and it actually needs them, it asks the application to provide them with this message. Application is expected to inspect MC_NMCHDISPINFO::fMask and fill the structure with corresponding data.

Parameters

[in]	wParam	(`int`) Id of the control sending the notification.
[in,out]	lParam	(MC_NMCHDISPINFO*) Pointer to structure for exchanging the data.

Returns: Ignored.

#define MC_WC_CHART MCTRL_NAME_AW(MC_WC_CHART)

Unicode-resolution alias.

See also: MC_WC_CHARTW MC_WC_CHARTA

#define MC_CHM_GETDATASETLEGEND MCTRL_NAME_AW(MC_CHM_GETDATASETLEGEND)

Unicode-resolution alias.

See also: MC_CHM_GETDATASETLEGENDW MC_CHM_GETDATASETLEGENDA

#define MC_CHM_SETDATASETLEGEND MCTRL_NAME_AW(MC_CHM_SETDATASETLEGEND)

Unicode-resolution alias.

See also: MC_CHM_SETDATASETLEGENDW MC_CHM_SETDATASETLEGENDA

#define MC_CHM_GETAXISLEGEND MCTRL_NAME_AW(MC_CHM_GETAXISLEGEND)

Unicode-resolution alias.

See also: MC_CHM_GETAXISLEGENDW MC_CHM_GETAXISLEGENDA

#define MC_CHM_SETAXISLEGEND MCTRL_NAME_AW(MC_CHM_SETAXISLEGEND)

Unicode-resolution alias.

See also: MC_CHM_SETAXISLEGENDW MC_CHM_SETAXISLEGENDA

Function Documentation

BOOL mcChart_Initialize ( void )

Registers window class of the control.

Note that the function fails, if GDIPLUS.DLL is not available.

Returns: TRUE on success, FALSE on failure.

void mcChart_Terminate ( void )

Unregisters window class of the control.

Detailed Description

Data Sets

Axes

Chart Types

Standard Messages

Data Structures

Initialization Functions

Window Class

Control Styles

MC_NMCHDISPINFO::fMask Bits

Control Messages

Control Notifications

Unicode Resolution

Data Structure Documentation

Macro Definition Documentation

Function Documentation