com.aspose.words
Class ChartSeries

java.lang.Object
    com.aspose.words.ChartSeries

All Implemented Interfaces:

IChartDataPoint, java.lang.Cloneable

public class ChartSeries 
extends java.lang.Object

public void dataLabels() throws Exception {
    Document doc = new Document();
    DocumentBuilder builder = new DocumentBuilder(doc);

    Shape chartShape = builder.insertChart(ChartType.LINE, 400.0, 300.0);
    Chart chart = chartShape.getChart();

    Assert.assertEquals(3, chart.getSeries().getCount());
    Assert.assertEquals("Series 1", chart.getSeries().get(0).getName());
    Assert.assertEquals("Series 2", chart.getSeries().get(1).getName());
    Assert.assertEquals("Series 3", chart.getSeries().get(2).getName());

    // Apply data labels to every series in the chart.
    // These labels will appear next to each data point in the graph and display its value.
    for (ChartSeries series : chart.getSeries()) {
        applyDataLabels(series, 4, "000.0", ", ");
        Assert.assertEquals(series.getDataLabels().getCount(), 4);
    }

    // Change the separator string for every data label in a series.
    Iterator<ChartDataLabel> enumerator = chart.getSeries().get(0).getDataLabels().iterator();
    while (enumerator.hasNext()) {
        Assert.assertEquals(enumerator.next().getSeparator(), ", ");
        enumerator.next().setSeparator(" & ");
    }

    // For a cleaner looking graph, we can remove data labels individually.
    chart.getSeries().get(1).getDataLabels().get(2).clearFormat();

    // We can also strip an entire series of its data labels at once.
    chart.getSeries().get(2).getDataLabels().clearFormat();

    doc.save(getArtifactsDir() + "Charts.DataLabels.docx");
}

/// <summary>
/// Apply data labels with custom number format and separator to several data points in a series.
/// </summary>
private static void applyDataLabels(ChartSeries series, int labelsCount, String numberFormat, String separator) {
    for (int i = 0; i < labelsCount; i++) {
        series.hasDataLabels(true);

        Assert.assertFalse(series.getDataLabels().get(i).isVisible());

        series.getDataLabels().get(i).setShowCategoryName(true);
        series.getDataLabels().get(i).setShowSeriesName(true);
        series.getDataLabels().get(i).setShowValue(true);
        series.getDataLabels().get(i).setShowLeaderLines(true);
        series.getDataLabels().get(i).setShowLegendKey(true);
        series.getDataLabels().get(i).setShowPercentage(false);
        series.getDataLabels().get(i).isHidden(false);
        Assert.assertFalse(series.getDataLabels().get(i).getShowDataLabelsRange());

        series.getDataLabels().get(i).getNumberFormat().setFormatCode(numberFormat);
        series.getDataLabels().get(i).setSeparator(separator);

        Assert.assertFalse(series.getDataLabels().get(i).getShowDataLabelsRange());
        Assert.assertTrue(series.getDataLabels().get(i).isVisible());
        Assert.assertFalse(series.getDataLabels().get(i).isHidden());
    }
}

public boolean getBubble3D() / public void setBubble3D(boolean value)

Specifies whether the bubbles in Bubble chart should have a 3-D effect applied to them.

public BubbleSizeCollection getBubbleSizes()

Gets a collection of bubble sizes for this chart series.

public ChartDataLabelCollection getDataLabels()

Specifies the settings for the data labels for the entire series.

Example:

Shows how to apply labels to data points in a line chart.

public void dataLabels() throws Exception {
    Document doc = new Document();
    DocumentBuilder builder = new DocumentBuilder(doc);

    Shape chartShape = builder.insertChart(ChartType.LINE, 400.0, 300.0);
    Chart chart = chartShape.getChart();

    Assert.assertEquals(3, chart.getSeries().getCount());
    Assert.assertEquals("Series 1", chart.getSeries().get(0).getName());
    Assert.assertEquals("Series 2", chart.getSeries().get(1).getName());
    Assert.assertEquals("Series 3", chart.getSeries().get(2).getName());

    // Apply data labels to every series in the chart.
    // These labels will appear next to each data point in the graph and display its value.
    for (ChartSeries series : chart.getSeries()) {
        applyDataLabels(series, 4, "000.0", ", ");
        Assert.assertEquals(series.getDataLabels().getCount(), 4);
    }

    // Change the separator string for every data label in a series.
    Iterator<ChartDataLabel> enumerator = chart.getSeries().get(0).getDataLabels().iterator();
    while (enumerator.hasNext()) {
        Assert.assertEquals(enumerator.next().getSeparator(), ", ");
        enumerator.next().setSeparator(" & ");
    }

    // For a cleaner looking graph, we can remove data labels individually.
    chart.getSeries().get(1).getDataLabels().get(2).clearFormat();

    // We can also strip an entire series of its data labels at once.
    chart.getSeries().get(2).getDataLabels().clearFormat();

    doc.save(getArtifactsDir() + "Charts.DataLabels.docx");
}

