BCGControlBar Pro for MFC

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:

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