Working with Charts

Working with Charts

Aspose.Words FOSS for .NET can insert native Word charts — the same DrawingML charts Word itself creates — as a shape in the drawing layer. DocumentBuilder.InsertChart creates the shape and returns it; the shape’s Chart property exposes series, axes, legend, and formatting. This guide covers creating a chart, choosing a chart type, working with series and data points, axes and gridlines, and formatting chart elements.

Creating a Chart

Call DocumentBuilder.InsertChart(chartType, width, height) to insert a chart shape at the cursor and get back the containing Shape. Its Chart property is the Chart object you configure. A freshly inserted chart comes with placeholder demo series, so clear Chart.Series before adding real data with ChartSeriesCollection.Add(seriesName, categories, values):

using Aspose.Words;
using Aspose.Words.Drawing.Charts;

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Shape shape = builder.InsertChart(ChartType.Line, 432, 252);
Chart chart = shape.Chart;

// Delete default generated series.
chart.Series.Clear();

string[] categories = new string[] { "AW Category 1", "AW Category 2", "AW Category 3" };
chart.Series.Add("AW Series 1", categories, new double[] { 4.3, 2.5, 3.5 });

doc.Save("chart.docx");

This example builds a Document, uses DocumentBuilder.InsertChart(ChartType.Line, 432, 252) to insert a line chart shape, reads shape.Chart to get the Chart object, calls chart.Series.Clear() to remove the placeholder series, adds one real series with chart.Series.Add(seriesName, categories, values), and writes the result with Document.Save.

Chart Types

ChartType covers the standard Word chart families — Line, Bar, Column (plus their Stacked, PercentStacked, and 3D variants), Pie, PieOfPie, Doughnut, Area, Scatter, Bubble, Radar, Stock, Surface, and the newer Word 2016 chart types Treemap, Sunburst, Histogram, Pareto, BoxAndWhisker, and Waterfall. Pass the desired value as the chartType argument to InsertChart; there is no way to change an existing chart’s type after insertion other than replacing the shape.

Series and Data Points

Chart.Series is a ChartSeriesCollection of ChartSeries objects. Beyond the Add(seriesName, categories, values) overload used above, ChartSeriesCollection also has overloads for X/Y value pairs, dates, and bubble sizes, plus Insert, Remove(index), and Clear(). Each ChartSeries exposes DataPoints (a ChartDataPointCollection) for per-point formatting — Format, Marker, Explosion, and InvertIfNegative — and HasDataLabels / DataLabels to turn on and configure a ChartDataLabelCollection (ShowValue, ShowCategoryName, ShowPercentage, Position).

Axes and Gridlines

Chart.AxisX, AxisY, and AxisZ are ChartAxis objects (with Chart.Axes as a ChartAxisCollection for iterating all of them). Each axis has HasMajorGridlines / HasMinorGridlines, MajorUnit / MinorUnit (with matching *IsAuto flags), Crosses / CrossesAt, CategoryType, and a TickLabels object (AxisTickLabels) for label font and orientation. ChartAxis.Title (ChartAxisTitle) sets the axis caption text via its Text and Show properties.

Legend, Title, and Data Table

Chart.Title (ChartTitle) sets the chart’s overall caption — Text, Show, and Font. Chart.Legend (ChartLegend) controls whether and where the legend appears via Position (a LegendPosition value such as Bottom, Right, or Top) and exposes individual LegendEntries. Chart.DataTable (ChartDataTable) can display the underlying series values as a table below the plot area, with Show, HasLegendKeys, and border toggles.

Formatting Chart Elements

Most chart elements — series, data points, axes, the title, and the legend — expose a Format property of type ChartFormat, which in turn exposes Fill and Stroke for that element’s colors, plus a ShapeType (ChartShapeType) for data-point marker shapes. ChartFormat.SetDefaultFill() resets an element back to its theme-driven default appearance.

Tips and Best Practices

• Always clear or replace the placeholder series (chart.Series.Clear()) before adding real data — a freshly inserted chart ships with sample data already in it.
• Use ChartSeriesCollection.Add overloads that match your data shape (categories, X/Y pairs, dates, or bubble sizes) rather than forcing everything through category/value pairs.
• Set HasDataLabels = true on a series before configuring its DataLabels collection — the collection’s display properties have no visible effect while labels are switched off.
• Read Chart.ChartSpace or check the specific ChartType before relying on gridline or axis behavior that differs between classic and Word-2016-style charts.
• Prefer ChartFormat.SetDefaultFill() over manually clearing every fill property when you want to reset an element’s appearance.

Common Issues

FAQ

How do I insert a chart into a document?

Call DocumentBuilder.InsertChart(chartType, width, height). It returns the containing Shape; read its Chart property to configure the chart.

How do I add data to a chart?

Clear the placeholder series with chart.Series.Clear(), then call chart.Series.Add(seriesName, categories, values) (or one of the other Add overloads for X/Y, date, or bubble data).

Which chart types are available?

ChartType includes the classic families (Line, Bar, Column, Pie, Area, Scatter, Bubble, Radar, Stock, Surface, plus their stacked and 3D variants) and the Word 2016 chart types (Treemap, Sunburst, Histogram, Pareto, BoxAndWhisker, Waterfall).

How do I change where the legend appears?

Set Chart.Legend.Position to a LegendPosition value, such as LegendPosition.Bottom or LegendPosition.Right.

Can I format an individual data point differently from the rest of its series?

Yes — index into ChartSeries.DataPoints (a ChartDataPointCollection) and set that ChartDataPoint’s Format, Marker, or Explosion independently of the series-level formatting.

API Reference Summary

See Also

• Aspose.Words — Enterprise Documentation