Interface ITrendline

public interface ITrendline

Represents a trendline in a chart.

A trendline shows the trend, or direction, of data in a series. Use this interface to configure how the trendline is calculated and displayed, such as its type, forward or backward projection, equation, and R-squared value.


 worksheet.getRange("A1:B5").setValue(new Object[][] {
     {"Month", "Sales"}, {"Jan", 10}, {"Feb", 15}, {"Mar", 18}, {"Apr", 24}
 });
 IShape shape = worksheet.getShapes().addChart(ChartType.ColumnClustered, 200, 30, 300, 300);
 shape.getChart().getSeriesCollection().add(worksheet.getRange("A1:B5"), RowCol.Columns, true, true);
 ITrendline trendline = shape.getChart().getSeriesCollection().get(0).getTrendlines().add();
 trendline.setType(TrendlineType.Linear);

Method Summary

Modifier and Type

Method

Description

void

clearFormats()

Clears the formatting of this trendline.

void

delete()

Deletes this trendline.

double

getBackward()

Gets the number of periods, or units on a scatter chart, that the trendline extends backward.

IDataLabel

getDataLabel()

Gets the data label associated with the trendline.

boolean

getDisplayEquation()

Gets whether the equation for the trendline is displayed on the chart.

boolean

getDisplayRSquared()

Gets whether the trendline displays its R-squared value.

IChartFormat

getFormat()

Gets the chart format of the trendline.

double

getForward()

Gets the number of periods, or units on a scatter chart, that the trendline extends forward.

int

getIndex()

Gets the index number of this trendline within the collection of trendlines for the series.

double

getIntercept()

Gets the point where the trendline crosses the value axis.

String

getName()

Gets the name of the trendline.

boolean

getNameIsAuto()

Gets whether the trendline's name is automatically determined.

int

getOrder()

Gets the trendline order when the trendline type is TrendlineType.Polynomial.

ISeries

getParent()

Gets the parent series of the trendline.

int

getPeriod()

Gets the period for the moving-average trendline.

TrendlineType

getType()

Gets the trendline type.

void

setBackward(double value)

Sets the number of periods, or units on a scatter chart, that the trendline extends backward.

void

setDisplayEquation(boolean value)

Sets whether the equation for the trendline is displayed on the chart.

void

setDisplayRSquared(boolean value)

Sets whether the trendline displays its R-squared value.

void

setForward(double value)

Sets the number of periods, or units on a scatter chart, that the trendline extends forward.

void

setIntercept(double value)

Sets the point where the trendline crosses the value axis.

void

setName(String name)

Sets the name of the trendline.

void

setNameIsAuto(boolean value)

Sets whether the trendline's name is automatically determined.

void

setOrder(int value)

Sets the trendline order when the trendline type is TrendlineType.Polynomial.

void

setPeriod(int value)

Sets the period for the moving-average trendline.

void

setType(TrendlineType value)

Sets the trendline type.

Method Details

getIndex

int getIndex()

Gets the index number of this trendline within the collection of trendlines for the series.

The index identifies the trendline's position among similar objects in the same collection.


 worksheet.getRange("A1:A4").setValue(new Object[] { 10, 20, 30, 40 });
 IShape shape = worksheet.getShapes().addChart(ChartType.ColumnClustered, 20, 20, 360, 220);
 shape.getChart().getSeriesCollection().add(worksheet.getRange("A1:A4"), RowCol.Columns);
 ITrendline trendline = shape.getChart().getSeriesCollection().get(0).getTrendlines().add();
 int index = trendline.getIndex();

Returns:: The index number of the trendline within the collection of similar objects.

getBackward

double getBackward()

Gets the number of periods, or units on a scatter chart, that the trendline extends backward.

Use this property to read the backward forecast length configured for the trendline. For scatter charts, the returned value represents units on the horizontal axis rather than category periods.


 worksheet.getRange("A1:A4").setValue(new Object[] { 10, 20, 30, 40 });
 IShape shape = worksheet.getShapes().addChart(ChartType.ColumnClustered, 20, 20, 360, 220);
 shape.getChart().getSeriesCollection().add(worksheet.getRange("A1:A4"), RowCol.Columns);
 ITrendline trendline = shape.getChart().getSeriesCollection().get(0).getTrendlines().add();
 trendline.setBackward(0.5);
 double backward = trendline.getBackward();

Returns:: The number of periods, or units on a scatter chart, that the trendline extends backward.

setBackward

