Aspose::Words::Drawing::Charts Namespace Reference

Detailed Description

The Aspose.Words.Drawing.Charts namespace provides classes that allow to access charts in Microsoft Word documents.

The chart supported are Word 2007 (or higher) DrawingML Charts.

Classes

class  AxisBound
 Represents minimum or maximum bound of axis values. More...
 
class  AxisDisplayUnit
 Provides access to the scaling options of the display units for the value axis. More...
 
class  AxisScaling
 Represents the scaling options of the axis. More...
 
class  Chart
 Provides access to the chart shape properties. More...
 
class  ChartAxis
 Represents the axis options of the chart. More...
 
class  ChartDataLabel
 Represents data label on a chart point or trendline. More...
 
class  ChartDataLabelCollection
 Represents a collection of ChartDataLabel. More...
 
class  ChartDataPoint
 Allows to specify formatting of a single data point on the chart. More...
 
class  ChartDataPointCollection
 Represents collection of a ChartDataPoint. More...
 
class  ChartFormat
 Represents the formatting of a chart element. More...
 
class  ChartLegend
 Represents chart legend properties. More...
 
class  ChartMarker
 Represents a chart data marker. More...
 
class  ChartNumberFormat
 Represents number formatting of the parent element. More...
 
class  ChartSeries
 Represents chart series properties. More...
 
class  ChartSeriesCollection
 Represents collection of a ChartSeries. More...
 
class  ChartTitle
 Provides access to the chart title properties. More...
 
interface  IChartDataPoint
 Contains properties of a single data point on the chart. More...
 

Enumerations

enum class  AxisBuiltInUnit
 Specifies the display units for an axis. More...
 
enum class  AxisCategoryType
 Specifies type of a category axis. More...
 
enum class  AxisCrosses
 Specifies the possible crossing points for an axis. More...
 
enum class  AxisScaleType
 Specifies the possible scale types for an axis. More...
 
enum class  AxisTickLabelPosition
 Specifies the possible positions for tick labels. More...
 
enum class  AxisTickMark
 Specifies the possible positions for tick marks. More...
 
enum class  AxisTimeUnit
 Specifies the unit of time for axes. More...
 
enum class  ChartAxisType
 Specifies type of chart axis. More...
 
enum class  ChartType
 Specifies type of a chart. More...
 
enum class  LegendPosition
 Specifies the possible positions for a chart legend. More...
 
enum class  MarkerSymbol
 Specifies marker symbol style. More...
 

Enumeration Type Documentation

◆ AxisBuiltInUnit

Specifies the display units for an axis.

Examples

Shows how to manipulate the tick marks and displayed values of a chart axis.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<Shape> shape = builder->InsertChart(ChartType::Scatter, 450, 250);
SharedPtr<Chart> chart = shape->get_Chart();
ASSERT_EQ(1, chart->get_Series()->get_Count());
ASSERT_EQ(u"Y-Values", chart->get_Series()->idx_get(0)->get_Name());
// Set the minor tick marks of the Y-axis to point away from the plot area,
// and the major tick marks to cross the axis.
SharedPtr<ChartAxis> axis = chart->get_AxisY();
axis->set_MajorTickMark(AxisTickMark::Cross);
axis->set_MinorTickMark(AxisTickMark::Outside);
// Set they Y-axis to show a major tick every 10 units, and a minor tick every 1 unit.
axis->set_MajorUnit(10);
axis->set_MinorUnit(1);
// Set the Y-axis bounds to -10 and 20.
// This Y-axis will now display 4 major tick marks and 27 minor tick marks.
axis->get_Scaling()->set_Minimum(MakeObject<AxisBound>(-10.0));
axis->get_Scaling()->set_Maximum(MakeObject<AxisBound>(20.0));
// For the X-axis, set the major tick marks at every 10 units,
// every minor tick mark at 2.5 units.
axis = chart->get_AxisX();
axis->set_MajorUnit(10);
axis->set_MinorUnit(2.5);
// Configure both types of tick marks to appear inside the graph plot area.
axis->set_MajorTickMark(AxisTickMark::Inside);
axis->set_MinorTickMark(AxisTickMark::Inside);
// Set the X-axis bounds so that the X-axis spans 5 major tick marks and 12 minor tick marks.
axis->get_Scaling()->set_Minimum(MakeObject<AxisBound>(-10.0));
axis->get_Scaling()->set_Maximum(MakeObject<AxisBound>(30.0));
axis->set_TickLabelAlignment(ParagraphAlignment::Right);
ASSERT_EQ(1, axis->get_TickLabelSpacing());
// Set the tick labels to display their value in millions.
axis->get_DisplayUnit()->set_Unit(AxisBuiltInUnit::Millions);
// We can set a more specific value by which tick labels will display their values.
// This statement is equivalent to the one above.
axis->get_DisplayUnit()->set_CustomUnit(1000000);
doc->Save(ArtifactsDir + u"Charts.AxisDisplayUnit.docx");
Enumerator
None 

