BCGControlBar Pro for MFC
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:

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:

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)
{
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;
}
+ Inheritance diagram for CBCGPChartLegendVisualObject:

Public Member Functions

 AddLegendEntryAdds a new legend entry (row)
 
 AddLegendEntryAdds a new legend entry (row)
 
 AddRelatedChartConnects a legend with a chart
 
 AdjustLayoutAdjusts legend layout
 
 FindLegendEntryFinds a legend entry that contains a sell displaying information about specified series and data point
 
 GetColumnCountReturns column count
 
 GetColumnWidthReturns width of specified column
 
 GetHorizontalAlignmentReturns current horizontal alignment
 
 GetLegendBoundsReturns visible legend bounds
 
 GetLegendCellReturns a legend cell located at specified index
 
 GetLegendCellFromPointReturns a legend cell containing a point in client coordinates
 
 GetLegendCellRTCReturns a pointer to runtime class information of custom cell.
 
 GetLegendEntryReturns a pointer to legend entry located at specified index
 
 GetLegendEntryCountReturns a number of legend entries
 
 GetLegendSizeReturns legend size
 
 GetLegendTitleReturns current legend title
 
 GetRelatedChartReturns a chart connected to a legend
 
 GetRelatedChartCountReturns the number of connected charts
 
 GetScrollStepReturns current scroll step
 
 GetTitleSizeReturns size of legend title
 
 GetVerticalAlignmentReturns current vertical alignment
 
 HitTestCalled for hit testing
 
 InsertLegendEntryInserts a legend entry at specified position
 
 InvalidateLegendContentInvalidates legend content
 
 InvalidateLegendSizeCalled by the framework to invalidate the legend after resize
 
 IsAdjustLegendSizeByTitleSizeTells how to adjust legend size if legend title is larger than total size of all cells in a row
 
 IsChartNameInLegendVisibleTells whether a legend displays chart names in entries (rows)
 
 IsLegendTitleVisibleTells whether legend title is visible, or not
 
 IsVerticalLayoutTells whether a legend has vertical or horizontal layout
 
 OnDrawCalled to draw a legend
 
 RemoveAllEntriesRemoves all entries from a legend
 
 RemoveLegendEntryRemoves an entry from legend
 
 RemoveLegendEntryRemoves an entry from legend
 
 RemoveRelatedChartDisconnects a legend from a chart
 
 SetAdjustLegendSizeByTitleSizeDefines how to adjust legend size if legend title is larger than total size of all cells in a row
 
 SetHorizontalAlignmentSets horizontal alignment of advanced legend
 
 SetLegendCellRTCSets legend cell runtime class
 
 SetLegendTitleFormatSets formatting options of legend title
 
 SetScrollStepSpecifies constant scroll step
 
 SetVerticalAlignmentSets vertical alignment of advanced legend
 
 SetVerticalLayoutSets vertical or horizontal layout
 
 ShowChartNameInLegendShows or hides chart names in a legend
 
 ShowLegendTitleShows or hides legend title and sets new title text
 
 UpdateLegendColorsUpdates legend colors
 
- Public Member Functions inherited from CBCGPBaseVisualObject
 CBCGPBaseVisualObjectConstructor.
 
 CBCGPBaseVisualObjectCopy constructor.
 
 CopyToClipboardCopies visual object to the Clipboard.
 
 EnableImageCacheEnables or disables visual object image cache.
 
 ExportToBitmapExports the visual object to bitmap.
 
 ExportToFileExports the visual object to a file (BMP or PNG).
 
 ExportToImageExports the visual object to an image.
 
 GetDataGets an internal data object.
 
 GetDataAnimationTypeGets data animation type.
 
 GetDataCountReturns a number of data objects.
 
 GetEditFlagsGets editing flags.
 
 GetIDGets the object identifier.
 
 GetNameGets the object name.
 
 GetParentContainerGets the parent visual container.
 
 GetRectGets the object bounding rectangle.
 
 GetSelectedThemeObtain a currently selected visual theme.
 
 GetUserDataGets user-defined data associated with this object.
 
 GetValueGets the object value.
 
 IsAutoDestroyTells whether this object will be destroyed automatically.
 
 IsEditModeTells whether this object has the edit mode.
 
 IsEnabledTells whether the visual object is enabled.
 
 IsImageCacheTells whether image cache is enabled for this object.
 
 IsSelectedTells whether this object is selected in the parent container.
 
 IsVisibleTells whether the visual object is visible.
 
 RedrawRedraws this object.
 
 RedrawRectRedraws a specified rectangle.
 
 SelectVisualThemeSelect a visual theme created in Visual Designer.
 
 SetAutoDestroySpecifies whether the object should be destroyed automatically.
 
 SetDataAnimationTypeSets data animation type.
 
 SetDirtyInvalidates and redraws a visual object.
 
 SetEditFlagsSets editing flags.
 
 SetIDSets the object identifier.
 
 SetNameSets an object name.
 
 SetSelectedSelects or unselects the object in the parent container.
 
 SetUserDataSets user-defined data associated with this object.
 
 SetValueSets the object value.
 
 SetVisibleShows or hides the visual object.
 

Protected Member Functions

 OnAdjustLegendBoundsCalled to adjust legend bounds
 
 OnAfterLegendDrawCalled when legend drawing has been finished
 
 OnCalcScrollStepCalled to calculate a scroll step in device units
 
 OnCreateLegendCellCalled to create a legend cell
 
 OnCreateLegendEntryCalled to create a legend entry
 
 OnLegendContentCreatedCalled when legend content has been created (or re-created)