void setBackward(double value)
Sets the number of periods, or units on a scatter chart, that the trendline extends backward.
Use this property to set the backward forecast length configured for the trendline. For scatter charts, the value represents units on the horizontal axis rather than category periods.
```
 worksheet.getRange("A1:A4").setValue(new Object[] { 10, 20, 30, 40 });
 IShape shape = worksheet.getShapes().addChart(ChartType.ColumnClustered, 20, 20, 360, 220);
 shape.getChart().getSeriesCollection().add(worksheet.getRange("A1:A4"), RowCol.Columns);
 ITrendline trendline = shape.getChart().getSeriesCollection().get(0).getTrendlines().add();
 trendline.setBackward(0.5);
 
```
Parameters:

value - The number of periods, or units on a scatter chart, that the trendline extends backward.

getDisplayEquation

boolean getDisplayEquation()

Gets whether the equation for the trendline is displayed on the chart.

If this property is true, the equation is shown in the same data label as the R-squared value. Use setDisplayEquation(boolean) to enable or disable the equation display.


 worksheet.getRange("A1:A4").setValue(new Object[] { 10, 20, 30, 40 });
 IShape shape = worksheet.getShapes().addChart(ChartType.ColumnClustered, 20, 20, 360, 220);
 shape.getChart().getSeriesCollection().add(worksheet.getRange("A1:A4"), RowCol.Columns);
 ITrendline trendline = shape.getChart().getSeriesCollection().get(0).getTrendlines().add();
 trendline.setDisplayEquation(true);
 boolean displayEquation = trendline.getDisplayEquation();

Returns:: true if the trendline equation is displayed on the chart; otherwise, false.

setDisplayEquation

void setDisplayEquation(boolean value)

Sets whether the equation for the trendline is displayed on the chart.


 worksheet.getRange("A1:A4").setValue(new Object[] { 10, 20, 30, 40 });
 IShape shape = worksheet.getShapes().addChart(ChartType.ColumnClustered, 20, 20, 360, 220);
 shape.getChart().getSeriesCollection().add(worksheet.getRange("A1:A4"), RowCol.Columns);
 ITrendline trendline = shape.getChart().getSeriesCollection().get(0).getTrendlines().add();
 trendline.setDisplayEquation(true);

Parameters:: value - true if the trendline equation is displayed on the chart; otherwise, false.

getDisplayRSquared

boolean getDisplayRSquared()

Gets whether the trendline displays its R-squared value.

If this property is true, the R-squared value is displayed on the chart in the same data label as the trendline equation. Enabling this setting also turns on data labels. See getDataLabel() and setDisplayRSquared(boolean).


 worksheet.getRange("A1:B4").setValue(new Object[][] {
     {1, 2},
     {2, 4},
     {3, 6},
     {4, 8}
 });
 IShape shape = worksheet.getShapes().addChart(ChartType.XYScatter, 20, 20, 360, 230);
 shape.getChart().getSeriesCollection().add(worksheet.getRange("A1:B4"), RowCol.Columns, false, false);
 ITrendline trendline = shape.getChart().getSeriesCollection().get(0).getTrendlines().add();
 trendline.setDisplayRSquared(true);
 boolean displayRSquared = trendline.getDisplayRSquared();

Returns:: true if the trendline displays its R-squared value; otherwise, false.

setDisplayRSquared

void setDisplayRSquared(boolean value)

Sets whether the trendline displays its R-squared value.


 worksheet.getRange("A1:B4").setValue(new Object[][] {
     {1, 2},
     {2, 4},
     {3, 6},
     {4, 8}
 });
 IShape shape = worksheet.getShapes().addChart(ChartType.XYScatter, 20, 20, 360, 230);
 shape.getChart().getSeriesCollection().add(worksheet.getRange("A1:B4"), RowCol.Columns, false, false);
 ITrendline trendline = shape.getChart().getSeriesCollection().get(0).getTrendlines().add();
 trendline.setDisplayRSquared(true);

Parameters:: value - true if the trendline displays its R-squared value; otherwise, false.

getFormat

IChartFormat getFormat()

Gets the chart format of the trendline.

The returned IChartFormat object provides access to the trendline's fill and line formatting settings.


 worksheet.getRange("A1:A4").setValue(new Object[] { 10, 20, 30, 40 });
 IShape shape = worksheet.getShapes().addChart(ChartType.ColumnClustered, 20, 20, 360, 220);
 shape.getChart().getSeriesCollection().add(worksheet.getRange("A1:A4"), RowCol.Columns);
 ITrendline trendline = shape.getChart().getSeriesCollection().get(0).getTrendlines().add();
 IChartFormat format = trendline.getFormat();
 format.getLine().getColor().setRGB(Color.GetBlue());