/// <summary>
/// Apply data labels with custom number format and separator to several data points in a series.
/// </summary>
private static void applyDataLabels(ChartSeries series, int labelsCount, String numberFormat, String separator) {
    for (int i = 0; i < labelsCount; i++) {
        series.hasDataLabels(true);

        Assert.assertFalse(series.getDataLabels().get(i).isVisible());

        series.getDataLabels().get(i).setShowCategoryName(true);
        series.getDataLabels().get(i).setShowSeriesName(true);
        series.getDataLabels().get(i).setShowValue(true);
        series.getDataLabels().get(i).setShowLeaderLines(true);
        series.getDataLabels().get(i).setShowLegendKey(true);
        series.getDataLabels().get(i).setShowPercentage(false);
        series.getDataLabels().get(i).isHidden(false);
        Assert.assertFalse(series.getDataLabels().get(i).getShowDataLabelsRange());

        series.getDataLabels().get(i).getNumberFormat().setFormatCode(numberFormat);
        series.getDataLabels().get(i).setSeparator(separator);

        Assert.assertFalse(series.getDataLabels().get(i).getShowDataLabelsRange());
        Assert.assertTrue(series.getDataLabels().get(i).isVisible());
        Assert.assertFalse(series.getDataLabels().get(i).isHidden());
    }
}

public ChartDataPointCollection getDataPoints()

Returns a collection of formatting objects for all data points in this series.

Example:

Shows how to apply labels to data points in a line chart.

public void dataLabels() throws Exception {
    Document doc = new Document();
    DocumentBuilder builder = new DocumentBuilder(doc);

    Shape chartShape = builder.insertChart(ChartType.LINE, 400.0, 300.0);
    Chart chart = chartShape.getChart();

    Assert.assertEquals(3, chart.getSeries().getCount());
    Assert.assertEquals("Series 1", chart.getSeries().get(0).getName());
    Assert.assertEquals("Series 2", chart.getSeries().get(1).getName());
    Assert.assertEquals("Series 3", chart.getSeries().get(2).getName());

    // Apply data labels to every series in the chart.
    // These labels will appear next to each data point in the graph and display its value.
    for (ChartSeries series : chart.getSeries()) {
        applyDataLabels(series, 4, "000.0", ", ");
        Assert.assertEquals(series.getDataLabels().getCount(), 4);
    }

    // Change the separator string for every data label in a series.
    Iterator<ChartDataLabel> enumerator = chart.getSeries().get(0).getDataLabels().iterator();
    while (enumerator.hasNext()) {
        Assert.assertEquals(enumerator.next().getSeparator(), ", ");
        enumerator.next().setSeparator(" & ");
    }

    // For a cleaner looking graph, we can remove data labels individually.
    chart.getSeries().get(1).getDataLabels().get(2).clearFormat();

    // We can also strip an entire series of its data labels at once.
    chart.getSeries().get(2).getDataLabels().clearFormat();

    doc.save(getArtifactsDir() + "Charts.DataLabels.docx");
}

/// <summary>
/// Apply data labels with custom number format and separator to several data points in a series.
/// </summary>
private static void applyDataLabels(ChartSeries series, int labelsCount, String numberFormat, String separator) {
    for (int i = 0; i < labelsCount; i++) {
        series.hasDataLabels(true);

        Assert.assertFalse(series.getDataLabels().get(i).isVisible());

        series.getDataLabels().get(i).setShowCategoryName(true);
        series.getDataLabels().get(i).setShowSeriesName(true);
        series.getDataLabels().get(i).setShowValue(true);
        series.getDataLabels().get(i).setShowLeaderLines(true);
        series.getDataLabels().get(i).setShowLegendKey(true);
        series.getDataLabels().get(i).setShowPercentage(false);
        series.getDataLabels().get(i).isHidden(false);
        Assert.assertFalse(series.getDataLabels().get(i).getShowDataLabelsRange());

        series.getDataLabels().get(i).getNumberFormat().setFormatCode(numberFormat);
        series.getDataLabels().get(i).setSeparator(separator);

        Assert.assertFalse(series.getDataLabels().get(i).getShowDataLabelsRange());
        Assert.assertTrue(series.getDataLabels().get(i).isVisible());
        Assert.assertFalse(series.getDataLabels().get(i).isHidden());
    }
}