Specifies the values on the chart shall displayed as is.

Custom 

Specifies the values on the chart shall be divided by a user-defined divisor. This value is not supported by the new chart types of MS Office 2016.

Billions 

Specifies the values on the chart shall be divided by 1,000,000,000.

HundredMillions 

Specifies the values on the chart shall be divided by 100,000,000.

Hundreds 

Specifies the values on the chart shall be divided by 100.

HundredThousands 

Specifies the values on the chart shall be divided by 100,000.

Millions 

Specifies the values on the chart shall be divided by 1,000,000.

TenMillions 

Specifies the values on the chart shall be divided by 10,000,000.

TenThousands 

Specifies the values on the chart shall be divided by 10,000.

Thousands 

Specifies the values on the chart shall be divided by 1,000.

Trillions 

Specifies the values on the chart shall be divided by 1,000,000,000,0000.

Percentage 

Specifies the values on the chart shall be divided by 0.01. This value is supported only by the new chart types of MS Office 2016.

◆ AxisCategoryType

Specifies type of a category axis.

Examples

Shows how to insert a chart and modify the appearance of its axes.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<Shape> shape = builder->InsertChart(ChartType::Column, 500, 300);
SharedPtr<Chart> chart = shape->get_Chart();
// Clear the chart's demo data series to start with a clean chart.
chart->get_Series()->Clear();
// Insert a chart series with categories for the X-axis and respective numeric values for the Y-axis.
chart->get_Series()->Add(u"Aspose Test Series", MakeArray<String>({u"Word", u"PDF", u"Excel", u"GoogleDocs", u"Note"}),
MakeArray<double>({640, 320, 280, 120, 150}));
// Chart axes have various options that can change their appearance,
// such as their direction, major/minor unit ticks, and tick marks.
SharedPtr<ChartAxis> xAxis = chart->get_AxisX();
xAxis->set_CategoryType(AxisCategoryType::Category);
xAxis->set_Crosses(AxisCrosses::Minimum);
xAxis->set_ReverseOrder(false);
xAxis->set_MajorTickMark(AxisTickMark::Inside);
xAxis->set_MinorTickMark(AxisTickMark::Cross);
xAxis->set_MajorUnit(10.0);
xAxis->set_MinorUnit(15.0);
xAxis->set_TickLabelOffset(50);
xAxis->set_TickLabelPosition(AxisTickLabelPosition::Low);
xAxis->set_TickLabelSpacingIsAuto(false);
xAxis->set_TickMarkSpacing(1);
SharedPtr<ChartAxis> yAxis = chart->get_AxisY();
yAxis->set_CategoryType(AxisCategoryType::Automatic);
yAxis->set_Crosses(AxisCrosses::Maximum);
yAxis->set_ReverseOrder(true);
yAxis->set_MajorTickMark(AxisTickMark::Inside);
yAxis->set_MinorTickMark(AxisTickMark::Cross);
yAxis->set_MajorUnit(100.0);
yAxis->set_MinorUnit(20.0);
yAxis->set_TickLabelPosition(AxisTickLabelPosition::NextToAxis);
// Column charts do not have a Z-axis.
ASSERT_TRUE(chart->get_AxisZ() == nullptr);
doc->Save(ArtifactsDir + u"Charts.AxisProperties.docx");
Enumerator
Automatic 

Specifies that type of a category axis is determined automatically based on data.

Category 

Specifies an axis of an arbitrary set of categories.

Time 

Specifies a time category axis.

◆ AxisCrosses

Specifies the possible crossing points for an axis.

Examples

