mCtrl  0.9.3
Data Structures
chart.h File Reference

Chart control (MC_WC_CHART). More...

Go to the source code of this file.

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 bitmask 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)
 
#define MC_CHM_GETDATASETLEGENDA   (MC_CHM_FIRST + 9)
 
#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...
 

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)
 

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 bersion 1.0 or newer to work correctly. This library was introduced in Windows XP and Windows Server
  1. If your application needs to use this control on Windows 2000, you may need to distribute GDIPLUS.DLL along with your application. (Microsoft released GDIPLUS.DLL 1.0 as a redistributable for this purpose.)

In general, the control is able to hold a multiple series of data (data sets). Each series typically denotes some quantity evolvement 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 respectivally.

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 realy 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. Currently each axis has only a single attribute, a factor exponent, but in future versions more attributes may be added.

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.

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 ineteger value is multiplied with (10 ^ exp), where ^ marks power and exp the exponent.

This is especially usefull 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 }.

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 attibutes 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, tyhe 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 respectivelly.

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_STCKEDCOLUMN and MC_CHS_STACKEDBAR) additionaly 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 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

Common 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 value.

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 bitmask 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)

Not yet implemented.

#define MC_CHM_GETDATASETLEGENDA   (MC_CHM_FIRST + 9)

Not yet implemented.

#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(WCHAR*) 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 thetooltip window or NULL if no tooltip is associated with the control.
#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

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.