public int getExplosion() / public void setExplosion(int value)

Specifies the amount the data point shall be moved from the center of the pie. Can be negative, negative means that property is not set and no explosion should be applied. Applies only to Pie charts.

public ChartFormat getFormat()

Provides access to fill and line formatting of the series.

Example:

Sows how to set series color.

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

Shape shape = builder.insertChart(ChartType.COLUMN, 432.0, 252.0);

Chart chart = shape.getChart();
ChartSeriesCollection seriesColl = chart.getSeries();

// Delete default generated series.
seriesColl.clear();

// Create category names array.
String[] categories = new String[] { "Category 1", "Category 2" };

// Adding new series. Value and category arrays must be the same size.
ChartSeries series1 = seriesColl.add("Series 1", categories, new double[] { 1.0, 2.0 });
ChartSeries series2 = seriesColl.add("Series 2", categories, new double[] { 3.0, 4.0 });
ChartSeries series3 = seriesColl.add("Series 3", categories, new double[] { 5.0, 6.0 });

// Set series color.
series1.getFormat().getFill().setForeColor(Color.RED);
series2.getFormat().getFill().setForeColor(Color.YELLOW);
series3.getFormat().getFill().setForeColor(Color.BLUE);

doc.save(getArtifactsDir() + "Charts.SeriesColor.docx");

public boolean hasDataLabels() / public void hasDataLabels(boolean value)

Gets or sets a flag indicating whether data labels are displayed for the series.

public boolean getInvertIfNegative() / public void setInvertIfNegative(boolean value)

Specifies whether the parent element shall inverts its colors if the value is negative.

public ChartLegendEntry getLegendEntry()

Gets a legend entry for this chart series.

public ChartMarker getMarker()

Specifies a data marker. Marker is automatically created when requested.

public java.lang.String getName() / public void setName(java.lang.String value)

Gets or sets the name of the series, if name is not set explicitly it is generated using index. By default returns Series plus one based index.

Example:

Shows how to apply labels to data points in a line chart.

public void dataLabels() throws Exception {
    Document doc = new Document();
    DocumentBuilder builder = new DocumentBuilder(doc);

    Shape chartShape = builder.insertChart(ChartType.LINE, 400.0, 300.0);
    Chart chart = chartShape.getChart();

    Assert.assertEquals(3, chart.getSeries().getCount());
    Assert.assertEquals("Series 1", chart.getSeries().get(0).getName());
    Assert.assertEquals("Series 2", chart.getSeries().get(1).getName());
    Assert.assertEquals("Series 3", chart.getSeries().get(2).getName());

    // Apply data labels to every series in the chart.
    // These labels will appear next to each data point in the graph and display its value.
    for (ChartSeries series : chart.getSeries()) {
        applyDataLabels(series, 4, "000.0", ", ");
        Assert.assertEquals(series.getDataLabels().getCount(), 4);
    }

    // Change the separator string for every data label in a series.
    Iterator<ChartDataLabel> enumerator = chart.getSeries().get(0).getDataLabels().iterator();
    while (enumerator.hasNext()) {
        Assert.assertEquals(enumerator.next().getSeparator(), ", ");
        enumerator.next().setSeparator(" & ");
    }

    // For a cleaner looking graph, we can remove data labels individually.
    chart.getSeries().get(1).getDataLabels().get(2).clearFormat();

    // We can also strip an entire series of its data labels at once.
    chart.getSeries().get(2).getDataLabels().clearFormat();

    doc.save(getArtifactsDir() + "Charts.DataLabels.docx");
}

/// <summary>
/// Apply data labels with custom number format and separator to several data points in a series.
/// </summary>
private static void applyDataLabels(ChartSeries series, int labelsCount, String numberFormat, String separator) {
    for (int i = 0; i < labelsCount; i++) {
        series.hasDataLabels(true);

        Assert.assertFalse(series.getDataLabels().get(i).isVisible());

        series.getDataLabels().get(i).setShowCategoryName(true);
        series.getDataLabels().get(i).setShowSeriesName(true);
        series.getDataLabels().get(i).setShowValue(true);
        series.getDataLabels().get(i).setShowLeaderLines(true);
        series.getDataLabels().get(i).setShowLegendKey(true);
        series.getDataLabels().get(i).setShowPercentage(false);
        series.getDataLabels().get(i).isHidden(false);
        Assert.assertFalse(series.getDataLabels().get(i).getShowDataLabelsRange());

        series.getDataLabels().get(i).getNumberFormat().setFormatCode(numberFormat);
        series.getDataLabels().get(i).setSeparator(separator);

        Assert.assertFalse(series.getDataLabels().get(i).getShowDataLabelsRange());
        Assert.assertTrue(series.getDataLabels().get(i).isVisible());
        Assert.assertFalse(series.getDataLabels().get(i).isHidden());
    }
}