Shows how to insert a chart and modify the appearance of its axes.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<Shape> shape = builder->InsertChart(ChartType::Column, 500, 300);
SharedPtr<Chart> chart = shape->get_Chart();
// Clear the chart's demo data series to start with a clean chart.
chart->get_Series()->Clear();
// Insert a chart series with categories for the X-axis and respective numeric values for the Y-axis.
chart->get_Series()->Add(u"Aspose Test Series", MakeArray<String>({u"Word", u"PDF", u"Excel", u"GoogleDocs", u"Note"}),
MakeArray<double>({640, 320, 280, 120, 150}));
// Chart axes have various options that can change their appearance,
// such as their direction, major/minor unit ticks, and tick marks.
SharedPtr<ChartAxis> xAxis = chart->get_AxisX();
xAxis->set_CategoryType(AxisCategoryType::Category);
xAxis->set_Crosses(AxisCrosses::Minimum);
xAxis->set_ReverseOrder(false);
xAxis->set_MajorTickMark(AxisTickMark::Inside);
xAxis->set_MinorTickMark(AxisTickMark::Cross);
xAxis->set_MajorUnit(10.0);
xAxis->set_MinorUnit(15.0);
xAxis->set_TickLabelOffset(50);
xAxis->set_TickLabelPosition(AxisTickLabelPosition::Low);
xAxis->set_TickLabelSpacingIsAuto(false);
xAxis->set_TickMarkSpacing(1);
SharedPtr<ChartAxis> yAxis = chart->get_AxisY();
yAxis->set_CategoryType(AxisCategoryType::Automatic);
yAxis->set_Crosses(AxisCrosses::Maximum);
yAxis->set_ReverseOrder(true);
yAxis->set_MajorTickMark(AxisTickMark::Inside);
yAxis->set_MinorTickMark(AxisTickMark::Cross);
yAxis->set_MajorUnit(100.0);
yAxis->set_MinorUnit(20.0);
yAxis->set_TickLabelPosition(AxisTickLabelPosition::NextToAxis);
// Column charts do not have a Z-axis.
ASSERT_TRUE(chart->get_AxisZ() == nullptr);
doc->Save(ArtifactsDir + u"Charts.AxisProperties.docx");
Enumerator
Automatic 

The category axis crosses at the zero point of the value axis (if possible), or at the minimum value if the minimum is greater than zero, or at the maximum if the maximum is less than zero.

Maximum 

A perpendicular axis crosses at the maximum value of the axis.

Minimum 

A perpendicular axis crosses at the minimum value of the axis.

Custom 

A perpendicular axis crosses at the specified value of the axis.

◆ AxisScaleType

Specifies the possible scale types for an axis.

Examples

Shows how to apply logarithmic scaling to a chart axis.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<Shape> chartShape = builder->InsertChart(ChartType::Scatter, 450, 300);
SharedPtr<Chart> chart = chartShape->get_Chart();
// Clear the chart's demo data series to start with a clean chart.
chart->get_Series()->Clear();
// Insert a series with X/Y coordinates for five points.
chart->get_Series()->Add(u"Series 1", MakeArray<double>({1.0, 2.0, 3.0, 4.0, 5.0}), MakeArray<double>({1.0, 20.0, 400.0, 8000.0, 160000.0}));
// The scaling of the X-axis is linear by default,
// displaying evenly incrementing values that cover our X-value range (0, 1, 2, 3...).
// A linear axis is not ideal for our Y-values
// since the points with the smaller Y-values will be harder to read.
// A logarithmic scaling with a base of 20 (1, 20, 400, 8000...)
// will spread the plotted points, allowing us to read their values on the chart more easily.
chart->get_AxisY()->get_Scaling()->set_Type(AxisScaleType::Logarithmic);
chart->get_AxisY()->get_Scaling()->set_LogBase(20);
doc->Save(ArtifactsDir + u"Charts.AxisScaling.docx");
Enumerator
Linear 

Linear scaling.

Logarithmic 

Logarithmic scaling.

◆ AxisTickLabelPosition

Specifies the possible positions for tick labels.

Examples

