mCtrl  0.11.0
Data Structures
chart.h File Reference

Go to the source code of this file.

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:

These standard notifications are sent by the control:

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
wParamReserved, set to zero.
lParamReserved, set to zero.
Returns
(int) Count of data sets.
#define MC_CHM_DELETEALLDATASETS   (MC_CHM_FIRST + 1)

Delete all data sets.

Parameters
wParamReserved, set to zero.
lParamReserved, 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.
lParamReserved, 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.
lParamReserved, 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.
lParamReserved, 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.
lParamReserved, 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.
lParamReserved, 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
wParamReserved, set to zero.
lParamReserved, 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.