public int getSeriesType()

Gets the type of this chart series. The value of the property is ChartSeriesType integer constant.

Example:

Shows how to remove specific chart serie.

Document doc = new Document(getMyDir() + "Reporting engine template - Chart series (Java).docx");
Chart chart = ((Shape)doc.getChild(NodeType.SHAPE, 0, true)).getChart();

// Remove all series of the Column type.
for (int i = chart.getSeries().getCount() - 1; i >= 0; i--)
{
    if (chart.getSeries().get(i).getSeriesType() == ChartSeriesType.COLUMN)
        chart.getSeries().removeAt(i);
}

chart.getSeries().add(
        "Aspose Series",
        new String[] { "Category 1", "Category 2", "Category 3", "Category 4" },
        new double[] { 5.6, 7.1, 2.9, 8.9 });

doc.save(getArtifactsDir() + "Charts.RemoveSpecificChartSeries.docx");

public boolean getSmooth() / public void setSmooth(boolean value)

Allows to specify whether the line connecting the points on the chart shall be smoothed using Catmull-Rom splines.

Example:

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

public void chartDataPoint() throws Exception {
    Document doc = new Document();
    DocumentBuilder builder = new DocumentBuilder(doc);

    Shape shape = builder.insertChart(ChartType.LINE, 500.0, 350.0);
    Chart chart = shape.getChart();

    Assert.assertEquals(3, chart.getSeries().getCount());
    Assert.assertEquals("Series 1", chart.getSeries().get(0).getName());
    Assert.assertEquals("Series 2", chart.getSeries().get(1).getName());
    Assert.assertEquals("Series 3", chart.getSeries().get(2).getName());

    // Emphasize the chart's data points by making them appear as diamond shapes.
    for (ChartSeries series : chart.getSeries())
        applyDataPoints(series, 4, MarkerSymbol.DIAMOND, 15);

    // Smooth out the line that represents the first data series.
    chart.getSeries().get(0).setSmooth(true);

    // Verify that data points for the first series will not invert their colors if the value is negative.
    Iterator<ChartDataPoint> enumerator = chart.getSeries().get(0).getDataPoints().iterator();
    while (enumerator.hasNext()) {
        Assert.assertFalse(enumerator.next().getInvertIfNegative());
    }

    // For a cleaner looking graph, we can clear format individually.
    chart.getSeries().get(1).getDataPoints().get(2).clearFormat();

    // We can also strip an entire series of data points at once.
    chart.getSeries().get(2).getDataPoints().clearFormat();

    doc.save(getArtifactsDir() + "Charts.ChartDataPoint.docx");
}

/// <summary>
/// Applies a number of data points to a series.
/// </summary>
private static void applyDataPoints(ChartSeries series, int dataPointsCount, int markerSymbol, int dataPointSize) {
    for (int i = 0; i < dataPointsCount; i++) {
        ChartDataPoint point = series.getDataPoints().get(i);
        point.getMarker().setSymbol(markerSymbol);
        point.getMarker().setSize(dataPointSize);

        Assert.assertEquals(point.getIndex(), i);
    }
}

public ChartXValueCollection getXValues()

Gets a collection of X values for this chart series.

public ChartYValueCollection getYValues()

Gets a collection of Y values for this chart series.

public void add(ChartXValue xValue)

Adds the specified X value to the chart series. If the series supports Y values and bubble sizes, they will be empty for the X value.

public void add(ChartXValue xValue, ChartYValue yValue)

Adds the specified X and Y values to the chart series.

Example:

Shows how to populate chart series with data.

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

Shape shape = builder.insertChart(ChartType.COLUMN, 432.0, 252.0);
Chart chart = shape.getChart();
ChartSeries series1 = chart.getSeries().get(0);

// Clear X and Y values of the first series.
series1.clearValues();

// Populate the series with data.
series1.add(ChartXValue.fromDouble(3.0), ChartYValue.fromDouble(10.0));
series1.add(ChartXValue.fromDouble(5.0), ChartYValue.fromDouble(5.0));
series1.add(ChartXValue.fromDouble(7.0), ChartYValue.fromDouble(11.0));
series1.add(ChartXValue.fromDouble(9.0), ChartYValue.fromDouble(17.0));

ChartSeries series2 = chart.getSeries().get(1);

// Clear X and Y values of the second series.
series2.clearValues();