Shows how to insert chart with date/time values.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<Shape> shape = builder->InsertChart(ChartType::Line, 500, 300);
SharedPtr<Chart> chart = shape->get_Chart();
// Clear the chart's demo data series to start with a clean chart.
chart->get_Series()->Clear();
// Add a custom series containing date/time values for the X-axis, and respective decimal values for the Y-axis.
chart->get_Series()->Add(u"Aspose Test Series",
MakeArray<System::DateTime>({System::DateTime(2017, 11, 6), System::DateTime(2017, 11, 9), System::DateTime(2017, 11, 15),
System::DateTime(2017, 11, 21), System::DateTime(2017, 11, 25), System::DateTime(2017, 11, 29)}),
MakeArray<double>({1.2, 0.3, 2.1, 2.9, 4.2, 5.3}));
// Set lower and upper bounds for the X-axis.
SharedPtr<ChartAxis> xAxis = chart->get_AxisX();
xAxis->get_Scaling()->set_Minimum(MakeObject<AxisBound>(System::DateTime(2017, 11, 5).ToOADate()));
xAxis->get_Scaling()->set_Maximum(MakeObject<AxisBound>(System::DateTime(2017, 12, 3)));
// Set the major units of the X-axis to a week, and the minor units to a day.
xAxis->set_BaseTimeUnit(AxisTimeUnit::Days);
xAxis->set_MajorUnit(7.0);
xAxis->set_MajorTickMark(AxisTickMark::Cross);
xAxis->set_MinorUnit(1.0);
xAxis->set_MinorTickMark(AxisTickMark::Outside);
// Define Y-axis properties for decimal values.
SharedPtr<ChartAxis> yAxis = chart->get_AxisY();
yAxis->set_TickLabelPosition(AxisTickLabelPosition::High);
yAxis->set_MajorUnit(100.0);
yAxis->set_MinorUnit(50.0);
yAxis->get_DisplayUnit()->set_Unit(AxisBuiltInUnit::Hundreds);
yAxis->get_Scaling()->set_Minimum(MakeObject<AxisBound>(100.0));
yAxis->get_Scaling()->set_Maximum(MakeObject<AxisBound>(700.0));
doc->Save(ArtifactsDir + u"Charts.DateTimeValues.docx");
Enumerator
High 

Specifies the axis labels shall be at the high end of the perpendicular axis.

Low 

Specifies the axis labels shall be at the low end of the perpendicular axis.

NextToAxis 

Specifies the axis labels shall be next to the axis.

None 

Specifies the axis labels are not drawn.

Default 

Specifies default value of tick labels position.

◆ AxisTickMark

Specifies the possible positions for tick marks.

Examples

Shows how to insert chart with date/time values.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<Shape> shape = builder->InsertChart(ChartType::Line, 500, 300);
SharedPtr<Chart> chart = shape->get_Chart();
// Clear the chart's demo data series to start with a clean chart.
chart->get_Series()->Clear();
// Add a custom series containing date/time values for the X-axis, and respective decimal values for the Y-axis.
chart->get_Series()->Add(u"Aspose Test Series",
MakeArray<System::DateTime>({System::DateTime(2017, 11, 6), System::DateTime(2017, 11, 9), System::DateTime(2017, 11, 15),
System::DateTime(2017, 11, 21), System::DateTime(2017, 11, 25), System::DateTime(2017, 11, 29)}),
MakeArray<double>({1.2, 0.3, 2.1, 2.9, 4.2, 5.3}));
// Set lower and upper bounds for the X-axis.
SharedPtr<ChartAxis> xAxis = chart->get_AxisX();
xAxis->get_Scaling()->set_Minimum(MakeObject<AxisBound>(System::DateTime(2017, 11, 5).ToOADate()));
xAxis->get_Scaling()->set_Maximum(MakeObject<AxisBound>(System::DateTime(2017, 12, 3)));
// Set the major units of the X-axis to a week, and the minor units to a day.
xAxis->set_BaseTimeUnit(AxisTimeUnit::Days);
xAxis->set_MajorUnit(7.0);
xAxis->set_MajorTickMark(AxisTickMark::Cross);
xAxis->set_MinorUnit(1.0);
xAxis->set_MinorTickMark(AxisTickMark::Outside);
// Define Y-axis properties for decimal values.
SharedPtr<ChartAxis> yAxis = chart->get_AxisY();
yAxis->set_TickLabelPosition(AxisTickLabelPosition::High);
yAxis->set_MajorUnit(100.0);
yAxis->set_MinorUnit(50.0);
yAxis->get_DisplayUnit()->set_Unit(AxisBuiltInUnit::Hundreds);
yAxis->get_Scaling()->set_Minimum(MakeObject<AxisBound>(100.0));
yAxis->get_Scaling()->set_Maximum(MakeObject<AxisBound>(700.0));
doc->Save(ArtifactsDir + u"Charts.DateTimeValues.docx");
Enumerator
Cross 