Returns:: The IChartFormat object that represents the trendline formatting.

getForward

double getForward()

Gets the number of periods, or units on a scatter chart, that the trendline extends forward.

Use this property to read the forecast length configured for the trendline. For scatter charts, the returned value represents units on the horizontal axis rather than category periods.


 worksheet.getRange("A1:A4").setValue(new Object[] { 10, 20, 30, 40 });
 IShape shape = worksheet.getShapes().addChart(ChartType.ColumnClustered, 20, 20, 360, 220);
 shape.getChart().getSeriesCollection().add(worksheet.getRange("A1:A4"), RowCol.Columns);
 ITrendline trendline = shape.getChart().getSeriesCollection().get(0).getTrendlines().add();
 trendline.setForward(1.5);
 double forward = trendline.getForward();

Returns:: The number of periods, or units on a scatter chart, that the trendline extends forward.

setForward

void setForward(double value)
Sets the number of periods, or units on a scatter chart, that the trendline extends forward.
Use this property to set the forecast length configured for the trendline. For scatter charts, the value represents units on the horizontal axis rather than category periods.
```
 worksheet.getRange("A1:A4").setValue(new Object[] { 10, 20, 30, 40 });
 IShape shape = worksheet.getShapes().addChart(ChartType.ColumnClustered, 20, 20, 360, 220);
 shape.getChart().getSeriesCollection().add(worksheet.getRange("A1:A4"), RowCol.Columns);
 ITrendline trendline = shape.getChart().getSeriesCollection().get(0).getTrendlines().add();
 trendline.setForward(1.5);
 
```
Parameters:

value - The number of periods, or units on a scatter chart, that the trendline extends forward.

getIntercept

double getIntercept()

Gets the point where the trendline crosses the value axis.

Returns the fixed intercept value when the trendline intercept has been set explicitly.


 worksheet.getRange("A1:B5").setValue(new Object[][] {
     {1, 2},
     {2, 4},
     {3, 6},
     {4, 8},
     {5, 10}
 });
 IChart chart = worksheet.getShapes().addChart(ChartType.XYScatter, 20, 20, 300, 200).getChart();
 chart.setSourceData(worksheet.getRange("A1:B5"));
 ITrendline trendline = chart.getSeriesCollection().get(0).getTrendlines().add();
 trendline.setIntercept(1.5);
 double intercept = trendline.getIntercept();

Returns:: The point where the trendline crosses the value axis.

setIntercept

void setIntercept(double value)

Sets the point where the trendline crosses the value axis.

Sets the fixed intercept value when the trendline intercept has been set explicitly.


 worksheet.getRange("A1:B5").setValue(new Object[][] {
     {1, 2},
     {2, 4},
     {3, 6},
     {4, 8},
     {5, 10}
 });
 IChart chart = worksheet.getShapes().addChart(ChartType.XYScatter, 20, 20, 300, 200).getChart();
 chart.setSourceData(worksheet.getRange("A1:B5"));
 ITrendline trendline = chart.getSeriesCollection().get(0).getTrendlines().add();
 trendline.setIntercept(1.5);

Parameters:: value - The point where the trendline crosses the value axis.

getName

String getName()

Gets the name of the trendline.

Returns the custom name assigned to the trendline. If the trendline name is determined automatically, this method returns the current automatically generated name.


 worksheet.getRange("A1:A4").setValue(new Object[] { 10, 20, 30, 40 });
 IShape shape = worksheet.getShapes().addChart(ChartType.ColumnClustered, 20, 20, 360, 220);
 shape.getChart().getSeriesCollection().add(worksheet.getRange("A1:A4"), RowCol.Columns);
 ITrendline trendline = shape.getChart().getSeriesCollection().get(0).getTrendlines().add();
 trendline.setName("Sales Trend");
 String name = trendline.getName();

Returns:: The trendline name.

setName

void setName(String name)

Sets the name of the trendline.

Sets the custom name assigned to the trendline. If the trendline name is determined automatically, this method Sets the current automatically generated name.


 worksheet.getRange("A1:A4").setValue(new Object[] { 10, 20, 30, 40 });
 IShape shape = worksheet.getShapes().addChart(ChartType.ColumnClustered, 20, 20, 360, 220);
 shape.getChart().getSeriesCollection().add(worksheet.getRange("A1:A4"), RowCol.Columns);
 ITrendline trendline = shape.getChart().getSeriesCollection().get(0).getTrendlines().add();
 trendline.setName("Sales Trend");

