Chart Control User’s Guide
Table of Contents
- Architecture Overview
- Component Overview
- ChartControl
- ChartContainer
- ChartPanel
- X/Y Chart
- Pie Chart
- ChartLegend
- Printing
- Export/Import
Architecture Overview
(Note: Many of the options and abilities of the ChartControl, as presented in this document, are demonstrated in the ChartControl Demo Applications included in the DotNetBar Samples folder. Please refer to it as an additional source for information and assistance).
The following is the basic overview of the architecture of the ChartControl.
(The items contained within this architecture will be elaborated upon later in this document).
Component Overview
The following images illustrate the main components in the ChartControl.
In the first image we have 4 separate charts, with each chart occupying a single cell of a 2×2 defined matrix (see ChartMatrix). Each matrix cell (or range of cells) can contain one or more ChartContainer items. ChartContainer items may either be a ChartPanel or a ChartXy element.
ChartPanel elements can contain additional ChartPanel or ChartXy elements, oriented in their own matrix layout.
ChartXy elements can contain any number of ChartSeries (along with their associated ChartAxes, DataLabels, etc).
Each ChartSeries can be either a Point, Line, or Bubble based series, and can be associated with either the primary, default axes, or associated with any number of user defined and created ancillary axes.
Each ChartPanel, ChartXy, and ChartAxis can have multiple defined Titles, oriented and styled to the application needs.
Here are a few sample ChartControl charts:
The Next Chart Control illustrates additional chart components, such as Chart Legends, Data Labels, Reference Lines, Trend Lines, Regression Lines, and Axis Stripes. With each one of these items being highly configurable (such as with drop shadows, fore and background coloring, orientation / alignment, visibility, value formatting, etc).
ChartControl
The main ChartControl object contains properties and methods that pertain to the entire control. The following is a list, and description, of each of these properties and methods.
ChartControl Properties
ChartCursor – Gets or sets the “logical” Cursor for the ChartControl. Use “Cursor” property to set the default Cursor for the application. ChartCursor is used to set the Cursor based upon the underlying chart element interacting with the system mouse.
ChartPanel – Gets the primary (or default) ChartPanel for the ChartControl. This is the root container element for all defined chart items. Each ChartPanel manages a matrix of ChartContainer items (ChartPanel or ChartXy items). ChartPanel’s can be nested to any depth as needed by the application. They can optionally be scrolled (via horizontal and vertical scrollbars) or “panned” (via clicking and dragging in the content are of the ChartPanel). Scrolling and panning is also available in ChartXy and ChartLegend items.
DataMember – Gets or sets the application defined default “DataMember” (as associated and defined by the set DataSource). Setting the DataMember at the ChartControl level, will enable its use throughout the ChartControl (each ChartPanel, ChartXy, and ChartSeries can have their own set DataSource and DataMember if desired).
DataSource – Gets or sets the application defined default “DataSource”. Setting the DataSource at the ChartControl level, will enable its use throughout the ChartControl (each ChartPanel, ChartXy, and ChartSeries can have their own set DataSource and DataMember if desired).
DefaultVisualStyles – Gets or set the default visual styles for the entire ChartControl. Each element in the ChartControl (ChartPanel, ChartXy, ChartSeries, ChartAxis, etc) can set their own specific styles, and in doing so, will override the control-wide settings.
IsUpdateSuspended – Gets whether the current visual update mechanism has been suspended. Updates can be suspended via calling BeginUpdate(), and restarted by calling EndUpdate(). Begin/EndUpdate() must be called as a pair (multiple BeginUpdates() can be called, but must eventually be paired with a matching EndUpdate() call).
IsUpdateSuspended – Gets a list of the currently “Selected” ChartControl items.
SelectedItems – Gets a list of the current items marked as “Selected”.
ChartControl Methods
UpdateLayout([bool force])
This routine performs ChartControl layout and arrangement. You should seldom, if ever, need to call this function. The ChartControl uses this routine after any chart property has changed that requires the layout to be recalculated and its elements arranged. It is provided for external use for those instances where you might need to know layout information before the chart has internally performed this operation.
PaintTo(Graphics g [,Rectangle ClipRectangle])
This routine paints the ChartControl to the given Graphics canvas. It can be used to save the chart to an image for later display/use, or to provide your own specialized printing operations, or some such functionality. (Note that print support is provided by the chart itself).
GetElementAt(Point pt)
This routine gets the chart control element located at the given Point. Note that the Point needs to be in local coordinates for the control and not in screen coordinates.
BeginUpdate()
EndUpdate()
Calling the BeginUpdate routine informs the ChartControl that an extended update phase has begun.The control will suspend all layout calculations and display updates until the corresponding EndUpdate routine is called. You will probably never need to suspend output, but the functionality is provided none-the-less.
BeginUpdate / EndUpdate can be nested and must be called in pairs – every BeginUpdate must have a matching EndUpdate call.
GetSelected(ChartContainer item)
This routine returns whether the given item is “selected“.
SetSelected(ChartContainer item, bool selected)
This routine sets or clears the given item’s selection state.
ClearAllSelected()
This routine clears each selected item’s selection state.
ChartContainer
The ChartContainer object is the base container object for all ‘container’ type chart elements in the ChartControl. ChartContainer elements can be ChartPanel or ChartXy elements.
The following is a list of the Properties available to all ChartContainer elements (ChartPanel and ChartXy).
Bounds – Gets the scroll adjusted rectangular bounds of the entire container area.
ContentBounds – Gets the rectangular bounds of the “Content” area of the chart. For a ChartPanel, this includes the entire display area, however for ChartXy elements it includes the Charting area, Axes, Legend, and Titles.
FrameBounds – Gets the rectangular bounds of the “Frame” area of the chart. This area is inset due to set margins, padding, and drop shadow – and encompasses the entire Content area.
In the image below, the red rectangle denotes the Container ‘Bounds‘, the blue rectangle denotes the ‘FrameBounds‘, and the green rectangle denotes the ‘ContentBounds‘.
AutoSizeMode – Gets or sets the mode used to size the container. The available choices are ‘None’, and ‘Fill’. ‘None’ is the default (which indicates no auto-sizing will occur). ‘Fill‘ indicates that the size of the container will be determined by the containers assigned “FillWeight” (see FillWeight below), relative to all other set container FillWeights.
ContainerVisualStyles – Gets or sets the visual styles for the container. The container supports styles for ‘Default‘, ‘MouseOver‘, ‘Selected‘, and ‘MouseOverSelected‘.
EffectiveContainerStyle – Gets a reference to the container’s effective (cached, composite) styles. Chart element styles are created from higher level defined styles, to the lower, instance level styles.
In other words, if the ChartControl DefaultVisualStyle for a ChartContainer has a Background style set, it will be in effect for all defined ChartContainers, no matter the level. If a specific ChartContainer’s style redefines the same property, however, it will override the DefaultVisualStyle set at the ChartControl (or any higher) level.
Effective style properties should not be altered, as changes made through them will be lost when the composite style is recreated, as needed for other style and programmatic changes.
EmptyText – Gets or sets the Text to display when the container is empty. For ChartPanel elements, this is when there are no displayable ChartContainer objects (ie. the ChartContainer collection contains no Visible entries). For ChartXy elements, it is when there are no displayable ChartSeries defined for the chart (ie. the ChartSeries collection contains no Visible entries).
EnableEmptyTextMarkup – Gets or sets whether EmptyText mini-markup support is enabled.
EnablePanning – Gets or sets whether the container can be ‘panned‘ (scrolled vertically/horizontally by click-and-drag in the content area). Default is ‘true‘. Panning can be enabled or disabled for any/all container objects, including each ChartPanel, ChartXy, and ChartLegend objects.
EnableSelection – Indicates whether the container can be “selected” with the mouse. The ChartControl maintains a selection status for each chart container, but does not currently use this for anything other than utilizing the “Selected/SelectedMouseOver” styles.
FillWeight – Gets or sets a value which, when AutoSizeMode is “Fill“, represents the width of the container relative to the widths of other fill-mode containers (default value is 100)
HScrollBar – Gets a reference to the container’s Horizontal Scrollbar. The Horizontal Scrollbar may or may not be presented, based upon whether the content area of the container can be displayed fully in the area given (see MinContentSize). Each scrollbar in the control can be stylized as needed by the app.
HScrollBarHeight – Gets or sets the height of the horizontal scrollbar. It’s default height is 9, set as such to minimize the area taken up in the display, to give more area for the visibility of chart data and information. It can be set larger or smaller as needed by the application.
HScrollOffset – Gets or sets the horizontal scrollbar offset. This property can be used to scroll the content area of the container as needed.
HScrollBarVisible – Gets or sets whether horizontal scrollbar is shown if needed (due to content of the control exceeding available width). Default is ‘true‘, but can be set to ‘false‘ if no horizontal scrollbar is wanted.
IsSelected – Gets or sets whether the container is selected.
Legend – Gets a reference to the container’s ChartLegend. A Legend can be presented for each container (ChartPanel and ChartXy), or combined as needed (‘parent‘ Legend’s can optionally contain ‘child‘ Legend entries, so that (for instance) if you have a 5×5 matrix of nested charts, you need not have 25 legends, but can choose to have a single Legend controlling all 25 child charts).
MatrixAlignEndColumn – Gets or sets whether the container’s content ending X-offset is aligned with other containers ending in the same ChartMatrix column. When you define multiple charts within the same ChartControl, the defined charts are assigned a range of matrix cells (either automatically or directly by the application). If you have multiple charts ending in the same column of the matrix, there is no guarantee that these containers right edges will align (due to titles, axis definitions, etc). If it is desired that they align, you can set this property to ‘true‘ for each container that needs to be aligned, and the content area edges will be aligned as needed.
In the example given below, each chart is occupying 6 horizontal matrix cells, with the start and ending cell contents not aligning by default, due to the chart titles defined for them (they are set to auto-wrap if needed).
The first image is with the MatrixAlignStartColumns and MatrixAlignEndColumn properties are set to ‘false’.
This image is with the MatrixAlignStartColumns and MatrixAlignEndColumn properties set to ‘true’.
MatrixAlignEndRow – Gets or sets whether the container’s content ending Y-offset is aligned with other containers ending in the same ChartMatrix row. It is the same principle as with MatrixAlignEndColumn. (See above MatrixAlignEndColumn)
MatrixAlignStartRow – Gets or sets whether the container’s content starting Y-offset is aligned with other containers starting in the same ChartMatrix row. It is the same principle as with MatrixAlignEndColumn. (See above MatrixAlignEndColumn)
MatrixAlignStartColumn – Gets or sets whether the container’s content starting X-offset is aligned with other containers starting in the same ChartMatrix column. It is the same principle as with MatrixAlignEndColumn. (See above MatrixAlignEndColumn)
MatrixAlignStartRow – Gets or sets whether the container’s content starting Y-offset is aligned with other containers starting in the same ChartMatrix row. It is the same principle as with MatrixAlignEndColumn. (See above MatrixAlignEndColumn)
MatrixDisplayBounds – Gets or sets the container’s matrix display bounds (in relative units of the matrix). This property follows the ‘normal‘ Rectangle definition – starting offset with a length and width associated value. So, to assign a given container to a single matrix cell (cell 0,0), one could do the following (note that in the following examples, the matrix must have been defined to be at least 8×6 in size):
chartXy.MatrixDisplayBounds = new Rectangle(0, 0, 1, 1);
To set a container to a range of cells (starting at 0,0 and encompassing cell 7, 5), one would do so like the following:
chartXy.MatrixDisplayBounds = new Rectangle(0, 0, 8, 6);
MatrixDisplayOrder – Gets or sets the containers display order in the matrix layout (higher values are placed on top of lower values).
In the following example, the MatrixDisplayOrder for the large, background chart is set to ‘0’ and the smaller, foreground chart is set to ‘1’.
MinContentSize – Gets or sets the minimum size of the content area of the container . If the container is sized such that the content area of the container would become smaller than the set MinContentSize, then the appropriate scrollbar will be presented (if enabled).
ScrollBounds – Gets the Scrollable bounds. This value is the same as the ContentBounds, except for container borders are taken into account.
ScrollBoundsEx – Gets the extended Scrollable bounds. This is the ‘extended’, or actual content area of the container (not just the visible area on screen). The area can be larger than MinContentSize, but will never be smaller.
ScrollBoundsOffset – Gets the current horizontal and vertical offsets (see HScrollOffset and VScrollOffset).
Titles – Gets or Sets a reference to the collection of Titles for the container. Each container (ChartPanel, ChartXy) can have any number of titles defined for it. They can be oriented top, bottom, left, or right, and can be aligned TopLeft, MiddleRight, etc). They can be fully styled, with borders, backgrounds, images and a drop shadow if desired. Each title can be set to auto-wrap if needed, and can be set to limit the number of wrapped lines to a given amount.
VScrollBar – Gets a reference to the container’s Vertical Scrollbar. The Vertical Scrollbar may, or may not, be presented, based upon whether the content area of the container can be displayed fully in the area given (see MinContentSize). Each scrollbar in the control can be stylized as needed by the app.
VScrollBarHeight – Gets or sets the width of the vertical scrollbar. It’s default width is 9, set as such to minimize the area taken up in the display, to give more area for the visibility of chart data and information. It can be set larger or smaller as needed by the application.
VScrollOffset – Gets or sets the vertical scrollbar offset. This property can be used to scroll the content area of the container as needed.
VScrollBarVisible – Gets or sets whether vertical scrollbar is shown if needed (due to content of the control exceeding available height). Default is ‘true‘, but can be set to ‘false‘ if no vertical scrollbar is wanted.
The following is a list of the methods available to all ChartContainer elements (ChartPanel and ChartXy).
EnsureVisible(bool center)
EnsureVisible(ChartContainer item, bool center)
Ensures that the associated container (or the given container “item”) is visible on screen, and optionally centered in the display (as much as is possible).
GetElementAt(Point pt)
Returns the ChartVisualElement located at the given Point (in local coordinates) or null if the Point is not within the container. Note that when the ChartVisualElement is returned, it must be cast to the actual chart element that was returned, in order to access the specific element’s properties and methods.
For example:
ChartVisualElement item = GetElementAt(pt);
if (item is ChartXy)
{
ChartXy chart = (ChartXy) item;
chartXy.EnsureVisible(true);
}
GetHitArea(Point pt)
Returns the ItemHitArea that the given Point (in local coordinates) is associated with.
Copy()
Creates and returns a duplicate copy of the associated element.
CopyTo(ChartVisualElement copy)
Copies all property and style definitions from the associated element, to the given ‘copy’.
ChartPanel
The ChartPanel object is the main container object for all chart elements in the ChartControl. ChartPanel objects contain a collection of ChartContainer elements, and as such can be nested to any desired depth.
The following is a list of the Properties available to all ChartPanel elements. These are in addition to the base ChartContainer properties and methods listed above.
AutoFillChartMatrix – Gets or sets whether the ChartMatrix is auto filled from the ChartContainers collection. Each defined, visible element is, by default, assigned to a single matrix cell. The layout used to fill the matrix, is defined by the ContainerLayout property.
AutoSizeChartMatrix – Gets or sets whether the ChartMatrix is auto sized from the ChartContainers collection. When set to true, the ChartControl will size the ChartMatrix to best fit the defined visible ChartContainers. The layout that is used to size the matrix, is defined by the ContainerLayout property.
ChartContainers – Gets a reference to the collection of ChartContainers (ChartPanel and ChartXy). All displayed chart elements must appear in the ChartContainers collection to be part of the ChartControl and added to the ChartMatrix. (See above ChartContainers component description).
ChartMatrix – Gets the Matrix used to display the defined ChartContainers in a Matrix format. The ChartMatrix can be sized and ‘styled’ as needed by the application (DividerLines, etc). All displayed ChartContainer elements appear in a ChartMatrix – even if there is only 1 element defined. Matrix cells may contain no items, single items, or an overlap of multiple items (with overlapping items having a settable display order).
ChartPanelVisualStyle – Gets or sets the visual style for the ChartPanel. Values set here, will override set panel styles on parent items.
ContainerLayout – Gets or sets the layout (horizontal, vertical, matrix) for the defined ChartContainers. This property defines how the ChartControl auto sizes and fills the ChartMatrix.
DefaultVisualStyles – Gets or set the default visual styles for the ChartPanel and its contained elements. Each element in the ChartPanel can set its own specific style settings, and in doing so, will override these panel-wide settings.
EffectivePanelStyle – Gets a reference to the panel’s effective (cached, composite) style.
Effective style properties should not be altered, as changes made through them will be lost when the composite style is recreated, as needed for other style and programmatic changes.
LegendSource – Gets or sets the source for the items in the panel legend. This property permits the inclusion (or exclusion) of nested ChartPanel and/or ChartXy Legend items. For instance, setting the LegendSource to LegendSource.ChartXy, will cause only nested ChartXy Legend items to be included in the panel. This is useful when you wish to consolidate all subordinate Legend’s into one, parent ChartPanel Legend – but you don’t want to include ChartPanel legend items (or ChartXy legend items). The default is to include both.
The following is a list of the methods available to all ChartPanel elements (in addition to those presented for ChartContainer elements).
GetMatrixCoordAt(Point pt, ref int column, ref int row)
This method will ‘true‘ if the given Point is in a matrix cell, or ‘false‘ if not. If ‘true‘, the method will also return (via the column and row parameters) the column and row of the matrix cell.
GetMatrixCoordOf(ChartContainer item, ref int column, ref int row)
This method will ‘true‘ if the given ChartContainer item is in a matrix cell, or ‘false‘ if not. If ‘true‘, the method will also return (via the column and row parameters) the column and row of the matrix cell.
GetContainerByName(string name[, bool searchNested])
Gets the ChartContainer object from the given name, with optional searching of nested panels/charts. If found, a reference to the ChartContainer will be returned. If not found, null is returned.
GetChartByName(string name[, bool searchNested])
Gets the BaseChart from the given name, optionally searching nested panels and charts. If found, a reference to the BaseChart will be returned. If not found, null is returned. To access specific properties and methods of the returned item, it must be cast into the appropriate type (ie ChartXy).
GetPanelByName(string name[, bool searchNested])
Gets the ChartPanel from the given name, optionally searching nested panels and charts. If found, a reference to the ChartPanel will be returned. If not found, null is returned.
ChartXy
The ChartXy object is an X/Y coordinate based ‘BaseChart’. As such, it can contain X/Y related elements, such as the actual chart area, ChartSeries, and ChartAxes.
The following is a list of the Properties available to all ChartXy elements. These are in addition to the base ChartContainer properties and methods listed above.
AncillaryAxesX – Gets a reference to the collection of Ancillary X Axes – axes that can be presented in addition to the default, primary X Axis (see AxisX property). You can create and add as many ancillary X axes as you need. They can be positioned Near (bottom) or Far (top), and styled as needed.
Once an Ancillary axis is defined, it needs to be added to the AncillaryAxesX collection, and then associated with one or more series to which it applies. This is done by setting the associated series.AxisX property to the created AncillaryAxisX element.
AncillaryAxesY – Gets a reference to the collection of Ancillary Y Axes – axes that can be presented in addition to the default, primary Y Axis (see AxisY property). You can create and add as many ancillary Y axes as you need. They can be positioned Near (right) or Far (left), and styled as needed.
Once an Ancillary axis is defined, it needs to be added to the AncillaryAxesY collection, and then associated with one or more series to which it applies. This is done by setting the associated series.AxisY property to the created AncillaryAxisY element.
AutoGenSeriesCollection – Gets or sets whether series definitions are automatically generated by the Chart Control from the associated bound data. If AutoGenSeriesCollection is ‘true‘ then the DataPropertyNameSeries must also be set.
AutoGenSeriesType – Gets or sets the default SeriesType to be assigned to all auto-generated Series.
AxisX – Gets a reference to the default, primary X Axis. This axis will be used for all series created and added to a ChartXy’s ChartSeries collection, when the series.AxisX property is either set to this AxisX, or left null (ie. it becomes the default AxisX when series AxisX is unassigned).
AxisY – Gets a reference to the default, primary Y Axis. This axis will be used for all series created and added to a ChartXy’s ChartSeries collection, when the series.AxisY property is either set to this AxisY, or left null (ie. it becomes the default AxisY when series AxisY is unassigned).
BarFillRange – Gets or sets how series bars are filled by default (either according to each individual bar range, or the entire series range). Setting this property to “ByBar” will cause gradient brush definitions to fill the bar area based upon the length of the bar being filled. If set to “BySeries”, each bar will be filled based upon the maximum series bar length.
Here is what a chart looks like when its BarFillRange is set to ‘BySeries‘.
And here is the same chart when its BarFillRange is set to ‘ByBar‘.
BarLabelPosition – Gets or sets the default position of bar series labels (default is Center). Bar labels can be positioned ‘Center’, ‘Near’, ‘NearInside’, ‘Far’, or ‘FarInside’. The ‘Near’ and ‘Far’ options place the labels outside the bar, the remaining items are inside the bar area. If an outside bar label cannot be positioned as such, it will be placed inside the bar.
BarOrigin – Gets or sets the bar ‘origin’. This value is used as the base, or starting Value, from which each bar, by default, originates. The default BarOrigin for Quantitative scales is 0 (zero), and in the case of Qualitative or DateTime values, the default BarOrigin is the Actual Minimum Value for the associated axis.
The above bar chart has its BarOrigin set to ‘0’ (zero).
The following image shows the same chart with the BarOrigin set to ’16’.
BarOverlayEnabled – Gets or sets the intra-bar (or bar grouping) overlay is enabled (bars within a group are positioned overlayed on top of each other). Bars are overlayed based upon the chart’s series display order.
Here is a chart with BarOverlayEnabled set to false.
Here is the same chart with BarOverlayEnabled set to true.
BarShadingEnabled – Gets or sets whether Bar shading is enabled by default for Horizontal and Vertical Bar series. When enabled, the charting code will add a light shading to the bar. If you are pre-rendering the bar yourself (and cancel the default operation), no shading will be added.
Here is an example with BarShadingEnabled set to false.
And here is the same chart with BarShadingEnabled set to true.
BarSpacing – Gets or sets the intra-bar spacing (or spacing between bars within the same group). Value is taken as a fixed pixel size. Setting BarSpacing to 0 (zero) will disable the use of this property, and will enable the use of the set BarSpacingRatio value.
BarSpacingRatio – Gets or sets the intra-bar spacing ratio (or spacing between bars within the same group). The ratio is between the value itself and the inter-bar space (space between groups of bars) – which is always taken as 1. The BarSpacingRatio default is .2
BarWidthRatio – Gets or sets the default ratio of bar width to bar group spacing (defaults to 1 – bar width matches spacing).
BubbleIntensityMode – Gets or sets the default mode used to determine series bubble intensities. If a Bubble series has been provided with intensity data (third Y param defined in its SeriesPoints), this property tells the ChartControl how the data is to be interpreted and used. BubbleIntensityMode can be one of the following:
None – it is ignored.
Alpha – States that the value is an absolute Color Alpha value that is to be applied to the assigned series color.
Value – States that the value is a data Color Alpha value, that will be used in conjunction will all other defined intensity data values in the series to calculate the relative alpha value to apply to the assigned series color.
BubbleSizeMode – Gets or sets the default mode used to calculate series bubble sizes.
Area – Bubble size is proportional to the bubble area.
Diameter – Bubble size is proportional to the bubble diameter.
ChartLineAreaDisplayMode – Gets or sets the default Line ‘Area’ display mode. Multiple line ‘areas’ can be rendered for a series when the ChartLineAreaDisplayMode has the corresponding ChartLineDisplayMode is set as well.
ChartLineDisplayMode – Gets or sets the default display mode for SeriesType.Line series. The ChartLineDisplayMode values are bitwise values that can be ‘or-ed’ together as needed.
DisplayLine – Displays a straight line through defined series points.
DisplaySpline – Displays a spline through defined series points.
DisplayPoints – Displays each defined series point.
DisplayUnsorted – Points are displayed unsorted.
DisplayClosed – Start and end Points are connected.
ChartSeries – Gets a reference to the collection of Chart Series.
ChartSeriesVisualStyle – Gets or sets a reference to the default visual style for each chart series.
ChartVisualStyle – Gets or sets the visual style for the Chart. Styles set at the chart level will override parent styles set for the same properties (but will be added in addition to them when they do not conflict).
ConvexHullDisplayMode – Gets or sets the default ConvexHull display mode. Each series contained in the chart can have a ConvexHull presented with it. A ConvexHull is the smallest, enclosing, convex polygon that encompases and includes all points in the series. The ConvexHull can be rendered either as a background, border, or both – complete with its own styling.
ChartCrosshair – Gets a reference to the Crosshair element for the chart. The chart’s Crosshair element is just what its name implies – an X/Y crosshair that is ‘driven’ by either the X or Y axis, and intersects with one or more series points in the chart. The Crosshair can be set and styled to display callout labels or axis labels – whichever (or both) as desired.
CustomPalette – Gets or sets the custom palette for the chart. A custom array of Colors can be created and assigned to this property, in order to define a new palette of colors for the chart control to utilize, in place of the predefined color group palette choices (see PaletteGroup property).
DataLabelOverlapMode – Gets or sets the mode for resolving overlapping series data labels. When the presentation of DataLabels (and/or PointLabels) are enabled (see PointLabelDisplayType), there is always the possibility of one label overlapping another. When that occurs, this property informs the ChartControl how to attempt to resolve the overlap.
ShowOverlapping – No extra processing takes place. Labels are permitted to overlap.
HideOverlapping – All labels that could not be positioned without overlapping other labels, will be hidden and not displayed.
RotateAroundPoint – When a label overlaps another, this option tells the ChartControl to attempt to move the label by rotating around the defined label point until it no longer overlaps another label.
Although great effort is made to locate a “free” label position, locating such a spot is not always possible. Data labels will be positioned irrespective of other data series and points.
DataLabelVisualStyle – Gets or sets the default visual style for the chart DataLabel’s.
DataMember – Gets or sets the name of the list or table in the data source that the Chart is bound to.
DataPropertyNameSeries – Gets or sets the default name of the data field to which the Series Name is bound.
DataPropertyNameX – Gets or sets the default name of the data field to which the X-Axis data is bound.
DataPropertyNamesY – Gets or sets the default names of the data fields to which the Y-Axis data is bound.
DataSource – Gets or sets the data source that the Chart is bound to.
EffectiveChartSeriesStyle – Gets a reference to the ChartSeries effective (cached, composite) style.
Effective style properties should not be altered, as changes made through them will be lost when the composite style is recreated, as needed for other style and programmatic changes.
EffectiveChartStyle – Gets a reference to the Chart’s Effective (cached, composite) style.
Effective style properties should not be altered, as changes made through them will be lost when the composite style is recreated, as needed for other style and programmatic changes.
EffectiveDataLabelStyle – Gets a reference to the DataLabel Effective (cached, composite) style.
Effective style properties should not be altered, as changes made through them will be lost when the composite style is recreated, as needed for other style and programmatic changes.
MaxValueX – Gets the calculated maximum X value (composite value of all associated series).
MaxValueY – Gets the calculated maximum Y value (composite value of all associated series).
MinValueX – Gets the calculated minimum X value (composite value of all associated series).
MinValueY – Gets the calculated minimum Y value (composite value of all associated series).
PaletteGroup – Gets or sets the palette color group to use (Light/Medium/Dark/Color1/Color2/MonoBlue/etc). When a series is allocated, a default palette color is assigned to the series. That color will be used for the series if the series style color values are not set by the application.
PointLabelDisplayMode – Gets or sets the default display mode for the chart PointLabels/DataLabels. PointLabes are comprised us system generated labels for defined series points, and labels defined by the user (DataLabels). This property informs the ChartControl which types of points (and/or labels) are to be displayed. The property values are bit field values, and as such can be ‘or-ed’ together to produce the labels needed.
None – No labels will be presented.
AllSeriesPoints – All defined series points will have a label presented.
DataLabels – User defined DataLabels will be displayed.
MinValueX – The minimum X value will have a label displayed.
MinValueY – The minimum Y value will have a label displayed.
MaxValueX – The maximum X value will have a label displayed.
MaxValueY – The maximum Y value will have a label displayed.
ReversePaletteColors – Gets or sets whether default palette colors are utilized in reverse order.
SeriesDisplayOrder – Gets or sets the order in which the chart series are displayed (controls how they the series overlap each other). It can either be set to ‘Forward‘ or ‘Reverse‘. Default is ‘Forward‘.
StepLines – Gets or sets which ‘Step lines’ are displayed by default. This value can be either ‘None‘, ‘Horizontal‘, ‘Vertical‘, or ‘Both‘ (or ‘NotSet‘, which defaults to ‘Both’).
StepLineMode – Gets or sets the default mode (or order of rendered Step Lines) used to render “Step Lines” in the defined Line series. Set value can be ‘None‘, ‘HorizontalThenVertical‘, ‘VerticalThenHorizontal‘ or ‘MidPoint‘ (or ‘NotSet, which defaults to ‘HorizontalThenVertical‘).
The following has StepLineMode set to ‘HorizontalThenVertical‘:
The following is the same chart with StepLineMode set to ‘VerticalThenHorizontal‘:
And finally, the same chart with StepLineMode set to ‘MidPoint‘:
The following is a list of the methods available to all ChartXy elements (in addition to those presented for ChartContainer elements).
GetLocalAdjustedPoint(Point pt)
Gets the local, scroll adjusted point, from the given point. This routine adjusts the given point for scrolling that may have occurred as a result of being scrolled/panned (either itself or as a result of a parent container being scrolled).
IsCrosshairSeriesPoint(ChartSeries series, Point pt)
Gets whether the given Point is a Crosshair displayed point for the provided series.
EnsureVisible(bool center)
Ensures the container is visible on screen, and optionally centered (if possible).
EnsureVisible(ChartContainer item, bool center)
Ensures that the given container “item” is visible on screen, and optionally centered (if possible).
GetElementAt(Point pt)
Gets the visual chart element at the given Point (ie. ChartLegend, ChartTitle, etc) – or null if no element is present at the point.
GetHitArea(Point pt)
Gets the logical ‘hit’ area of the chart for the given Point (ie. InContent, etc).
GetPointFromValue(ChartSeries series, SeriesPoint sp)
GetPointFromValue(ChartSeries series, object pointValueX, object pointValueY)
The above 2 methods return the local adjusted point from the given series and data values. In the first case, a SeriesPoint is given. In the second case the actual X and Y data values are provided.
ChartAxis
The ChartAxis object is the object which defines the attributes and behavior of all defined primary and ancillary axes in the ChartControl.
The following is a list of the Properties available to all ChartAxis elements.
ActualDateTimeUnits – Gets the actual axis display units for DateTime data (as determined by either the DateTimeUnits property or actual inspection of the associated data). DateTimeUnits can be Ticks, Milliseconds, Seconds, Minutes, Hours, Days, Months, or Years.
ActualMaxValue – Gets the actual, axis max data value (as determined by either the MaxValue property or actual inspection of the associated data).
ActualMinValue – Gets the actual, axis min data value (as determined by either the MinValue property or actual inspection of the associated data).
AxisAlignment – Gets or sets the axis alignment. For an X-Axis, Near (bottom) or Far (top). For an Y-Axis, Near (right) or Far (left).
AxisFarMargin – Gets or sets the far/ending margin for the axis. When set ( >= 0 ), the value overrides the general AxisMargins setting for the far margin.
AxisMargins – Gets or sets the beginning and ending pixel margins for the axis (ignored when set to < 0 or AutoCalcAxisMargins is true). The AxisMargins setting is applied to both the left and right margins (for an X axis), or both the top and bottom margins (for a Y axis). The default is 20.
AxisNearMargin – Gets or sets the near/beginning margin for the axis. When set ( >= 0 ), the value overrides the general AxisMargins setting for the near margin.
AxisOrientation – Gets the axis orientation (X/Y).
AxisStripes – Gets a reference to the collection of AxisStripes associated with the axis. AxisStripes are “stripes” or a defined range between 2 values on the axis. This range, or stripe, can overlap other stripes, and is used to denote a property or attribute of a range of values on the axis. AxisStripes can be shown or hidden, and can be placed in the chart legend, if desired.
ChartAxisVisualStyle – Gets or sets the visual style for the Axis.
CrosshairLabelVisualStyle – Gets or sets the visual style to be used for Crosshair elements associated with the axis.
DateTimeUnits – Gets or sets the axis display units for DateTime data. DateTimeUnits can be Ticks, Milliseconds, Seconds, Minutes, Hours, Days, Months, or Years.
EffectiveAxisStyle – Gets a reference to the Axis’ Effective (cached, composite) style.
Effective style properties should not be altered, as changes made through them will be lost when the composite style is recreated, as needed for other style and programmatic changes.
EffectiveCrosshairLabelStyle – Gets a reference to the CrosshairLabel’s Effective (cached, composite) style.
Effective style properties should not be altered, as changes made through them will be lost when the composite style is recreated, as needed for other style and programmatic changes.
GridInterval – Gets or sets the grid interval (the distance between MajorTickmarks, in pixels). If left unset, the ChartControl will auto-calculate this value based upon the data and the space available to the chart.
GridSpacing – Gets or sets the numerical spacing between MajorTickmarks (such as 1, 10, 100, …).
IsPrimaryAxis – Gets whether the axis is a Primary axis.
MajorGridLines – Gets a reference to the axis MajorGridLines element. MajorGridLines are directly associated with the MajorTickmarks, but they are not directly linked, meaning that they can be independently displayed, but are always establish at the same axis values. MajorGridLines appear in the content area as a grid, whose lines are fully configurable by their associated style components.
MajorTickmarks – Gets a reference to the axis MajorTickmarks element. MajorTickmarks are directly associated with the MajorGridLines, but they are not directly linked, meaning that they can be independently displayed, but are always establish at the same axis values. MajorTickmarks can either appear inside or outside the content area – or be displayed in both areas. MajorTickmarks are fully configurable by their associated style components.
MaxValue – Gets or sets the maximum axis data value. Normally the maximum data value is “discovered” or calculated by the ChartControl based upon inspection of the chart’s series data. You can, however, tell the chart control what the maximum value is by this property. The ActualMaxValue can be inspected to determine what the actual maximum is, should that be needed.
MinorGridLines – Gets a reference to the axis MinorGridLines element. MinorGridLines are directly associated with the MinorTickmarks, but they are not directly linked, meaning that they can be independently displayed, but are always establish at the same axis values. MinorGridLines appear in the content area as a grid, whose lines are fully configurable by their associated style components.
MinGridInterval – Gets or sets the minimum grid interval size. This is the distance (in pixels) between MajorTickmark layout items.
MinorTickmarks – Gets a reference to the axis MinorTickmarks element. MinorTickmarks are directly associated with the MinorGridLines, but they are not directly linked, meaning that they can be independently displayed, but are always establish at the same axis values. MinorTickmarks can either appear inside or outside the content area – or be displayed in both areas. MinorTickmarks are fully configurable by their associated style components.
MinValue – Gets or sets the minimum axis data value. Normally the minimum data value is “discovered” or calculated by the ChartControl based upon inspection of the chart’s series data. You can, however, tell the chart control what the minimum value is by this property. The ActualMinValue can be inspected to determine what the actual minimum is, should that be needed.
ReferenceLines – Gets a reference to the collection of axis ReferenceLines. Any number of ReferenceLines can be defined for a given axis. ReferenceLines are simply a mechanism to mark a value or threshold on the axis by rendering a line across the chart. The line can be styled as desired, and a text label can be associated with it to further highlight its “message”.
Title – Gets a reference to the axis Title. Each axis can have its own associated title, which is fully configurable, as other Title elements in the Chart Control.
UseAlternateBackground – Gets or sets whether the axis utilizes the alternate background color. The alternate background color is used between every other defined MajorTickmark. Its style attributes can be set via the ChartAxisVisualStyle.
UseAutoMinGridInterval – Gets or sets whether the auto-calculated minimum grid interval will be used in determining the axis major tickmark interval. This may be important for you to use if you want to “compress” the data display so that more data can fit on the chart without scrolling. This can be used in-conjunction with MinGridInterval (which guarantees that the interval between majot tickmarks is a minimum amount) to reduce – or remove – the added display space. Note that doing so may make the data less readable (or unreadable if totally removed), but in some cases this may be desirable. The default value is ‘true‘.
The following is a list of the methods available to all ChartAxis elements .
GetPointFromValue(object value)
Gets the local, scroll adjusted chart Point from the given data value.
GetValueFromPoint(Point pt)
Gets the “Data” value from the given Chart Point.
EnsureVisible(object value[, bool center])
Ensures the given data value is visible and optionally centered on screen (as much as possible).
ChartSeries
The ChartSeries object is the object which defines the attributes, data, and behavior of all defined chart series.
The following is a list of the Properties available to all ChartSeries elements.
ActualScaleTypeX – Gets the Actual X axis Scale Type as discovered by inspection of the actual series data values. The ScaleType can be DateTime, Quantitative, or Qualitative.
ActualScaleTypeY – Gets the Actual Y axis Scale Type as discovered by inspection of the actual series data values. The ScaleType can be DateTime, Quantitative, or Qualitative.
AxisX – Gets a reference to the X-Axis associated with the series. If null, the series will automatically be associated with the default, primary axis as defined via the chartXy.AxisX property. If non-null, it must be set to a previously defined chartXy.AncillaryAxisX element.
AxisY – Gets a reference to the Y-Axis associated with the series. If null, the series will automatically be associated with the default, primary axis as defined via the chartXy.AxisY property. If non-null, it must be set to a previously defined chartXy.AncillaryAxisY element.
BarFillRange – Gets or sets how series bars are filled (either according to each individual bar range, or the entire series range). Setting this property to “ByBar” will cause gradient brush definitions to fill the bar area based upon the length of the bar being filled. If set to “BySeries”, each bar will be filled based upon the maximum series bar length.
BarLabelPosition – Gets or sets the position of bar series labels (default is Center). Bar labels can be positioned ‘Center’, ‘Near’, ‘NearInside’, ‘Far’, or ‘FarInside’. The ‘Near’ and ‘Far’ options place the labels outside the bar, the remaining items are inside the bar area. If an outside bar label cannot be positioned as such, it will be placed inside the bar.
BarShadingEnabled – Gets or sets whether Bar shading is enabled for Horizontal and Vertical Bar series. When enabled, the charting code will add a light shading to the bar. If you are pre-rendering the bar yourself (and cancel the default operation), no shading will be added.
BarWidthRatio – Gets or sets the ratio of bar width to bar group spacing (defaults to 1 – bar width matches spacing).
BubbleIntensityMode – Gets or sets the mode used to determine series bubble intensities. If a Bubble series has been provided with intensity data (third Y param defined in its SeriesPoints), this property tells the ChartControl how the data is to be interpreted and used.
None – it is ignored.
Alpha – States that the value is an absolute Color Alpha value that is to be applied to the assigned series color.
Value – States that the value is a data Color Alpha value, that will be used in conjunction will all other defined intensity data values in the series) to calculate the relative alpha value to apply to the assigned series color.
BubbleMaxPercentage – Gets or sets the max percentage of the display area used to calculate series bubble sizes. The ChartControl will take the smaller of the chart width and height and use that with the BubbleMaxPercentage to calculate the max bubble size permitted in the chart. Default is .25 (or 25%).
BubbleMinSize – Gets or sets the minimum series bubble size (in pixels). Default is 4.
BubbleScaleFactor – Gets or sets the Scale Factor used to calculate series bubble sizes. The default is 1. A setting of 2, will double the size of the bubbles, 3 will triple, .5 will make them half the normal size, etc.
BubbleSizeMode – Gets or sets the mode used to calculate series bubble sizes.
Area – Bubble size is proportional to the bubble area.
Diameter – Bubble size is proportional to the bubble diameter.
ChartIndicators – Gets a reference to the collection of Chart Indicators. ChartIndicators can be either TrendLines or RegressionLines. Each series can have any number of TrendLines – which is simply a stylized line connecting any 2 defined series points. Each series can also have a least squares RegressionLine displayed for them.
ChartLegendItemVisualStyles – Gets or sets the visual styles for the Legend item associated with the series. Legend items can be stylized for Default, MouseOver and Selection.
ChartLineAreaDisplayMode – Gets or sets the Line ‘Area’ display mode. Multiple line ‘areas’ can be rendered for a series when the ChartLineAreaDisplayMode has the corresponding ChartLineDisplayMode is set as well.
ChartLineDisplayMode – Gets or sets the display mode for SeriesType.Line series. The ChartLineDisplayMode values are bitwise values that can be ‘or-ed’ together as needed.
DisplayLine – Displays a straight line through defined series points.
DisplaySpline – Displays a spline through defined series points.
DisplayPoints – Displays each defined series point.
DisplayUnsorted – Points are displayed unsorted.
DisplayClosed – Start and end Points are connected.
ChartSeriesVisualStyle – Gets or sets the visual style for the series.
ConvexHullDisplayMode – Gets or sets the ConvexHull display mode. A ConvexHull is the smallest, enclosing, convex polygon that encompases and includes all points in the series. The ConvexHull can be rendered either as a background, border, or both – complete with its own styling.
CrosshairEnabled – Gets or sets whether Crosshair support is enabled for the series.
CrosshairHighlightPoints – Gets or sets whether Crosshair Point highlighting is enabled for the series. If this property is set to ‘true‘, when the chart crosshair intersects with a point in the series, the point will be “highlighted” (as can the PointLabel/DataLabel associated with it).
CrosshairShowLabels – Gets or sets whether Crosshair labels are shown for the series. Crosshair labels are callout style labels that display common (or individual) data pertaining to the intersected point(s).
DataLabels – Gets or sets the list of user defined instance Data Labels. Instance data labels can be created for any point in the chart (even if the point is not contained in the series). It will display as a normal PointLabel (as generated by the Chart Control), and is fully configurable as an individual element.
DataLabelVisualStyle – Gets or sets the visual style for the data labels.
DataPropertyNameSeries – Gets or sets the name of the data field, from the bound data source, to which the Series Name is bound.
DataPropertyNameX – Gets or sets the name of the data field to which the X-Axis data is bound.
DataPropertyNamesY – Gets or sets the collection of names of the data fields to which the Y-Axis data is bound.
DataMember – Gets or sets the name of the list or table in the data source that the Series is bound to.
DataSource – Gets or sets the data source that the Series is bound to.
DefaultPaletteColor – Gets the default palette color assigned to the series when it is added to the chart.
DisplayLinePointsOnTop – Gets or sets whether series points are displayed on top of series line.
EffectiveDataLabelStyle – Gets a reference to the DataLabel effective (cached, composite) style.
Effective style properties should not be altered, as changes made through them will be lost when the composite style is recreated, as needed for other style and programmatic changes.
EffectiveSeriesStyle – Gets a reference to the Series’s effective (cached, composite) style.
Effective style properties should not be altered, as changes made through them will be lost when the composite style is recreated, as needed for other style and programmatic changes.
EmptyValues – Gets or sets the collection of values used to determine if a series point is empty or missing.
EnableEmptyValues – Gets or sets whether EmptyValues are processed in the series. Default is ‘false‘.
GroupId – Gets or sets the logical grouping Id used to group qualitative series. Each series has a GroupId associated with it. This GroupId can be used to direct the Chart Control how multiple Qualitative series, of the same GroupId, are ‘stacked’ together in the same logical ‘column’ (see StackQualitativePoints).
In the following image, the ‘yearly’ series and the ‘Average’ series have their GroupId set to ‘0’ (the default). The ‘Projection’ series has its GroupId set to ‘1’.
The ‘yearly’ series has StackQualitativePoints set to ‘true’, while the ‘Average’ series has StackQualitativePoints set to ‘false’. For the ‘Projection’ series, it does not matter what StackQualitativePoints is set to, as there are no other series present in that same group.
HiLoBarType – Gets or sets the Series HiLoBar Type. The HiLoBar type can be one of the following:
Line
HiLoBarType Line specifies that the HiLoBar is to be displayed using only lines (no Boxes are present, as with both Box and Candle displays). The “range” (High/Low) values are represented by the entire length of the HiLo line. The “Open” value is presented as a tickmark/line on the left (when vetrical) or top (when horizontal) of the range line. The “Close” value is presented as a tickmark/line on the right (when vetrical) or bottom (when horizontal) of the range line. When “Median” values are provided (and displayed), they are represented as a tick-line that equidistantly crosses the range line at the median value.
Box
HiLoBarType Box specifies that the HiLoBar is to be displayed using a combination of lines (or Whiskers) and an Open/Close Box. The Whiskers extend from the top and bottom of the display (when displayed vertically) or the left and right (when displayed horizontally). The Whiskers denote the High and Low values, whereas the Box denotes the Open and Close values.
– UseAlternateSegmentStyle defaults to “False” for a Box display.
– When “Median” values are supplied, the Box display marks the median value with a line that crosses the display box. When the Close value is greater than the Open value, the upper portion of the box (or the entire area, when no Median value is specified) is filled with the “Default” background, with the lower portion (if a Median value is specified) being filled with the Alternate background. When the Open value is greater than the Close value, then the background areas are swapped and filled with the opposite background values.
Candle
HiLoBarType Candle specifies the High, Low, Open, and Close values identically to the HiLoBarType Box type. There are two main differences between the Candle and Box displays, and they are as follows:
– UseAlternateSegmentStyle defaults to “True” for a Candle display, whereas it defaults to “False” for all other displays (both Line and Box).
– When “Median” values are supplied, the Candle display marks the median value with a line that crosses the display box, identically to the Box display, however, the Box background is filled in a slightly different manner. The box background is always completely filled with either the default or alternate Box background (depending upon the direction of change between the Open and Close values), with no variance in the background with respect to the displayed median.
IsDisplayed – Gets whether the series is displayed in the chart (based upon Visibility and Legend check state).
MaxValueX – Gets the series maximum X value.
MaxValueY – Gets the series maximum Y value.
MinValueX – Gets the series minimum X value.
MinValueY – Gets the series minimum Y value.
PointLabelDisplayMode – Gets or sets the display mode for the series PointLabels/DataLabels. PointLabes are comprised of system generated labels for defined series points, and labels defined by the user (DataLabels). This property informs the ChartControl which types of points (and/or labels) are to be displayed. The property values are bit field values, and as such can be ‘or-ed’ together to produce the labels needed.
None – No labels will be presented.
AllSeriesPoints – All defined series points will have a label presented.
DataLabels – User defined DataLabels will be displayed.
MinValueX – The minimum X value will have a label displayed.
MinValueY – The minimum Y value will have a label displayed.
MaxValueX – The maximum X value will have a label displayed.
MaxValueY – The maximum Y value will have a label displayed.
PointLabelMinDistance – Gets or sets the minimum distance between label data points.
PointLabelSkip – Gets or sets the number of inter-label points to skip. In other words, if the PointLabelSkip value is set to ‘1’, then every other label is skipped. If it is set to ‘2’, then there will be to labels skipped for every label displayed.
ScaleTypeX – Gets or sets the X axis Scale Type (which can be DateTime, Quantitative, or Qualitative).
ScaleTypeY – Gets or sets the Y axis Scale Type (which can be DateTime, Quantitative, or Qualitative).
SeriesPoints – Gets a reference to the collection of SeriesPoints. (See SeriesPoints description).
SeriesType – Gets or sets the Series Type. SeriesType can be Bubble, HorizontalDot, VerticalDot, Point, Line. A series SeriesType can be changed dynamically, however, doing so may not always make sense, given the data and/or axis definitions. For example, the data provided for a HorizontalDot plot series will make little to no sense to a Bubble series plot. Default is ‘Point‘.
ShowEmptyLines – Gets or sets whether EmptyLines are shown in the series. EmptyLines can be rendered by the ChartControl where EmptyValues are present. EmptyLines are simply rendered between the non-missing, adjacent SeriesPoints. Default is ‘false‘.
ShowEmptyPoints – Gets or sets whether EmptyPoints are shown in the series. EmptyPoints can be rendered for each EmptyValue that is encountered. EmptyPoints positions are calculated based upon the non-missing, adjacent SeriesPoints. Default is ‘false‘.
ShowOriginValueLabels – Gets or sets whether labels are shown for ‘Origin’ data values.
StackQualitativePoints – Gets or sets whether Qualitative points are stacked or spread across the associated grouped column.
In the following 2 images, there are 6 defined series – 5 “Yearly Donation” series (colored bars), and a single “Average Donation” series (green triangle). The “Yearly Donation” series are are associated with one group (see above GroupId) and the “Average” series is associated with another.
The first image has StackQualitativePoints set to ‘true‘.
As a result all series with the same GroupId are “stacked” in the same qualitative ‘column‘.
The second image has StackQualitativePoints set to ‘false‘.
As a result all series are displayed in their own qualitative ‘columns‘.
StepLines – Gets or sets which ‘Step lines’ are displayed. This value can be either ‘None‘, ‘Horizontal‘, ‘Vertical‘, or ‘Both‘ (or ‘NotSet‘, which defaults to ‘Both’).
StepLineMode – Gets or sets the mode (or order of rendered Step Lines) used to render “Step Lines” in the defined Line series. Set value can be ‘None‘, ‘HorizontalThenVertical‘, ‘VerticalThenHorizontal‘ or ‘MidPoint‘ (or ‘NotSet, which defaults to ‘HorizontalThenVertical‘).
The following is a list of the methods available to all ChartSeries elements .
RefreshSeries()
Causes the series to refresh its display, as the underlying series data (potentially) has changed in some way.
IsConvexHullPoint(SeriesPoint sp)
Returns whether the given SeriesPoint is a ConvexHull point (ie. one of the SeriesPoints comprising the calculated ConvexHull border for the series).
IsHighLightPoint(SeriesPoint sp)
Determines if the given SeriesPoint is a HighLight Point (ie. a point highlighted by the Crosshair configuration).
ChartLegend
The ChartLegend object presents the LegendItems for each chart element supporting the ILegendItem interface (ChartSeries, TrendLines, RegressionLines, ReferenceLines, and AxisStripes). User defined LegendItems can also be added to support specific legend-centric user operations.
The following is a list of the Properties available to all ChartLegend elements.
Alignment – Gets or sets the alignment of the legend with respect to the chart (ie TopLeft, MiddleLeft, BottomRight, etc).
AlignVerticalItems – Gets or sets whether vertical items are aligned in the legend (used when multiple columns are presented).
The following image shows the alignment of the legend items when AlignVerticalItems is set to ‘false’.
The following image shows the alignment of the legend items when AlignVerticalItems is set to ‘true’.
ChartLegendItemVisualStyles – Gets or sets the default visual styles for the Legend items.
ChartLegendVisualStyles – Gets or sets the visual styles for the Legend.
CheckBoxSize – Gets or sets the default size of the item CheckBoxes. The default is 15 x 15.
CombineLikeItems – Gets or sets whether ‘like‘ subordinate items (items with same Names) are combined into a single item.
Direction – Gets or sets the display direction of the items within the legend. Direction can be LeftToRight, RightToLeft, TopToBottom, or BottomToTop.
EffectiveItemStyles – Gets a reference to the legend’s item Effective (cached, composite) styles
Effective style properties should not be altered, as changes made through them will be lost when the composite style is recreated, as needed for other style and programmatic changes.
EffectiveStyles – Gets a reference to the legend’s Effective (cached, composite) styles.
Effective style properties should not be altered, as changes made through them will be lost when the composite style is recreated, as needed for other style and programmatic changes.
EnablePanning – Gets or sets whether the Legend can be “panned” (scrolled vertically by click-and-drag in the content area). Default is ‘true‘.
ItemCheckAction – Gets or sets the “action” taken when a LegendItem is checked. The available actions are ‘None‘ (no action is taken), or ‘ShowItem‘ (item is either shown or hidden based upon the check state). Default is ‘ShowItem‘.
ItemSortDirection – Gets or sets the item sort direction (sorted by LegendItem Text). Valid values are ‘None‘, ‘Ascending‘, or ‘Descending‘. Default is ‘None‘.
ItemTextOffset – Gets or sets the offset between the marker (or Checkbox) and the item text. Default is 2.
LegendItems – Gets a reference to the collection of LegendItems.
MarkerSize – Gets or sets the default size of the item marker.
MaxHorizontalPct – Gets or sets the maximum horizontal size of the legend when sizing the Legend. The value is specified as a percentage of the displayed chart size. The default is 100.
MaxVerticalPct – Gets or sets the maximum vertical size of the legend when autosizing. The value is specified as a percentage of the displayed chart size.. The default is 100.
MinContentSize – Gets or sets the minimum size of the content area of the legend.
Placement – Gets or sets the placement of the legend with respect to the chart. Placement can be ‘Inside‘ or ‘Outside‘ the chart content area. Placement defaults to ‘Outside‘.
ScrollBounds – Gets the Scrollable bounds.
ScrollBoundsEx – Gets the extended Scrollable bounds. This is the ‘extended’, or actual content area of the container (not just the visible area on screen). The area can be larger than MinContentSize, but will never be smaller (see MinContentSize).
ScrollBoundsOffset – Gets the current horizontal and vertical offsets (see VScrollOffset).
ShowCheckBoxes – Gets or sets whether checkboxes are shown in the legend. Default is ‘false‘.
ShowItemText – Gets or sets whether LegendItem Text values are shown in the legend. Default is ‘true‘.
ShowMarkers – Gets or sets whether LegendItem markers are shown in the legend.
VScrollBar – Gets a reference to the Legend’s vertical scrollbar.
VScrollBarWidth – Gets or sets the width of a vertical scrollBar. Default is ‘9’.
VScrollOffset – Gets or sets the Legend’s vertical scrollbar offset.
VScrollBarVisible – Gets or sets whether Vertical Scrollbar is shown (due to the content of the control exceeding available height).
The following is a list of the methods available to all ChartLegend elements .
GetElementAt(Point pt)
Gets the legend element at the given local adjusted Point.
GetLegendItem(ILegendItem chartItem)
Gets the LegendItem from the given chart item supporting the ILegendItem interface.
ChartIndicators
ChartIndicators can be either TrendLines or RegressionLines. Each series can have any number of TrendLines – which is simply a stylized line connecting any 2 defined series points. Each series can also have a least squares RegressionLine displayed for it.
The following is a list of the Properties available for each TrendLine element.
EffectiveStyles – Gets a reference to the TrendLine’s effective (cached, composite) style.
Effective style properties should not be altered, as changes made through them will be lost when the composite style is recreated, as needed for other style and programmatic changes.
IndicatorType – Gets the TrendLine’s IndicatorType (‘TrendLine‘).
IsDisplayed – Gets whether the TrendLine is displayed in the chart (based upon Visibility and Legend check state).
ValueYIndex – Gets or sets the ValueY index to use for the slope/intercept calculation.
ValueX1 – Trendline starting X value.
ValueX2 – Trendline ending X value.
The following is a list of the Properties available for each RegressionLine element.
TrendLineVisualStyle – Gets or sets a reference to the visual style for the TrendLine Indicator.
EffectiveStyles – Gets a reference to the RegressionLine’s effective (cached, composite) style.
Effective style properties should not be altered, as changes made through them will be lost when the composite style is recreated, as needed for other style and programmatic changes.
IndicatorType – Gets the RegressionLine’s IndicatorType (‘RegressionLine‘).
IsDisplayed – Gets whether the RegressionLineis displayed in the chart (based upon Visibility and Legend check state).
Intercept – Gets the RegressionLine’s calculated intercept (ie. the ‘b’ portion of ‘y = mx + b’).
RegressionLineVisualStyle – Gets or sets a reference to the visual style for the RegressionLine Indicator.
Slope – Gets the RegressionLine’s calculated slope (ie. the ‘m’ portion of ‘y = mx + b’)
DataLabels
DataLabel objects define a label Point and label Text associated with that Point.
The following is a list of the Properties available for each DataLabel element.
DataLabelVisualStyle – Gets or sets the visual style for the data label.
EffectiveDataLabelStyle – Gets a reference to the DataLabel effective (cached, composite) style.
Effective style properties should not be altered, as changes made through them will be lost when the composite style is recreated, as needed for other style and programmatic changes.
ValueX – Gets or sets the X-Axis Value associated with the label.
ValueY – Gets or sets the Y-Axis Value associated with the label.
Text – Gets or sets the DataLabel text. DataLabel text can be specified using format specifiers. Available specifiers are as follows:
‘X’ – Specifies the X data value.
‘Y[n]’ – Specifies the Y data value. ‘n’ can optionally be specified to index into the ValueY collection.
‘S’ – Specifies the Series Name.
For example:
dataLabel.Text = “Series ‘{S}’ XValue={X:F3}, Y0Value={Y:C}, Y2Value={Y2:F3}!”;
Will produce labels that look like
“Series ‘MySeries1’ XValue=123, Y0Value=$10.45, Y2Value=288!”
SeriesPoints
SeriesPoints are ‘data points’ used to define instances on the chart for a given series. A SeriesPoint consists of a single X-Value (or argument) and one or more Y-Values. Each series type (Point, Line, Bar, Bubble, etc) accepts and processes varying SeriesPoint data.
The following is a list of the current available constructors for creating a SeriesPoint:
SeriesPoint()
Creates a SeriesPoint with ValueX = 0 (int zero), and ValueY[0] = 0 (int zero).
SeriesPoint(object xValue)
Creates a SeriesPoint with ValueX = xValue, and no ValueY elements defined.
SeriesPoint(object xValue, object yValue)
Creates a SeriesPoint with ValueX = xValue, and ValueY[0] = yValue.
SeriesPoint(object xValue, object[] yValue)
Creates a SeriesPoint with ValueX = xValue, and ValueY[] = yValue. This constructor can be used for all SeriesPoint allocations, but is especially needed for creating SeriesPoints that require multiple ValueY elements – such as is needed for the following items:
Bar Series: X Position : Y position[[, bar start value][, bar origin]].
17.57, [185] // x, end y value
84, [185, 100] // x, end y value, start y value
“USA”, [450.50, 125.75, 300.00] // x, end y value, start y value, origin
HiLoBar Series: X Position : Y position[high, low [, close [, open [, median [, …]]]]].
23.50, [18.33, 6.50] // x, high, low
84, [185, 100, 175] // x, high, low, close
94, [185, 100, 175, 125] // x, high, low, close, open
“USA”, [20, 5, 19, 7, 15, 8,11] // x, high, low, close, open, median, …
Bubble series: X Position : Y position[[, bubble size][, bubble intensity]].
10, [15, 100, 255] // x, y value, size, intensity
“USA”, [14.65, 11300] // x, y value, size
DotPlot Series: X Position : [count]
10 // x, y value count will default to 1
5, [15] // x, y value count
SeriesPoint(object xValue, object yValue, object size)
Creates a SeriesPoint with ValueX = xValue, and ValueY[0] = yValue and ValueY[1] = size. This constructor is targeted at creating Bubble series data elements where the xValue and yValue define the point position, and the ‘size’ defines the bubble size.
SeriesPoint(object xValue, object yValue, object size, object intensity)
Creates a SeriesPoint with ValueX = xValue, and ValueY[0] = yValue, ValueY[1] = size, and ValueY[2] = intensity. This constructor is targeted at creating Bubble series data elements where the xValue and yValue define the point position, the ‘size’ defines the bubble size, and ‘intensity’ defined the bubble intensity.
PieChart
The PieChart object is based upon the root ‘BaseChart’ object. It is a “radial” orientated display, and as such, it can contain only radial orientated elements (e.g. PieSeries elements).
The following is a list of the Properties available to all PieChart objects. These are in addition to the base ChartContainer properties and methods listed above.
ActualInnerRadius – Gets the actual, calculated inner pixel radius of the pie.
ActualOuterRadius – Gets the actual, calculated outer pixel radius of the pie.
CenterFirstSlice – Gets or sets whether the first pie slice is centered on the starting angle, or starts precisely on the starting angle. Default is false.
The above first image shows a pie chart with the StartAngle set to 270 degrees, the SweepDirection set to Clockwise, and CenterFirstSlice set to false, the second image shows the same chart with CenterFirstSlice set to true.
CenterLabel – Gets or sets the text to use for the pie center (or “donut” hole) label. The Center Label can be fully stylized, it also supports the DotNetBar Mini-Markup language, if enabled. (See EnableCenterLabelMarkup).
The above pie chart has its CenterLabel set to the currently selected pie slices (ie. those shown with a hatched background).
CenterLabelVisibility – Gets or sets the mode used to determine if/when to display the center label.
Always – The center label is always visible.
Never – The center label is Never shown.
MouseOver – The center label is only shown on MouseOver.
CenterPoint – Gets the calculated center Point for the pie.
CenterPos – Gets or sets the offset from the default x,y center location of the chart. If the values are between -1 and 1, then the offsets are taken as a percentage of the width/height, otherwise they are taken as absolute pixel offsets.
ChartSeries – Gets a reference to the collection of PieSeries.
ChartVisualStyles – Gets or sets the visual style for the Chart.
CustomPalette – Gets or sets the custom palette for the chart.
DetachedOffset – Gets or sets the default offset distance of a slice from the pie center, as measured by a percentage of the pie radius (if less than 1), or absolute pixel amount (if greater than 1). A value of 0 will restore the slice to its original position in the pie (which may still be offset, if the pie is “exploded”). Default is .1
Non-Detached Pie Slices Detached Pie Slices
EffectiveChartStyle – Gets a reference to the PieChartVisualStyle effective (cached, composite) style.
Effective style properties should not be altered, as changes made through them will be lost when the composite style is recreated, as needed for other style and programmatic changes.
EffectivePieCenterStyles – Gets a reference to the PieCenterVisualStyle effective (cached, composite) style.
Effective style properties should not be altered, as changes made through them will be lost when the composite style is recreated, as needed for other style and programmatic changes.
EnableCenterLabelMarkup – Gets or sets whether text-markup support is enabled for the CenterLabel.
The above pie chart has its CenterLable set to the following:
“<div align=\”center\”><font size=\”+20\”>” +
String.Format(“{0:00}:{1:00}:{2:00}”, minutes, seconds, tenths) +
“</font><br/>” + installState + “</div>”;
Here is another example, where the label has utilized the Mini-Markup language to add a hyper-link to a CDC article providing information about preventing chronic disease.
And here is the text assigned to the above label:
pieChart.CenterLabel = “<div align=\”center\”>Top Five Dyads” +
“<br/><br/><a href=\”https://www.cdc.gov/pcd/issues/2013/12_0308.htm\”>” +
“See CDC \”Preventing Chronic Disease\”</a></div>”;
chartControl1.PieCenterMarkupLinkClick += chartControl1_PieCenterMarkupLinkClick;
EnableDragDetach – Gets or sets whether the user can, by default, detach slices of the pie by Click and drag.
EnableShiftDragExplode – Gets or sets whether the user can explode the pie by ShiftClick and drag.
ExplodedMargin – Gets or sets the Margin between each series when the pie is Exploded. The Margin is measured as a percentage of the pie radius (if less than or equal to 1) or the absolute pixel amount (if less than or equal to 1). Default is .1.
The ExplodedMargin is used when multiple series are defined in the same pie. Its overall effect is to provide a ‘delayed’ explode offset between inner series.
ExplodedOffset – Gets or sets the offset of each slice from the pie center when the pie is Exploded. The offset is measured as a percentage of the pie radius (if less than or equal to 1) or the absolute pixel amount (if less than or equal to 1). Default is .1.
The ExplodedOffset and DetachedOffset values are additive, as each slice will be offset from the pie center by its DetachedOffset (if the slice ‘IsDetached’) and the current ExplodedOffset (if the pie ‘IsExploded’).
GridInnerRadius – Gets or sets the Inner radius of the pie grid, relative to the pie area. It can be a percentage (if value is between 0 and 1) or pixel amount (if value > 1). Defaults to 0.
GridOuterRadius – Gets or sets the outer radius of the pie grid, relative to the pie area. It can be a percentage (if value is between 0 and 1) or pixel amount (if value > 1). Defaults to 1 (ie 100 %).
GridInterval – Gets or sets the radial grid interval (interval division between grid lines).
GridMaxValue – Gets or sets the radial grid maximum value.
GridMinValue – Gets or sets the radial grid minimum value.
The above is an example where the GridInterval has been changed from figure 1 to figure 2.
InnerMargin – Gets or sets the inner pixel margin between the inner most ring and the pie center. Default is .02d.
The above has the InnerMargin set to zero.
And the above same pie chart has its InnerMargin set to.25
InnerRadius – Gets or sets the size of the inner radius for the pie, relative to the plot area. It can be a percentage (if value is between 0 and 1) or pixel amount (if value > 1). If the value is greater than 0 it will create an inner “hole” or donut chart.
IsExploded – Gets or sets whether all slices of the pie have been pulled out, or exploded, from the center of the pie. This attribute can be used to create added emphasis or to highlight the entire pie. Default is false.
The above is an example of a pie with IsExploded set to true (the amount it is exploded is controlled by ExplodedOffset).
MaxDetachedOffset – Gets or sets the maximum Detached Offset value (in pixels) that a pie slice can be detached. Default is 100.
MaxExplodedOffset – Gets or sets the maximum ExplodedOffset value (in pixels) that the pie may be exploded. Default is 100.
MaxRingOutRadius – Gets or sets the maximum radius of the Center RingOut image (in pixels). Default is 48.
MinOuterRadius – Gets or sets the minimum outer radius of the chart (in pixels). Defaults to 80.
MinRingOutRadius – Gets or sets the minimum radius of the Center RingOut image (in pixels). Default is 9.
MouseClickAction – Gets or sets the default action used when the user clicks on a pie slice. Default is ‘None’.
None – No action is taken.
Select – Pie element is selected (see PieSelectionMode).
Detach – Slice detach state is toggled.
Explode – Pie Exploded state is toggled.
MouseDoubleClickSliceAction – Gets or sets the default action used when the user double-clicks on a pie slice. Default is ‘None’.
None – No action is taken.
ChangeActiveRing – Active ring is changed to subordinate ring of clicked element (See ShowAllRings).
Detach – Slice detached state is toggled.
Explode – Pie Exploded state is toggled.
MultiSelect – Gets or sets whether multiple items can be selected by the user (ctrl+click to multi-select). Default is true.
OuterMargin – Gets or sets the outer pixel margin for the chart.
OuterRadius – Gets or sets the outer radius of the pie, relative to the plot area. Can be a percentage (if value is between 0 and 1) or pixel amount (if value > 1). Defaults to .8 (ie 80 %).
PaletteGroup – Gets or sets the palette color group to use (Light/Medium/Dark/Color1/MonoBlue/etc).
The above samples are MonoGreen, MonoBlue, and Color2 (respectively).
PieRadiusScale – Gets or sets how the PieRadius values (InnerRadius, OuterRadius, GridInnerRadius, and GridOuterRadius) are interpreted (as absolute pixel values or as relative percentages).
PieRingOutDisplayMode – Gets or sets the display mode for the ‘RingOut’ indicator (used to move out a ring level when ShowAllRings is false and the ActiveSeriesPointCollection has been set to an inner ring).
Always – RingOut indicator always displayed (when not at the outer-most ring).
Never – Never displayed (go up a level by shift dbl-click).
OnMouseOver – Indicator shown only when mouse is over ring area in center of Pie. (default).
Here is an example of the “RingOut” indicator (the gray circle/arrow in the pie center):
PieSelectionMode – Gets or sets the default mode used to perform pie selections (also controls what group of elements are displayed with MouseOver style when mouse is over an element). Default is ‘Slice’.
None – No selection.
Pie – Entire Pie is selected.
Series – Entire series is selected.
Slice – Slice selected.
Ring – Entire Ring is selected.
Point – Individual SeriesPoint selected.
ReversePaletteColors – Gets or sets whether default palette colors are utilized in reverse order.
ReverseRingOrder – Gets or sets whether rings of the pie are presented in reverse order.
The above has ReverseRingOrder set to false.
The above has ReverseRingOrder set to true.
SeriesMargin – Gets or sets the margin between multiple series in the chart, relative to the plot area. Can be a percentage (if value is between 0 and 1) or pixel amount (if value > 1). Defaults to .02
The above has the SeriesMargin set to zero.
The above has the SeriesMargin set to .4
SeriesOverlayEnabled – Gets or sets whether chart series are, by default, overlayed on top of each other. Default is false.
The above has SeriesOverlayEnabled set to false.
The above is the same Pie Chart, where its SeriesOverlayEnabled has been set to true.
ShowAllRings – Gets or sets whether all series rings are shown when rendering the chart. If false, only one ring at a time is shown, with the ability to ‘drill’ up or down, to display adjacent rings. Defaults to true.
The Above Pie Chart has 3 separate ring levels defined, and has ShowAllRings set to true.
The Above is the same chart, which now has ShowAllRings set to false, and is at the outer most level of the pie.
The Above has ShowAllRings set to false, and has had the “South” slice double clicked on, to drill down to the next related inner ring level. Double-clicking on a slice will let you go deeper, while clicking on the “RingOut” arrow in the center of the pie (or shift+double clicking on any slice) will take you back out a level.
ShowFullGrid – Gets or sets whether the radial pie grid is displayed over the entire pie (0 – 360 degrees) or only over the set sweep angle. Default is false.
ShowGridOnTop – Gets or sets whether the radial grid is displayed on top of the pie content (ShowPieGrid must also be true). Default is false.
The above ShowGridOnTop set to false.
The above ShowGridOnTop set to true.
ShowOtherSlice – Gets or sets whether to consolidate ‘excluded’ pie slices (due to MaxSlices or MinPercent settings) into a single slice that represents ‘Other’ data values. Default is false.
The above pie chart has ShowOtherSlice set to true, with its MaxSlices set to 8.
ShowPieGrid – Gets or sets whether a radial grid is displayed for the chart. Defaults to false.
ShowSliceLabelsOnEntry – Gets or sets whether all enabled slice labels will be shown when the mouse enters the chart area. Default is false.
ShowToolTips – Gets or sets whether tooltips are shown.
SliceLabelOverlapMode – Gets or sets the mode for resolving overlapping outer slice labels. Outer slice labels are only displayed for the outer-most chart series ring. This setting only applies to individual series (ie. Overlapped series are treated as distinct elements). Default is HideOverlapping.
SubSliceVisualLayout – Gets or sets the default layout of chart SeriesPoints in the chart. The properties / values set through this member will effect the slice/point elements subordinate to the item containing it (in this case, each series contained in the chart).
UseAlternateGridBackground – Gets or sets whether the chart utilizes the alternate background color when ShowPieGrid is enabled.
WhitespaceClickBehavior – Gets or sets the behavior when the user clicks the mouse in the chart whitespace.
None – No action taken.
ClearSelection – All selected items are cleared.
PieSeries
The PieSeries object is based upon the root ‘BaseSeries’ object, and contains elements specific to pie/radial data display.
The following is a list of the Properties available to all PieSeries elements.
CenterFirstSlice – Gets or sets whether the first pie slice is centered on the starting angle or starts on the starting angle. Default is false.
CustomPalette – Gets or sets the custom palette for the series (which enables a user defined palette of colors to use).
EnableDragDetach – Gets or sets whether the user can, by default, detach slices of the pie by Click and drag.
ExplodedMargin – Gets or sets the Margin between each series when the pie is Exploded. The ExplodedMargin is measured as a percentage of the pie radius (if <= 1) or the absolute pixel amount (if > 1).
The ExplodedMargin is used when multiple series are defined in the same pie. Its overall effect is to provide a ‘delayed’ explode offset between inner series.
MouseClickAction – Gets or sets the default action used when the user clicks on a pie slice. Default is ‘None’.
None – No action is taken.
Select – Pie element is selected (see PieSelectionMode).
Detach – Slice detach state is toggled.
Explode – Pie Exploded state is toggled.
MouseDoubleClickSliceAction – Gets or sets the default action used when the user double-clicks on a pie slice. Default is ‘None’.
None – No action is taken.
ChangeActiveRing – Active ring is changed to subordinate of clicked element (See ShowAllRings).
Detach – Slice detach state is toggled.
Explode – Pie Exploded state is toggled.
PaletteGroup – Gets or sets the palette color group to use (Light/Medium/Dark/Color1/MonoBlue/etc).
PieSelectionMode – Gets or sets the default mode used to perform pie selections. Default is ‘Slice’.
None – No selection.
Pie – Entire Pie is selected.
Series – Entire series is selected.
Slice – Slice selected (includes nested points).
Ring – Entire Ring is selected.
Point – Individual SeriesPoint selected.
ReversePaletteColors – Gets or sets whether default palette colors are utilized in reverse order.
RingWeight – Gets or sets the ‘relative’ total combined thickness of all series rings, as compared to the relative thickness of other series combined rings. Default is 100.
The above inner and outer rings both have their RingWeight set to 100 (therefore the outer ring width is the same as the inner ring width).
The above outer ring has its RingWeight set to 20, while the inner ring has its RingWeight set to 100 (therefore the outer ring width is approximately 1/5th the size of the inner ring).
SeriesPoints – Gets or sets the series point data collection (PieSeriesPoints).
ShowAllRings – Gets or sets whether all series rings are shown when rendering the chart. If false, only one ring at a time is shown, with the ability to ‘drill’ up or down, to display adjacent rings.
ShowOtherSlice – Gets or sets whether to consolidate smaller pie slices into a single slice that represents ‘other’ data values, or whether to display those smaller slices as separate pie slices.
SubSliceVisualLayout – Gets or sets the default layout of the subordinate or nested series slices.The properties / values set through this member will effect the slice/point elements subordinate to the item containing it (in this case, the series defined points/rings).
Visible – Gets or sets whether the series is visible or not.
PieRing
The PieRing object is a pie related object that defines certain properties applicable to all PieSeriesPoints at a given ring “level”.
The following is a list of the Properties available to all PieRing elements.
AllowDetach – Gets or sets whether the element can be ‘detached’ from the center of the pie by the user. Defaults to true.
AllowSelect – Gets or sets whether the ring can be selected by clicking on it. Defaults to true.
IsDisplayed – Gets whether the ringis displayed (based upon Visibility and Legend state).
Name – Gets or sets the user assigned Name of the item.
RingWeight – Gets or sets the ‘relative’ thickness of the series ring, as compared to the relative thickness of other series rings.
Visible – Gets or sets whether the ring is visible or not.
SubSliceVisualLayout
The SubSliceVisualLayout object defines additional objects and properties applicable to subordinate pie elements of the item containing the SubSliceVisualLayout object.
The following is a list of the Properties available to all SubSliceVisualLayout elements.
AngleMargin – Gets or sets the margin used to offset both the starting and ending angles at which the slice sides are rendered. This can be used to create a more ‘wedge’ shaped slice. Defaults to zero.
The above has the AngleMargin set to zero.
The above has the AngleMargin set to 2.5 degrees.
InnerLabelOrientation – Gets or sets the inner label orientation with respect to the slice.
Adaptive – The text is perpendicular to the center line of the slice, and is ‘adapted’ to fit the outer arc of the slice.
Custom – The label layout is gotten from the ‘Custom’ layout properties for the slice (includes location, size, orientation, etc). This option gives the most user control over the presentation of the label.
Horizontal – Labels are presented horizontally, within the bounds of the slice.
Parallel – Labels are presented parallel to the slice center line, within the bounds of the slice.
Perpendicular – Labels are presented perpendicular to the slice center line, within the bounds of the slice.
InnerSliceLabel – Gets or sets the inner slice label for the pie slice. The label can be straight text, or be comprised of text and formatting specifiers. The label should be specified as (note that brackets denote optional elements): “[text]{keyword[:format]}[text][{…}]”.
“AVG”, “A” – Average (angular values).
“PCT”, “P” – Percent of pie (angular values) – (.025 yields “2.5 %”).
“TOT” ,”T” – Total of all values (angluar values).
“VAL”, “V” – Value percent of pie (angular value) – (.025 yields “.025”).
“AVGX”, “AX” – Average (extent/radial values).
“PCTX”, “PX” – Percent of pie (extent values) – (.025 yields “2.5 %”).
“TOTX”, “TX” – Total of all values (extent values).
“VALX”, “VX” – Value percent of pie (extent value) – (.025 yields “.025”).
“S”, “SNAME” – Series name.
“X” – ValueX.
“Y”, “Y0”, “Yn” – ValueY values (where ‘n’ is index value).
Example use:
“{S}\\n{X:yyyy} ({Y:##,##0} – {P:Y1})”
“Individual cost {Y:C} and average cost {AVG:C} of goods.”
MaxSlices – Gets or sets the maximum number of slices to represent in the pie. Any remaining values are consolidated into the ‘Other’ slice, if shown, or are not displayed at all. The slices are counted in the order in which they are displayed.
MinExtent – Gets or sets the minimum extent for the collection.
MinPercent – Gets or sets the minimum percent-of-total represented in individual slices. Values less than the MinPercent are either accumulated into the ‘Other’ slice, if shown, or left in the main pie display. Range is 0–1.
OtherSliceVisualStyles – Gets or sets the default visual style for the series ‘Other’ slice.
ReferenceLineDisplayMode – Gets or sets the type of pie reference lines to display. The mode value is a ‘Flags’ value (ie. bit orientated), therefore you can select more than one element to display at a time (ie. ExtentMaximum | UserDefined).
None – No ReferenceLines will be displayed.
ExtentAverage – Extent Average Line will be shown.
ExtentMaximum – Extent Maximum Line will be shown.
ExtentMinimum – Extent Minimum Line will be shown.
ExtentOuterRadius – Extent Outer Radius will be shown.
UserDefined – All User defined Reference Lines will be shown.
ReferenceLineDisplayOnTop – Gets or sets whether references lines are displayed on top of chart data.
ReferenceLines – Gets a reference to the collection of user defined Reference Lines.
RingWeight – Gets or sets the ‘relative’ thickness of the associated pie ring, as compared to the relative thickness of other series rings rings.
ShowSliceWhiteSpace – Gets or sets whether to display, by default, the full slice (includes potential area beyond slice extent). Default is false.
The above has ShowSliceWhiteSpace set to false.
The above has the same image with ShowSliceWhiteSpace set to true.
SliceLabelCropMode – Gets or sets the label display mode (ie. the action taken when a label needs be clipped for full display). Default is Clip.
NoAction – No action is taken (no clipping or hiding).
Clip – Labels that do not fully fit will be clipped.
Hide – Labels that do not fully fit will be hidden.
SliceLabelVisibility – Gets or sets when the slice labels are visibly displayed.
Always – Labels are always visible.
Never – Labels are never visible.
SelectionModeMouseOver – Labels will be shown according to the PieSelectionMode setting in effect (ie. Ring, Slice, Pie, etc).
SliceDetach – Labels are shown for Detached slices.
SliceMouseOver – Labels are shown on MouseOver.
SliceSelect – Labels are shown for selected slices.
SliceLabelDisplayMode – Gets or sets the label display mode, which determines which slice labels (inner/outer) are displayed. Default is InnerAndOuter.
None – No Labels are displayed.
Inner – Inner labels only are displayed (those inside the pie slice).
Outer – Outer labels only are displayed (those outside the pie slice).
InnerAndOuter – Both inner and outer labels displayed.
InnerXorOuter – Either the inner or the outer label will be displayed, but not both (outer label will be displayed only when the inner label cannot be displayed).
SliceVisualStyles – Gets or sets the visual styles for the slice.
StartAngle – Gets or sets the start angle of the pie, in degrees, where 0 is right and 270 is top. Defaults to 270.
SweepAngle – Gets or sets the sweep angle (distance from StartAngle to the ending angle) of the pie in positive degrees (use SweepDirection to change rotational direction).
SweepDirection – Gets or sets the direction to display the pie slices – in either a clockwise or counterclockwise direction.
ToolTipText – Gets or sets the text to use for the point ToolTip.
PieSeriesPoints
PieSeriesPoints are ‘data points’ used to define instances on a PieChart for a given series. A PieSeriesPoint consists of a single X-Value (or argument) and one or more Y-Values.
The following is a list of the current available constructors for creating a PieSeriesPoint:
PieSeriesPoint()
Creates a PieSeriesPoint with ValueX = 0 (int zero), and ValueY[0] = 0 (int zero).
PieSeriesPoint(object xValue, object yValue)
Creates a PieSeriesPoint with ValueX = xValue, and ValueY[0] = yValue.
PieSeriesPoint(object xValue, object yValue1, object yValue2)
Creates a PieSeriesPoint with ValueX = xValue, ValueY[0] = yValue1, and ValueY[1] = yValue2.
PieSeriesPoint(object xValue, object[] yValue)
Creates a PieSeriesPoint with ValueX = xValue, and ValueY[] = yValue. This constructor can be used for all SeriesPoint allocations, but is especially needed for creating SeriesPoints that require multiple ValueY elements – such as is needed for the following items:
Examples:
PieSeriesPoint(“New York”, 235.66)
The above will create a PieSeriesPoint with ValueX = “New York”, and ValueY[0] = 235.66. The ValueY[0] defines the relative angular value for the point. It will be used to calculate the pie slice degree value related to the point.
PieSeriesPoint(“Bonner Motors”, 96074.20, 117.6)
The above will create a PieSeriesPoint with ValueX = “Bonner Motors”, ValueY[0] = 96074.20, and ValueY[1] = 117.6. The ValueY[0] defines the relative angular value for the point, and the ValueY[1] value will be used to calculate the radial extent for the point.
The following is a list of the Properties available to all PieSeriesPoint elements.
ActualStartAngle – Gets the actual, calculated starting angle for the slice.
ActualSweepAngle – Gets the actual, calculated sweep angle for the slice.
AllowDetach – Gets or sets whether the element can be ‘detached’ from the center of the pie by the user. Defaults to true.
AllowSelect – Gets or sets whether the element can be selected by clicking on it. Defaults to true.
CenterAngle – Gets the Center Angle for the slice.
ChartSeries – Gets the associated PieSeries.
DefaultPaletteColor – Gets the default palette color assigned to the point when it is arranged in the pie.
DetachedOffset – Gets or sets the offset distance of the slice from the pie center, as measured by a percentage of the pie radius (if between 0 and 1), or absolute pixel amount (if >= 1).
EffectiveSliceStyles – Gets a reference to the Effective (cached, composite) Slice styles.
ExtentRadius – Gets the actual, calculated extent radius of the slice (ValuesY[1]).
InnerRadius – Gets the actual, inner radius of the slice.
InnerSliceLabel – Gets or sets the inner slice label for the pie slice. The label can be straight text, or be comprised of text and formatting specifiers.
IsDetached– Gets or sets whether the slice is ‘detached’ from the center of the pie. This can be used to create emphasis or to highlight a slice of the pie.
IsDisplayed – Gets whether the series point is displayed based upon its Visibility and Legend check state.
IsEmptyPoint – Gets or sets whether the point is an ‘Empty’ (or missing) Point.
IsInOther – Gets whether the slice is in the ‘Other’ slice.
IsOther – Gets whether the slice is the ‘Other’ slice.
IsSelected – Gets or sets whether the slice is selected.
Name – Gets or sets the Name of the item.
OrdinalValue – Gets the ordial value for the point (the ordinal index value when added to its parent PieSeriesPoint Collection).
OuterRadius – Gets the actual, outer radius of the slice.
OuterSliceLabel – Gets or sets the outer slice label for the pie slice.
PieRing – Gets the items associated PieRing (if applicable).
SeriesPoints – Gets the nested series point data collection.
SliceCenter – Gets the slice center origin point.
SliceExtent – Gets the calculated slice extent value (the relative percent-of-total ValuesY[1] value for the slice).
SliceValue – Gets the calculated slice value (the relative percent-of-total ValuesY[0] value for the slice).
SliceVisualStyles – Gets or sets the visual styles for the slice.
StartAngle – Gets or sets the starting angle of the slice. For subsequent slices, the default is the ending angle of the previous slice. Specify a value for the StartAngle if you want the next slice to start at an angle that is different from the previous ending angle.
SubSliceVisualLayout – Gets or sets the layout of the subordinate (or nested) slices.
SweepAngle – Gets or sets the sweep angle of the slice (angle size, in degrees).
ToolTipText – Gets or sets the text to use for the point ToolTip.
Visible – Gets or sets whether the point is Visible.
Printing
Printing chart elements can be accomplished by the use of the ChartPrint object.
The following is a list of the Properties available for the ChartPrint object.
FitToPageScale – Gets or sets how the chart is scaled to fit the page when printing. FitToPageScale can be one of the following values:
Normal – No scaling will be done.
Stretch – Chart image will be stretched to completely fill the page.
Zoom – Chart image will be resized to fit the page, with the image aspect ratio maintained.
Printing Example
Here is an example of how one can use the ChartPrint object to print a chart:
Page Setup:
PageSetupDialog psd = PageSetupDialog;
psd.ShowDialog();
Print Preview:
PrintPreviewDialog pvd = new PrintPreviewDialog();
pvd.Document = new ChartPrint(_ChartControl);
// Tell the chart control to perform Nomal page fit for
// the chart (could also Stretch or Zoom).
((ChartPrint)pvd.Document).FitToPageScale = FitToPageScale.Normal;
PageSetupDialog psd = PageSetupDialog;
pvd.Document.PrinterSettings = psd.PrinterSettings;
pvd.Document.DefaultPageSettings = psd.PageSettings;
pvd.ShowDialog();
Print:
ChartPrint cp = new ChartPrint(_ChartControl);
PageSetupDialog psd = PageSetupDialog;
cp.PrinterSettings = psd.PrinterSettings;
cp.DefaultPageSettings = psd.PageSettings;
cp.Print();
Export/Import
Most ‘visible’ chart objects can be Exported and Imported as needed by the application.
Export will ‘export’ all non-default properties values to the specified file/stream. The corresponding import must be performed on the same type of chart element from which the export was performed. It may also be important to note that referenced ‘external’ objects are not serialized (such as DataSource and ImageList objects).
The following is a list of the methods available for Exporting and Importing:
Export:
VisualObject.Export(string filePath) – Exports the associated object to the file at the specified path.
VisualObject.Export(Stream stream) – Exports the associated object to the specified Stream.
Import:
VisualObject.Import(string filePath) – Imports all properties and settings to the associated object from the given file at the specified path.
VisualObject.Import(Stream stream) – Imports all properties and settings to the associated object from the given Stream.
Export / Import Example
Here is an example of how one can Export and Import the base ChartPanel in a chart control:
Export:
ChartControl cc = chartControl;
// Create a MemoryStream to use for our Export/Import.
// Export/Import can also be performed to/from a file path.
_MemStream = new MemoryStream();
// For this example, let’s export/import the entire root
// ChartPanel definition/layout.
cc.ChartPanel.Export(_MemStream);
Import:
ChartControl cc = chartControl;
// Import the entire root ChartPanel definition/layout, and
// add it to the current main panel layout / definition.
cc.ChartPanel.Import(_MemStream);
good !
Does the Chart include CandleChart(financial)?
Yes! With future updates adding more chart types and features!