Specifies that the tick marks shall cross the axis.

Inside 

Specifies that the tick marks shall be inside the plot area.

Outside 

Specifies that the tick marks shall be outside the plot area.

None 

Specifies that there shall be no tick marks.

◆ AxisTimeUnit

Specifies the unit of time for axes.

Examples

Shows how to insert chart with date/time values.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<Shape> shape = builder->InsertChart(ChartType::Line, 500, 300);
SharedPtr<Chart> chart = shape->get_Chart();
// Clear the chart's demo data series to start with a clean chart.
chart->get_Series()->Clear();
// Add a custom series containing date/time values for the X-axis, and respective decimal values for the Y-axis.
chart->get_Series()->Add(u"Aspose Test Series",
MakeArray<System::DateTime>({System::DateTime(2017, 11, 6), System::DateTime(2017, 11, 9), System::DateTime(2017, 11, 15),
System::DateTime(2017, 11, 21), System::DateTime(2017, 11, 25), System::DateTime(2017, 11, 29)}),
MakeArray<double>({1.2, 0.3, 2.1, 2.9, 4.2, 5.3}));
// Set lower and upper bounds for the X-axis.
SharedPtr<ChartAxis> xAxis = chart->get_AxisX();
xAxis->get_Scaling()->set_Minimum(MakeObject<AxisBound>(System::DateTime(2017, 11, 5).ToOADate()));
xAxis->get_Scaling()->set_Maximum(MakeObject<AxisBound>(System::DateTime(2017, 12, 3)));
// Set the major units of the X-axis to a week, and the minor units to a day.
xAxis->set_BaseTimeUnit(AxisTimeUnit::Days);
xAxis->set_MajorUnit(7.0);
xAxis->set_MajorTickMark(AxisTickMark::Cross);
xAxis->set_MinorUnit(1.0);
xAxis->set_MinorTickMark(AxisTickMark::Outside);
// Define Y-axis properties for decimal values.
SharedPtr<ChartAxis> yAxis = chart->get_AxisY();
yAxis->set_TickLabelPosition(AxisTickLabelPosition::High);
yAxis->set_MajorUnit(100.0);
yAxis->set_MinorUnit(50.0);
yAxis->get_DisplayUnit()->set_Unit(AxisBuiltInUnit::Hundreds);
yAxis->get_Scaling()->set_Minimum(MakeObject<AxisBound>(100.0));
yAxis->get_Scaling()->set_Maximum(MakeObject<AxisBound>(700.0));
doc->Save(ArtifactsDir + u"Charts.DateTimeValues.docx");
Enumerator
Automatic 

Specifies that unit was not set explicitly and default value should be used.

Days 

Specifies that the chart data shall be shown in days.

Months 

Specifies that the chart data shall be shown in months.

Years 

Specifies that the chart data shall be shown in years.

◆ ChartAxisType

Specifies type of chart axis.

Examples

Shows how to create an appropriate type of chart series for a graph type.