Parameters:: name - The trendline name.

getNameIsAuto

boolean getNameIsAuto()

Gets whether the trendline's name is automatically determined.

When this property is true, the trendline uses an automatically generated name. When it is false, the name can be controlled explicitly, for example by using setName(String).


 worksheet.getRange("A1:A4").setValue(new Object[] { 10, 20, 30, 40 });
 IShape shape = worksheet.getShapes().addChart(ChartType.ColumnClustered, 20, 20, 360, 220);
 shape.getChart().getSeriesCollection().add(worksheet.getRange("A1:A4"), RowCol.Columns);
 ITrendline trendline = shape.getChart().getSeriesCollection().get(0).getTrendlines().add();
 trendline.setNameIsAuto(false);
 boolean nameIsAuto = trendline.getNameIsAuto();

Returns:: true if the trendline's name is automatically determined; otherwise, false.

setNameIsAuto

void setNameIsAuto(boolean value)

Sets whether the trendline's name is automatically determined.

When this property is true, the trendline uses an automatically generated name. When it is false, the name can be controlled explicitly, for example by using setName(String).


 worksheet.getRange("A1:A4").setValue(new Object[] { 10, 20, 30, 40 });
 IShape shape = worksheet.getShapes().addChart(ChartType.ColumnClustered, 20, 20, 360, 220);
 shape.getChart().getSeriesCollection().add(worksheet.getRange("A1:A4"), RowCol.Columns);
 ITrendline trendline = shape.getChart().getSeriesCollection().get(0).getTrendlines().add();
 trendline.setNameIsAuto(false);

Parameters:: value - true if the trendline's name is automatically determined; otherwise, false.

getOrder

int getOrder()

Gets the trendline order when the trendline type is TrendlineType.Polynomial.

The order specifies the degree of the polynomial trendline.


 worksheet.getRange("A1:A4").setValue(new Object[] { 10, 20, 30, 40 });
 IShape shape = worksheet.getShapes().addChart(ChartType.ColumnClustered, 20, 20, 360, 220);
 shape.getChart().getSeriesCollection().add(worksheet.getRange("A1:A4"), RowCol.Columns);
 ITrendline trendline = shape.getChart().getSeriesCollection().get(0).getTrendlines().add();
 trendline.setType(TrendlineType.Polynomial);
 trendline.setOrder(3);
 int order = trendline.getOrder();

Returns:: The trendline order.

setOrder

void setOrder(int value)

Sets the trendline order when the trendline type is TrendlineType.Polynomial.

The order specifies the degree of the polynomial trendline.


 worksheet.getRange("A1:A4").setValue(new Object[] { 10, 20, 30, 40 });
 IShape shape = worksheet.getShapes().addChart(ChartType.ColumnClustered, 20, 20, 360, 220);
 shape.getChart().getSeriesCollection().add(worksheet.getRange("A1:A4"), RowCol.Columns);
 ITrendline trendline = shape.getChart().getSeriesCollection().get(0).getTrendlines().add();
 trendline.setType(TrendlineType.Polynomial);
 trendline.setOrder(3);

Parameters:: value - The trendline order.

getParent

ISeries getParent()

Gets the parent series of the trendline.

Use this method to access the ISeries that contains the current trendline.


 worksheet.getRange("A1:A4").setValue(new Object[] { 10, 20, 30, 40 });
 IShape shape = worksheet.getShapes().addChart(ChartType.ColumnClustered, 20, 20, 360, 220);
 shape.getChart().getSeriesCollection().add(worksheet.getRange("A1:A4"), RowCol.Columns);
 ITrendline trendline = shape.getChart().getSeriesCollection().get(0).getTrendlines().add();
 ISeries parentSeries = trendline.getParent();

Returns:: The ISeries that contains the trendline.

getPeriod

int getPeriod()

Gets the period for the moving-average trendline.

This property applies to a trendline whose type is TrendlineType.MovingAvg.


 worksheet.getRange("A1:A4").setValue(new Object[] { 10, 20, 30, 40 });
 IShape shape = worksheet.getShapes().addChart(ChartType.ColumnClustered, 20, 20, 360, 220);
 shape.getChart().getSeriesCollection().add(worksheet.getRange("A1:A4"), RowCol.Columns);
 ITrendline trendline = shape.getChart().getSeriesCollection().get(0).getTrendlines().add();
 trendline.setType(TrendlineType.MovingAvg);
 trendline.setPeriod(2);
 int period = trendline.getPeriod();

