[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications and Dialogs
  [Expand]Editors and Simple Controls
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Property Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Diagrams
  [Expand]Gauges
  [Expand]Map Control
  [Expand]Scheduler
  [Collapse]Spreadsheet
   [Expand]Product Information
    Product Structure
    Getting Started
   [Expand]Spreadsheet Document
    Supported Formats
   [Expand]Cell Basics
   [Expand]Spreadsheet Formulas
    Defined Names
    Data Binding
    Data Validation
   [Expand]Data Presentation
    Data Grouping
   [Expand]Pivot Table Overview
   [Collapse]Charting Overview
     Chart Elements
     Create and Modify a Chart Programmatically
    Shapes
    Printing
    Events
   [Expand]Mail Merge Overview
    Protection
    Find and Replace
   [Expand]Visual Elements
    Services
   [Expand]Shortcuts
   [Expand]Examples
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]Printing-Exporting
  [Expand]PDF Viewer
   Reporting
  [Expand]Snap
  [Expand]TreeMap Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Reporting
[Expand]Report and Dashboard Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Create and Modify a Chart Programmatically

This topic describes how to create and modify charts in code using the Spreadsheet Chart API.

This topic consists of the following sections:

Expanded Arrange Worksheet Data to Create a Chart

When you create a chart, the SpreadsheetControl plots data on the chart based on the number of rows and columns in the source range:

  1. If the source range has more rows than columns, the first column provides labels for the category axis (X-axis), and the first row contains series names. Series values are arranged in columns.

    If you do not include labels and/or series names in the source range, a chart displays sequential numbers for data points on the category axis and uses the default series names (Series 1, Series 2, ..., Series N).

  2. If the source range has more columns than rows or the number of rows and columns is the same, the first row provides labels for the category axis (X-axis), and the first column contains series names. Series values are arranged in rows.

    If you do not include labels and/or series names in the source range, a chart displays sequential numbers for data points on the category axis and uses the default series names (Series 1, Series 2, ..., Series N).

You can use the ChartObject.SwitchRowColumn method to change the default direction used to plot data series on a chart (whether the series values are obtained from columns or rows), or call the ChartObject.SelectData method with the direction parameter to specify how to retrieve series values.

The table below lists how to arrange data on a worksheet to create a specific chart.

Chart type

Data arrangement

Line, column, bar, area, surface, or radar chart

In columns or rows:

Pie chart

Uses a single series of values arranged in one column or row. Another column or row contains data labels.

Doughnut chart

In one or multiple columns or rows, and one column or row contains data labels.

Scatter or bubble chart

In columns or rows. Place x values in the first column or row, and the corresponding y values in the adjacent columns or rows.

For a bubble chart, add columns or rows specifying the bubble size.

Stock chart

In columns or rows in the same order as the stock chart name.

Expanded Create a Chart

The chart collection (ChartCollection) stores charts in a worksheet. You can use the Worksheet.Charts property to access a worksheet's chart collection, and the collection's ChartCollection.Add method to create a chart. The ChartType enumeration value specifies the chart type.

Use one of the following approaches to specify the chart's data:

  • Pass a cell range containing chart data to the ChartCollection.Add method. Refer to the Arrange Worksheet Data to Create a Chart section for information on how to organize data in the source range to create a specific chart.

  • Pass a cell range containing chart data to the ChartObject.SelectData method. This method also allows you to specify the data direction: whether the series values are arranged in columns (ChartDataDirection.Column) or rows (ChartDataDirection.Row).

  • Use the SeriesCollection.Add method overloads to add data series to the chart's series collection (ChartObject.Series). These methods enable you to plot data contained in the noncontiguous cell ranges. You can explicitly specify a name, arguments, and values for each series.

The ChartData object specifies data plotted on a chart. You can also use an array of numeric, string or boolean literals as the chart's data source. ChartData supports implicit conversion from an array of CellValue objects. You can use these objects to specify numeric, string or boolean values without casting. Use the ChartData.FromArray method to convert the CellValue type arrays to chart data, or assign these arrays to the series's arguments and values directly.

Refer to the How to: Create and Modify a Chart topic for more examples on how to create charts in code.

Each chart has an associated ChartView. This object is created automatically when you create a chart. It consolidates data series of the same type (ChartView.Series) and provides customization options. A ChartView object is a member of the ChartViewCollection collection you can access using the ChartObject.Views property. A chart can have several ChartView objects (a combination chart). To create a combination chart, use the Series.ChangeType method to change an existing series's type. If the specified type is incompatible with the other series types, the SpreadsheetControl clears the ChartViewCollection collection and creates a new ChartView object to display all chart series. This object has the same type as the modified data series. The How to: Create and Modify a Chart topic contains a list of compatible chart types and provides an example on how to create a combination chart.