void ChartSeriesCollection_()
{
auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// There are several ways of populating a chart's series collection.
// Different series schemas are intended for different chart types.
// 1 - Column chart with columns grouped and banded along the X-axis by category:
SharedPtr<Chart> chart = AppendChart(builder, ChartType::Column, 500, 300);
ArrayPtr<String> categories = MakeArray<String>({u"Category 1", u"Category 2", u"Category 3"});
// Insert two series of decimal values containing a value for each respective category.
// This column chart will have three groups, each with two columns.
chart->get_Series()->Add(u"Series 1", categories, MakeArray<double>({76.6, 82.1, 91.6}));
chart->get_Series()->Add(u"Series 2", categories, MakeArray<double>({64.2, 79.5, 94.0}));
// Categories are distributed along the X-axis, and values are distributed along the Y-axis.
ASSERT_EQ(ChartAxisType::Category, chart->get_AxisX()->get_Type());
ASSERT_EQ(ChartAxisType::Value, chart->get_AxisY()->get_Type());
// 2 - Area chart with dates distributed along the X-axis:
chart = AppendChart(builder, ChartType::Area, 500, 300);
ArrayPtr<System::DateTime> dates =
MakeArray<System::DateTime>({System::DateTime(2014, 3, 31), System::DateTime(2017, 1, 23), System::DateTime(2017, 6, 18),
System::DateTime(2019, 11, 22), System::DateTime(2020, 9, 7)});
// Insert a series with a decimal value for each respective date.
// The dates will be distributed along a linear X-axis,
// and the values added to this series will create data points.
chart->get_Series()->Add(u"Series 1", dates, MakeArray<double>({15.8, 21.5, 22.9, 28.7, 33.1}));
ASSERT_EQ(ChartAxisType::Category, chart->get_AxisX()->get_Type());
ASSERT_EQ(ChartAxisType::Value, chart->get_AxisY()->get_Type());
// 3 - 2D scatter plot:
chart = AppendChart(builder, ChartType::Scatter, 500, 300);
// Each series will need two decimal arrays of equal length.
// The first array contains X-values, and the second contains corresponding Y-values
// of data points on the chart's graph.
chart->get_Series()->Add(u"Series 1", MakeArray<double>({3.1, 3.5, 6.3, 4.1, 2.2, 8.3, 1.2, 3.6}),
MakeArray<double>({3.1, 6.3, 4.6, 0.9, 8.5, 4.2, 2.3, 9.9}));
chart->get_Series()->Add(u"Series 2", MakeArray<double>({2.6, 7.3, 4.5, 6.6, 2.1, 9.3, 0.7, 3.3}),
MakeArray<double>({7.1, 6.6, 3.5, 7.8, 7.7, 9.5, 1.3, 4.6}));
ASSERT_EQ(ChartAxisType::Value, chart->get_AxisX()->get_Type());
ASSERT_EQ(ChartAxisType::Value, chart->get_AxisY()->get_Type());
// 4 - Bubble chart:
chart = AppendChart(builder, ChartType::Bubble, 500, 300);
// Each series will need three decimal arrays of equal length.
// The first array contains X-values, the second contains corresponding Y-values,
// and the third contains diameters for each of the graph's data points.
chart->get_Series()->Add(u"Series 1", MakeArray<double>({1.1, 5.0, 9.8}), MakeArray<double>({1.2, 4.9, 9.9}), MakeArray<double>({2.0, 4.0, 8.0}));
doc->Save(ArtifactsDir + u"Charts.ChartSeriesCollection.docx");
}
static SharedPtr<Chart> AppendChart(SharedPtr<DocumentBuilder> builder, ChartType chartType, double width, double height)
{
SharedPtr<Shape> chartShape = builder->InsertChart(chartType, width, height);
SharedPtr<Chart> chart = chartShape->get_Chart();
chart->get_Series()->Clear();
return chart;
}
Enumerator
Category 

Category axis of a chart.

Series 

Series axis of a chart.

Value 

Value axis of a chart.

◆ ChartType

Specifies type of a chart.

Examples

Shows how to create an appropriate type of chart series for a graph type.