// Populate the series with data.
series2.add(ChartXValue.fromDouble(2.0), ChartYValue.fromDouble(4.0));
series2.add(ChartXValue.fromDouble(4.0), ChartYValue.fromDouble(7.0));
series2.add(ChartXValue.fromDouble(6.0), ChartYValue.fromDouble(14.0));
series2.add(ChartXValue.fromDouble(8.0), ChartYValue.fromDouble(7.0));

doc.save(getArtifactsDir() + "Charts.PopulateChartWithData.docx");

Example:

Shows how to add/remove chart data values.

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

Shape shape = builder.insertChart(ChartType.COLUMN, 432.0, 252.0);
Chart chart = shape.getChart();
ChartSeries department1Series = chart.getSeries().get(0);
ChartSeries department2Series = chart.getSeries().get(1);

// Remove the first value in the both series.
department1Series.remove(0);
department2Series.remove(0);

// Add new values to the both series.
ChartXValue newXCategory = ChartXValue.fromString("Q1, 2023");
department1Series.add(newXCategory, ChartYValue.fromDouble(10.3));
department2Series.add(newXCategory, ChartYValue.fromDouble(5.7));

doc.save(getArtifactsDir() + "Charts.ChartDataValues.docx");

public void add(ChartXValue xValue, ChartYValue yValue, double bubbleSize)

Adds the specified X value, Y value and bubble size to the chart series.

public void clear()

Removes all data values from the chart series. Format of all individual data points and data labels is cleared.

public void clearValues()

Removes all data values from the chart series with preserving the format of the data points and data labels.

public void copyFormatFrom(int dataPointIndex)

Copies default data point format from the data point with the specified index.

Example:

Shows how to copy data point format.

Document doc = new Document(getMyDir() + "DataPoint format.docx");

// Get the chart and series to update format.
Shape shape = (Shape)doc.getChild(NodeType.SHAPE, 0, true);
ChartSeries series = shape.getChart().getSeries().get(0);
ChartDataPointCollection dataPoints = series.getDataPoints();

Assert.assertTrue(dataPoints.hasDefaultFormat(0));
Assert.assertFalse(dataPoints.hasDefaultFormat(1));

// Copy format of the data point with index 1 to the data point with index 2
// so that the data point 2 looks the same as the data point 1.
dataPoints.copyFormat(0, 1);

Assert.assertTrue(dataPoints.hasDefaultFormat(0));
Assert.assertTrue(dataPoints.hasDefaultFormat(1));

// Copy format of the data point with index 0 to the series defaults so that all data points
// in the series that have the default format look the same as the data point 0.
series.copyFormatFrom(1);

Assert.assertTrue(dataPoints.hasDefaultFormat(0));
Assert.assertTrue(dataPoints.hasDefaultFormat(1));

doc.save(getArtifactsDir() + "Charts.CopyDataPointFormat.docx");

public void insert(int index, ChartXValue xValue)

Inserts the specified X value into the chart series at the specified index. If the series supports Y values and bubble sizes, they will be empty for the X value.

The corresponding data point with default formatting will be inserted into the data point collection. And, if data labels are displayed, the corresponding data label with default formatting will be inserted too.

public void insert(int index, ChartXValue xValue, ChartYValue yValue)

Inserts the specified X and Y values into the chart series at the specified index.

The corresponding data point with default formatting will be inserted into the data point collection. And, if data labels are displayed, the corresponding data label with default formatting will be inserted too.

public void insert(int index, ChartXValue xValue, ChartYValue yValue, double bubbleSize)

Inserts the specified X value, Y value and bubble size into the chart series at the specified index.

The corresponding data point with default formatting will be inserted into the data point collection. And, if data labels are displayed, the corresponding data label with default formatting will be inserted too.

public void remove(int index)

Removes the X value, Y value, and bubble size, if supported, from the chart series at the specified index. The corresponding data point and data label are also removed.

Example:

Shows how to add/remove chart data values.

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

Shape shape = builder.insertChart(ChartType.COLUMN, 432.0, 252.0);
Chart chart = shape.getChart();
ChartSeries department1Series = chart.getSeries().get(0);
ChartSeries department2Series = chart.getSeries().get(1);

// Remove the first value in the both series.
department1Series.remove(0);
department2Series.remove(0);

// Add new values to the both series.
ChartXValue newXCategory = ChartXValue.fromString("Q1, 2023");
department1Series.add(newXCategory, ChartYValue.fromDouble(10.3));
department2Series.add(newXCategory, ChartYValue.fromDouble(5.7));

doc.save(getArtifactsDir() + "Charts.ChartDataValues.docx");