Features and Functionalities

Features and Functionalities

This page covers the chart-authoring capabilities of Aspose.Words FOSS for .NET with working C# examples, built around DocumentBuilder.InsertChart() and the Chart object model. The library’s full document object model (paragraphs, tables, styles, bookmarks, sections) is described on the product overview and in the Quickstart guide.

Creating a Document with a Chart

Insert a chart shape with DocumentBuilder.InsertChart(), then access its Chart object through the returned Shape. Clear the default generated series before adding real data:

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");

Chart Series, Data Points, and Markers

Chart.Series is a ChartSeriesCollection. Each ChartSeries exposes its individual data points through DataPoints, which lets you customize a single point’s marker or formatting without affecting the rest of the series:

Shape shape = builder.InsertChart(ChartType.Line, 432, 252);
Chart chart = shape.Chart;
chart.Series.Clear();
chart.Series.Add("AW Series 1", categories, new double[] { 4.3, 2.5, 3.5 });

ChartSeries series = chart.Series[0];
ChartDataPointCollection points = series.DataPoints;

ChartDataPoint point1 = points[0];
ChartDataPoint point2 = points[1];

point1.InvertIfNegative = true;
point1.Marker.Symbol = MarkerSymbol.Square;
point2.InvertIfNegative = true;
point2.Marker.Symbol = MarkerSymbol.Diamond;

// Reset a single data point back to the series' inherited default formatting.
point1.ClearFormat();

Chart Data Labels

ChartSeries.DataLabels is a ChartDataLabelCollection that controls labels for every point in the series at once. Index into it with DataLabels[i] to override an individual ChartDataLabel:

Shape shape = builder.InsertChart(ChartType.Line, 432, 252);
Chart chart = shape.Chart;
chart.Series.Clear();
chart.Series.Add("AW Series 1", categories, new double[] { 4.3, 2.5, 3.5 });

ChartSeries series = chart.Series[0];
series.HasDataLabels = true;
series.DataLabels.ShowValue = true;

ChartDataLabel label = series.DataLabels[1];
label.ShowCategoryName = true;
label.Position = ChartDataLabelPosition.Below;

Chart Axis Titles

Chart.AxisX and Chart.AxisY each expose a ChartAxisTitle through their Title property:

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

Shape shape = builder.InsertChart(ChartType.Column, 432, 252);

Chart chart = shape.Chart;
ChartAxisTitle xTitle = chart.AxisX.Title;
ChartAxisTitle yTitle = chart.AxisY.Title;

xTitle.Show = true;
xTitle.Text = "Categories";
yTitle.Show = true;
yTitle.Text = "Values";

Chart Legend and Fonts

Chart.Legend exposes LegendEntries, one ChartLegendEntry per series, each with its own Font. Font implements fill formatting, so Font.Fill.Solid() sets a solid text color the same way it would on any other formatted run:

using System.Drawing;

Shape shape = builder.InsertChart(ChartType.Column, 432, 252);

ChartLegend legend = shape.Chart.Legend;
Font font1 = legend.LegendEntries[0].Font;
Font font2 = legend.LegendEntries[1].Font;

font1.Fill.Solid(Color.Blue);
font2.Color = Color.Green;

Chart Data Table

Chart.DataTable is a ChartDataTable that displays the underlying series values beneath the chart. Its Has*Border and HasLegendKeys properties control which parts are visible:

Shape shape = builder.InsertChart(ChartType.Column, 432, 252);
ChartDataTable dataTable = shape.Chart.DataTable;

dataTable.HasLegendKeys = false;
dataTable.HasHorizontalBorder = true;
dataTable.HasVerticalBorder = true;
dataTable.HasOutlineBorder = false;

doc.Save("chart-report.docx");

Tips and Best Practices

• DocumentBuilder.InsertChart() populates the new chart with a default generated series — call chart.Series.Clear() before adding your own data, or the defaults remain alongside it.
• Use ChartSeries.DataLabels[i] to target one data label when only a few points need custom formatting; use the collection-level properties (DataLabels.ShowValue, and similar) to set a default for every label in the series at once.
• ClearFormat() is available on both ChartDataPoint and ChartDataLabelCollection — it resets direct formatting back to what the series inherits by default.
• The field evaluation engine updates content fields such as DATE and DOCPROPERTY programmatically, but fields that depend on page layout (page numbers in a TOC, NUMPAGES) evaluate to placeholder 0 values because this edition does not include the layout engine.
• A NuGet package is not published yet — build from source as described in the Installation Guide before referencing these APIs.

Common Issues

FAQ

Why do page numbers in my table of contents come out as 0?

This FOSS edition does not include the page-layout and rendering subsystem, so any field value that depends on page layout — including page numbers — evaluates to a placeholder 0 instead of a computed value.

Can I export a document to PDF or an image format?

Not in this edition. PDF, XPS, and image export depend on the same rendering subsystem that was removed to keep this edition free. Use the commercial Aspose.Words for .NET for those outputs.

Can I create a new digital signature on a document?

No — this edition can verify existing digital signatures but cannot create new ones.

Which chart types does InsertChart() support?

InsertChart() takes a ChartType value — the enum covers standard chart families such as line, column, bar, pie, area, doughnut, radar, scatter, stock, and surface charts, including their stacked and 3D variants.

API Reference Summary

See Also

• Aspose.Words for .NET — Enterprise Documentation