CBCGPChartLegendVisualObject

Detailed Description

The CBCGPChartLegendVisualObject implements the functionality of advanced legend. An advanced legend is implemented as a separate visual object and can be used as a separate object.

It means that:

• it can be placed in container along with other visual objects
• you can take advantage of CBCGPChartLegendCtrl that can be placed on a dialog, embedded into CBCGPDockingControlBar and so on.
• CBCGPChartView has been extended to accommodate an additional control.
• an advanced legend can be connected to several charts.

Advanced legend provides the following features that were not found in the "standard" (embedded in to chart) legend:

• legend title
• grid lines
• scrolling
• customizable number of columns
• ability to display chart name in a separate column, which can be useful if a legend is connected to several charts
• ability to add custom legend entries and cells at any position
• extended customization.

At the core level the advanced legend is designed as a table built up from "rows". Each "row" contains a number of "cells" and this number can be different for each row. A "row" is represented by CBCGPChartLegendEntry class, which encapsulates a list of "cells" represented byCBCGPChartLegendCell class.

To connect a legend to a chart just call CBCGPChartLegendVisualObject::AddRelatedChart. To disconnect a legend from a chart call CBCGPChartLegendVisualObject::RemoveRelatedChart. You can also use two helpers: GetRelatedChartCount and GetRelatedChart, which return the number of connected charts and a related chart at specified index respectively.

The legend automatically gathers series keys and legend labels from related charts.

To use advanced legend in a CBCGPChartView - derived class:

• Derive your class from CBCGPChartView
• Call CBCGPChartView::EnableAdvancedLegend and specify the desired alignment and layout.
• Call CBCGPChartView::GetLegend to obtain a pointer to encapsulated legend visual object and perform additional tuning.
• Process BCGM_ON_CHART_LEGEND_CONTENT_CREATED in your view class in order to add custom entries and/or set custom cell parameters.

To use advanced legend in Visual Container:

• Create an instance of CBCGPChartLegendVisualObject and pass a pointer to container to legend's constructor.
• Call AddRelatedChart to connect the legend with chart(s).
• Call GetLegendSize to determine legend size.
• Reposition legend using SetRect() method and taking into account legend size. Scroll buttons will appear automatically if you allocate for the legend less space that it requires. Note, that legend with vertical layout supports only up/down scroll buttons and legend with horizontal layout supports only left/right scroll button.

An owner of host control will receive BCGM_ON_CHART_LEGEND_CONTENT_CREATED message, which should be handles for advanced customization.

To use advanced legend in CBCGPChartLegendCtrl:

• Create the legend control using CBCGPChartLegendCtrl::Create.
• Call CBCGPChartLegendCtrl::CreateCustomLegend if you have a class derived from CBCGPChartLegendVisualObject.
• Call CBCGPChartLegendCtrl::GetLegend and perform additional settings if needed.
• An owner of CBCGPChartLegendCtrl will receive BCGM_ON_CHART_LEGEND_CONTENT_CREATED message, which should be handles for advanced customization.

If you change content of connected charts dynamically (add or remove series or data points that are included in advanced legend) you must call CBCGPChartLegendVisualObject::InvalidateLegendContent and should handle the content creation (BCGM_ON_CHART_LEGEND_CONTENT_CREATED) message to keep visual settings of individual cells (because all cells are destroyed and recreated when the legend content has been invalidated). It's not recommended to store pointers to cells and rows, because they are invalidated during content creation.

If you directly change a cell property that affects legend size (such as font size in text format), you must call InvalidateLegendSize.

How to add custom entries and cells:

Copy

// To add custom entries and cells you have to handle ::BCGM_ON_CHART_LEGEND_CONTENT_CREATED message or

// override CBCGPChartLegendVisualObject::OnLegendContentCreated.

// The following example illustrates how to add an entry (legend row)

// with two custom cells at the top of the legend:

LRESULT CMyView::OnLegendContentCreated(WPARAM, LPARAM lp)

{

CBCGPChartLegendVisualObject* pLegend = (CBCGPChartLegendVisualObject*) lp;

CBCGPChartLegendEntry* pEntryHead = new CBCGPChartLegendEntry(pLegend);

CBCGPChartLegendCell* pCell1 = new CBCGPChartLegendCell(_T("Head Item"));

CBCGPChartLegendCell* pCell2 = new CBCGPChartLegendCell(_T("Head Value"));

pEntryHead->AddLegendCell(pCell1); pEntryHead->AddLegendCell(pCell2);

pLegend->InsertLegendEntry(pEntryHead, 0);

return 0;

}