Expanded Modify a Chart and Adjust Its Settings

After you create a chart, you can use the Spreadsheet Chart API members to change the chart's layout and appearance.

Tip

To improve the control's performance by avoiding unnecessary render operations after each modification, enclose the chart modifications in the Workbook.BeginUpdate() - Workbook.EndUpdate() method pair.

The table below lists the actions you can perform on a chart.

To perform this task

Use these API members

Example

Change the source data for a chart Chart.SelectData
(ChartObject.SelectData)
Series.Arguments
Series.Values
How to: Create and Modify a Chart
Add or remove data series SeriesCollection.Add
SeriesCollection.Remove
SeriesCollection.RemoveAt
SeriesCollection.Clear
How to: Create and Modify a Chart
Change the data direction on a chart Chart.SwitchRowColumn
(ChartObject.SwitchRowColumn)
How to: Create and Modify a Chart
Change the data series' order Series.BringForward
Series.SendBackward
Series.BringToFront
Series.SendToBack
How to: Create and Modify a Chart
Change a chart type Chart.ChangeType
(ChartObject.ChangeType)
How to: Create and Modify a Chart
Change a series type Series.ChangeType How to: Create and Modify a Chart
Create a chart on a separate sheet (chart sheet),
or move an existing chart to a new chart sheet
IWorkbook.ChartSheets
ChartSheetCollection.Add
Chart.MoveToNewChartSheet
(ChartObject.MoveToNewChartSheet)
How to: Create a Chart Sheet
How to: Move a Chart to a Chart Sheet
Display or hide primary axes,
adjust their position and orientation
Chart.PrimaryAxes
(ChartObject.PrimaryAxes)
Axis
Axis.Visible
Axis.Position
Axis.Scaling.Orientation
(AxisScaling.Orientation)
How to: Change the Display of Chart Axes
Add axis titles Axis.Title
Axis.Title.Visible
(ChartTitleOptions.Visible)
Axis.Title.SetValue
(ChartText.SetValue)
Axis.Title.SetReference
(ChartText.SetReference)
How to: Change the Display of Chart Axes
Change the axis scaling, and
format numbers on the axis
Axis.Scaling
AxisScaling.Min
AxisScaling.Max
AxisScaling.LogScale
AxisScaling.LogBase
Axis.NumberFormat
How to: Change the Display of Chart Axes
Display secondary axes Series.AxisGroup
AxisGroup.Secondary
Chart.SecondaryAxes
(ChartObject.SecondaryAxes)
How to: Change the Display of Chart Axes
Display or hide gridlines Axis.MajorGridlines
Axis.MinorGridlines
How to: Change the Display of Chart Axes
Add a chart title Chart.Title
(ChartObject.Title)
ChartTitle.Visible
(ChartTitleOptions.Visible)
ChartTitle.SetValue
(ChartText.SetValue)
ChartTitle.SetReference
(ChartText.SetReference)
How to: Display the Chart Title
Display or hide a chart legend, specify its position,
customize a legend entry
Chart.Legend
(ChartObject.Legend)
Legend.Visible
Legend.Position
Legend.CustomEntries
How to: Show or Hide the Chart Legend
Display data labels for the entire chart
or individual series/data points
ChartView.DataLabels
DataLabelPosition
Series.UseCustomDataLabels
Series.CustomDataLabels
How to: Display and Format Data Labels
Apply a number format to data labels ChartView.DataLabels.NumberFormat
(DataLabelBase.NumberFormat)
How to: Display and Format Data Labels
Apply a chart style Chart.Style
(ChartObject.Style)
How to: Format Chart Elements
Fill a chart element ShapeFormatBase.Fill
ShapeOutlineFill.SetNoFill
ShapeOutlineFill.SetSolidFill
ShapeOutlineFill.SetGradientFill
How to: Format Chart Elements
Format a chart element's outline ShapeFormatBase.Outline
ShapeOutlineFill.SetSolidFill
ShapeOutlineFill.SetNoFill
ShapeOutline.Width
How to: Format Chart Elements
Format a chart element's text
ShapeTextFormat.Font How to: Format Chart Elements
Apply protection to a chart Chart.Options.Protection
(ChartOptions.Protection)
How to: Protect a Chart

Expanded See Also

Is this topic helpful?​​​​​​​