Returns:: The period of the moving-average trendline.

setPeriod

void setPeriod(int value)

Sets the period for the moving-average trendline.

This property applies to a trendline whose type is TrendlineType.MovingAvg.


 worksheet.getRange("A1:A4").setValue(new Object[] { 10, 20, 30, 40 });
 IShape shape = worksheet.getShapes().addChart(ChartType.ColumnClustered, 20, 20, 360, 220);
 shape.getChart().getSeriesCollection().add(worksheet.getRange("A1:A4"), RowCol.Columns);
 ITrendline trendline = shape.getChart().getSeriesCollection().get(0).getTrendlines().add();
 trendline.setType(TrendlineType.MovingAvg);
 trendline.setPeriod(2);

Parameters:: value - The period of the moving-average trendline.

getType

TrendlineType getType()

Gets the trendline type.

Returns a TrendlineType value that specifies how the trendline is calculated.


 worksheet.getRange("A1:A4").setValue(new Object[] { 10, 20, 30, 40 });
 IShape shape = worksheet.getShapes().addChart(ChartType.ColumnClustered, 20, 20, 360, 220);
 shape.getChart().getSeriesCollection().add(worksheet.getRange("A1:A4"), RowCol.Columns);
 ITrendline trendline = shape.getChart().getSeriesCollection().get(0).getTrendlines().add();
 trendline.setType(TrendlineType.Linear);
 TrendlineType type = trendline.getType();

Returns:: The trendline type.

setType

void setType(TrendlineType value)

Sets the trendline type.

Use this method to change how the trendline is calculated for the associated series.


 worksheet.getRange("A1:B5").setValue(new Object[][] {
     {"Month", "Sales"},
     {"Jan", 12},
     {"Feb", 18},
     {"Mar", 15},
     {"Apr", 21}
 });
 IChart chart = worksheet.getShapes().addChart(ChartType.ColumnClustered, 20, 20, 300, 200).getChart();
 chart.getSeriesCollection().add(worksheet.getRange("A1:B5"), RowCol.Columns, true, false);
 ITrendline trendline = chart.getSeriesCollection().get(0).getTrendlines().add();
 trendline.setType(TrendlineType.Linear);

Parameters:: value - The trendline type to apply.

getDataLabel

IDataLabel getDataLabel()

Gets the data label associated with the trendline.

The returned IDataLabel object can be used to configure the content and formatting of the trendline label displayed on the chart.


 worksheet.getRange("A1:A4").setValue(new Object[] { 10, 20, 30, 40 });
 IShape shape = worksheet.getShapes().addChart(ChartType.ColumnClustered, 20, 20, 360, 220);
 shape.getChart().getSeriesCollection().add(worksheet.getRange("A1:A4"), RowCol.Columns);
 ITrendline trendline = shape.getChart().getSeriesCollection().get(0).getTrendlines().add();
 trendline.setDisplayEquation(true);
 IDataLabel dataLabel = trendline.getDataLabel();
 dataLabel.getFormat().getFill().getColor().setRGB(Color.GetRed());

Returns:: The IDataLabel object that represents the data label associated with the trendline.

clearFormats

void clearFormats()

Clears the formatting of this trendline.

Use this method to remove custom formatting that has been applied to the trendline.


 worksheet.getRange("A1:A4").setValue(new Object[] { 10, 20, 30, 40 });
 IShape shape = worksheet.getShapes().addChart(ChartType.ColumnClustered, 20, 20, 360, 220);
 shape.getChart().getSeriesCollection().add(worksheet.getRange("A1:A4"), RowCol.Columns);
 ITrendline trendline = shape.getChart().getSeriesCollection().get(0).getTrendlines().add();
 trendline.getFormat().getLine().getColor().setRGB(Color.GetBlue());
 trendline.clearFormats();

delete

void delete()

Deletes this trendline.

After this method is called, the trendline is removed from its parent chart series.


 worksheet.getRange("A1:A4").setValue(new Object[] { 10, 20, 30, 40 });
 IShape shape = worksheet.getShapes().addChart(ChartType.ColumnClustered, 20, 20, 360, 220);
 shape.getChart().getSeriesCollection().add(worksheet.getRange("A1:A4"), RowCol.Columns);
 ITrendline trendline = shape.getChart().getSeriesCollection().get(0).getTrendlines().add();
 trendline.delete();