void ChartSeriesCollection_()
{
auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// There are several ways of populating a chart's series collection.
// Different series schemas are intended for different chart types.
// 1 - Column chart with columns grouped and banded along the X-axis by category:
SharedPtr<Chart> chart = AppendChart(builder, ChartType::Column, 500, 300);
ArrayPtr<String> categories = MakeArray<String>({u"Category 1", u"Category 2", u"Category 3"});
// Insert two series of decimal values containing a value for each respective category.
// This column chart will have three groups, each with two columns.
chart->get_Series()->Add(u"Series 1", categories, MakeArray<double>({76.6, 82.1, 91.6}));
chart->get_Series()->Add(u"Series 2", categories, MakeArray<double>({64.2, 79.5, 94.0}));
// Categories are distributed along the X-axis, and values are distributed along the Y-axis.
ASSERT_EQ(ChartAxisType::Category, chart->get_AxisX()->get_Type());
ASSERT_EQ(ChartAxisType::Value, chart->get_AxisY()->get_Type());
// 2 - Area chart with dates distributed along the X-axis:
chart = AppendChart(builder, ChartType::Area, 500, 300);
ArrayPtr<System::DateTime> dates =
MakeArray<System::DateTime>({System::DateTime(2014, 3, 31), System::DateTime(2017, 1, 23), System::DateTime(2017, 6, 18),
System::DateTime(2019, 11, 22), System::DateTime(2020, 9, 7)});
// Insert a series with a decimal value for each respective date.
// The dates will be distributed along a linear X-axis,
// and the values added to this series will create data points.
chart->get_Series()->Add(u"Series 1", dates, MakeArray<double>({15.8, 21.5, 22.9, 28.7, 33.1}));
ASSERT_EQ(ChartAxisType::Category, chart->get_AxisX()->get_Type());
ASSERT_EQ(ChartAxisType::Value, chart->get_AxisY()->get_Type());
// 3 - 2D scatter plot:
chart = AppendChart(builder, ChartType::Scatter, 500, 300);
// Each series will need two decimal arrays of equal length.
// The first array contains X-values, and the second contains corresponding Y-values
// of data points on the chart's graph.
chart->get_Series()->Add(u"Series 1", MakeArray<double>({3.1, 3.5, 6.3, 4.1, 2.2, 8.3, 1.2, 3.6}),
MakeArray<double>({3.1, 6.3, 4.6, 0.9, 8.5, 4.2, 2.3, 9.9}));
chart->get_Series()->Add(u"Series 2", MakeArray<double>({2.6, 7.3, 4.5, 6.6, 2.1, 9.3, 0.7, 3.3}),
MakeArray<double>({7.1, 6.6, 3.5, 7.8, 7.7, 9.5, 1.3, 4.6}));
ASSERT_EQ(ChartAxisType::Value, chart->get_AxisX()->get_Type());
ASSERT_EQ(ChartAxisType::Value, chart->get_AxisY()->get_Type());
// 4 - Bubble chart:
chart = AppendChart(builder, ChartType::Bubble, 500, 300);
// Each series will need three decimal arrays of equal length.
// The first array contains X-values, the second contains corresponding Y-values,
// and the third contains diameters for each of the graph's data points.
chart->get_Series()->Add(u"Series 1", MakeArray<double>({1.1, 5.0, 9.8}), MakeArray<double>({1.2, 4.9, 9.9}), MakeArray<double>({2.0, 4.0, 8.0}));
doc->Save(ArtifactsDir + u"Charts.ChartSeriesCollection.docx");
}
static SharedPtr<Chart> AppendChart(SharedPtr<DocumentBuilder> builder, ChartType chartType, double width, double height)
{
SharedPtr<Shape> chartShape = builder->InsertChart(chartType, width, height);
SharedPtr<Chart> chart = chartShape->get_Chart();
chart->get_Series()->Clear();
return chart;
}
Enumerator
Area 

Area chart.

AreaStacked 

Stacked Area chart.

AreaPercentStacked 

100% Stacked Area chart.

Area3D 

3D Area chart.

Area3DStacked 

3D Stacked Area chart.

Area3DPercentStacked 

3D 100% Stacked Area chart.

Bar 

Bar chart.

BarStacked 

Stacked Bar chart.

BarPercentStacked 

100% Stacked Bar chart.

Bar3D 

3D Bar chart.

Bar3DStacked 

3D Stacked Bar chart.

Bar3DPercentStacked 

3D 100% Stacked Bar chart.

Bubble 

Bubble chart.

Bubble3D 

3D Bubble chart.

Column 

Column chart.

ColumnStacked 

Stacked Column chart.

ColumnPercentStacked 

100% Stacked Column chart.

Column3D 

3D Column chart.

Column3DStacked 

3D Stacked Column chart.

Column3DPercentStacked 

3D 100% Stacked Column chart.

Column3DClustered 

3D Clustered Column chart.

Doughnut 

Doughnut chart.

Line 

Line chart.

LineStacked 

Stacked Line chart.

LinePercentStacked 

100% Stacked Line chart.

Line3D 

3D Line chart.

Pie 

Pie chart.

Pie3D 

3D Pie chart.

PieOfBar 

Pie of Bar chart.

PieOfPie 

Pie of Pie chart.

Radar 

Radar chart.

Scatter 

Scatter chart.

Stock 

Stock chart.

Surface 

Surface chart.

Surface3D 

3D Surface chart.

◆ LegendPosition

Specifies the possible positions for a chart legend.

Examples

Shows how to edit the appearance of a chart's legend.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<Shape> shape = builder->InsertChart(ChartType::Line, 450, 300);
SharedPtr<Chart> chart = shape->get_Chart();
ASSERT_EQ(3, chart->get_Series()->get_Count());
ASSERT_EQ(u"Series 1", chart->get_Series()->idx_get(0)->get_Name());
ASSERT_EQ(u"Series 2", chart->get_Series()->idx_get(1)->get_Name());
ASSERT_EQ(u"Series 3", chart->get_Series()->idx_get(2)->get_Name());
// Move the chart's legend to the top right corner.
SharedPtr<ChartLegend> legend = chart->get_Legend();
legend->set_Position(LegendPosition::TopRight);
// Give other chart elements, such as the graph, more room by allowing them to overlap the legend.
legend->set_Overlay(true);
doc->Save(ArtifactsDir + u"Charts.ChartLegend.docx");
Enumerator
None 

No legend will be shown for the chart.

Bottom 

Specifies that the legend shall be drawn at the bottom of the chart.

Left 

Specifies that the legend shall be drawn at the left of the chart.

Right 

Specifies that the legend shall be drawn at the right of the chart.

Top 

Specifies that the legend shall be drawn at the top of the chart.

TopRight 

Specifies that the legend shall be drawn at the top right of the chart.

◆ MarkerSymbol

Specifies marker symbol style.

Examples

Shows how to work with data points on a line chart.

void ChartDataPoint_()
{
auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<Shape> shape = builder->InsertChart(ChartType::Line, 500, 350);
SharedPtr<Chart> chart = shape->get_Chart();
ASSERT_EQ(3, chart->get_Series()->get_Count());
ASSERT_EQ(u"Series 1", chart->get_Series()->idx_get(0)->get_Name());
ASSERT_EQ(u"Series 2", chart->get_Series()->idx_get(1)->get_Name());
ASSERT_EQ(u"Series 3", chart->get_Series()->idx_get(2)->get_Name());
// Emphasize the chart's data points by making them appear as diamond shapes.
for (const auto& series : System::IterateOver(chart->get_Series()))
{
ApplyDataPoints(series, 4, MarkerSymbol::Diamond, 15);
}
// Smooth out the line that represents the first data series.
chart->get_Series()->idx_get(0)->set_Smooth(true);
// Verify that data points for the first series will not invert their colors if the value is negative.
{
SharedPtr<System::Collections::Generic::IEnumerator<SharedPtr<ChartDataPoint>>> enumerator =
chart->get_Series()->idx_get(0)->get_DataPoints()->GetEnumerator();
while (enumerator->MoveNext())
{
ASSERT_FALSE(enumerator->get_Current()->get_InvertIfNegative());
}
}
// For a cleaner looking graph, we can clear format individually.
chart->get_Series()->idx_get(1)->get_DataPoints()->idx_get(2)->ClearFormat();
// We can also strip an entire series of data points at once.
chart->get_Series()->idx_get(2)->get_DataPoints()->ClearFormat();
doc->Save(ArtifactsDir + u"Charts.ChartDataPoint.docx");
}
static void ApplyDataPoints(SharedPtr<ChartSeries> series, int dataPointsCount, MarkerSymbol markerSymbol, int dataPointSize)
{
for (int i = 0; i < dataPointsCount; i++)
{
SharedPtr<ChartDataPoint> point = series->get_DataPoints()->idx_get(i);
point->get_Marker()->set_Symbol(markerSymbol);
point->get_Marker()->set_Size(dataPointSize);
ASSERT_EQ(i, point->get_Index());
}
}
Enumerator
Default 

Specifies a default marker symbol shall be drawn at each data point.

Circle 

Specifies a circle shall be drawn at each data point.

Dash 

Specifies a dash shall be drawn at each data point.

Diamond 

Specifies a diamond shall be drawn at each data point.

Dot 

Specifies a dot shall be drawn at each data point.

None 

Specifies nothing shall be drawn at each data point.

Picture 

Specifies a picture shall be drawn at each data point.

Plus 

Specifies a plus shall be drawn at each data point.

Square 

Specifies a square shall be drawn at each data point.

Star 

Specifies a star shall be drawn at each data point.

Triangle 

Specifies a triangle shall be drawn at each data point.

Specifies an X shall be drawn at each data point.