ExcelChart Class

Namespace:

GemBox.Spreadsheet.Charts

Assembly:

GemBox.Spreadsheet.dll

Represents a base class for all charts in a worksheet.

• C#
• VB.NET

public abstract class ExcelChart : ExcelDrawing

Inheritance:

System.Object

ExcelDrawing

ExcelChart

Derived

AreaChart

BarChart

ColumnChart

ComboChart

DoughnutChart

LineChart

PieChart

ScatterChart

Properties

CategoryLabels

Gets the chart's category labels.

• C#
• VB.NET

public virtual IEnumerable<string> CategoryLabels { get; }

Property Value

System.Collections.Generic.IEnumerable<System.String>

The chart's category labels.

Remarks

If category labels are not set neither as CategoryLabelsReference nor as SetCategoryLabels(IEnumerable<String>), automatic labels will be used (sequence of integral numbers starting from 1 whose count will be equal to the count of Values in the first chart series).

CategoryLabelsReference

Gets or sets the chart's category labels as a cell range reference (for example, 'Sheet1!A1:D1'). Values from cells in the referenced range will be used as category labels.

• C#
• VB.NET

public virtual string CategoryLabelsReference { get; set; }

Property Value

System.String

The chart's category labels as a cell range reference.

ChartType

Gets the ChartType of this ExcelChart instance.

• C#
• VB.NET

public abstract ChartType ChartType { get; }

Property Value

ChartType

The ChartType of this ExcelChart instance.

DataLabels

Gets the settings for the data labels for the entire chart.

• C#
• VB.NET

public ChartDataLabels DataLabels { get; }

Property Value

ChartDataLabels

The settings for the data labels for the entire chart.

Fill

Gets or sets the fill formatting options.

• C#
• VB.NET

public FillFormat Fill { get; set; }

Property Value

FillFormat

The fill formatting options.

Legend

Gets the chart's legend.

• C#
• VB.NET

public ChartLegend Legend { get; }

Property Value

ChartLegend

The chart's legend.

Outline

Gets or sets the outline formatting options.

• C#
• VB.NET

public LineFormat Outline { get; set; }

Property Value

LineFormat

The outline formatting options.

PlotArea

Gets the chart's plot area.

• C#
• VB.NET

public ChartPlotArea PlotArea { get; }

Property Value

ChartPlotArea

The chart's plot area.

RoundedCorners

Gets or sets a value indicating whether the chart area border has rounded corners.

Default value is false.

• C#
• VB.NET

public bool RoundedCorners { get; set; }

Property Value

System.Boolean

true if the chart area border has rounded corners; otherwise, false.

Remarks

Supported only in XLSX and XLSB.

Series

Gets the chart's series.

• C#
• VB.NET

public ChartSeriesCollection Series { get; }

Property Value

ChartSeriesCollection

The chart's series.

ShowDataInHiddenCells

Gets or sets the value which indicates whether only visible cells should be plotted on the chart.

• C#
• VB.NET

public bool ShowDataInHiddenCells { get; set; }

Property Value

System.Boolean

true to plot also cells in hidden rows or columns, false otherwise.

ShowEmptyCellsAs

Gets or sets the value which indicates how empty cells (cells with Value equal to null) shall be plotted on the chart.

• C#
• VB.NET

public EmptyCellDisplayMode ShowEmptyCellsAs { get; set; }

Property Value

EmptyCellDisplayMode

The value which indicates how empty cells (cells with Value equal to null) shall be plotted on the chart.

TextFormat

Gets or sets the text formatting options.

• C#
• VB.NET

public TextFormat TextFormat { get; set; }

Property Value

TextFormat

The text formatting options.

Title

Gets the chart's title.

• C#
• VB.NET

public ChartTitle Title { get; }

Property Value

ChartTitle

The chart's title.

UseSecondaryAxis

Gets or sets the value which indicates whether this chart should use the secondary axis of parent ComboChart.

• C#
• VB.NET

public bool UseSecondaryAxis { get; set; }

Property Value

System.Boolean

true if this chart uses the secondary axis, false otherwise.

Remarks

This property is only used for charts that are children of a ComboChart.

Setting UseSecondaryAxis to true on all inner charts of a ComboChart will result in all of them being set again to false, since Excel does not allow for a chart to not use its primary axis.

Methods

BringForward()

Moves the chart one position forward in the drawings if the parent collection is ExcelChartCollection.

• C#
• VB.NET

public void BringForward()

Remarks

The index of the chart in the ExcelChartCollection will not be updated if the drawing in front is a different type. But it will still update the position.

BringToFront()

Brings the chart to the front of the drawings if the parent collection is ExcelChartCollection.

• C#
• VB.NET

public void BringToFront()

ChangeChartType(ChartType)

Changes the chart to a different type of chart.

• C#
• VB.NET

public ExcelChart ChangeChartType(ChartType chartType)

Parameters

chartType

ChartType

Type of chart to change the chart to.

Returns

ExcelChart

A chart of different type.

Exceptions

System.NotSupportedException

Changing to or from Combo is not supported.

ChangeChartType<TChart>()

Changes the chart to a different type of chart.

• C#
• VB.NET

public TChart ChangeChartType<TChart>()
    where TChart : ExcelChart

Returns

TChart

A chart of different type.

Type Parameters

TChart

Type of chart deriving from ExcelChart type to change the chart to.

MoveZIndex(Int32)

Moves the picture forward or backward in the drawings with the given relative index if the parent collection is ExcelChartCollection.

• C#
• VB.NET

public void MoveZIndex(int relativeIndex)

Parameters

relativeIndex

System.Int32

The relative index for the picture to update. Negative to move backward and positive to move forward.

SelectData(CellRange)

Selects the data for the chart.

• C#
• VB.NET

public void SelectData(CellRange range)

Parameters

range

CellRange

The cell range which contains data for the chart.

Exceptions

SpreadsheetException

Parameter range is null or not valid.

SelectData(CellRange, Boolean)

Selects the data for the chart.

• C#
• VB.NET

public void SelectData(CellRange range, bool switchRowColumn)

Parameters

range

CellRange

The cell range which contains data for the chart.

switchRowColumn

System.Boolean

if set to true category labels will be in first column (not row), series names will be in first row (not column) and series values will be in columns (not rows).

Exceptions

SpreadsheetException

Parameter range is null or not valid.

SelectData(CellRange, Boolean, Boolean)

Selects the data for the chart.

• C#
• VB.NET

public void SelectData(CellRange range, bool switchRowColumn, bool excludeCategoryLabels)

Parameters

range

CellRange

The cell range which contains data for the chart.

switchRowColumn

System.Boolean

if set to true category labels will be in first column (not row), series names will be in first row (not column) and series values will be in columns (not rows).

excludeCategoryLabels

System.Boolean

if set to true, category labels won't be resolved from range.

Exceptions

SpreadsheetException

Parameter range is null or not valid.

SelectData(CellRange, Boolean, Boolean, Boolean)

Selects the data for the chart.

• C#
• VB.NET

public void SelectData(CellRange range, bool switchRowColumn, bool excludeCategoryLabels, bool excludeSeriesNames)

Parameters

range

CellRange

The cell range which contains data for the chart.

switchRowColumn

System.Boolean

if set to true category labels will be in first column (not row), series names will be in first row (not column) and series values will be in columns (not rows).

excludeCategoryLabels

System.Boolean

if set to true, category labels won't be resolved from range.

excludeSeriesNames

System.Boolean

if set to true, series names won't be resolved from range.

Exceptions

SpreadsheetException

Parameter range is null or not valid.

SelectData(String)

Selects the data for the chart.

• C#
• VB.NET

public void SelectData(string range)

Parameters

range

System.String

The cell range which contains data for the chart.

Exceptions

SpreadsheetException

Either chart is in invalid state or range parameter is not valid.

SelectData(String, Boolean)

Selects the data for the chart.

• C#
• VB.NET

public void SelectData(string range, bool switchRowColumn)

Parameters

range

System.String

The cell range which contains data for the chart.

switchRowColumn

System.Boolean

if set to true category labels will be in first column (not row), series names will be in first row (not column) and series values will be in columns (not rows).

Exceptions

SpreadsheetException

Either chart is in invalid state or range parameter is not valid.

SelectData(String, Boolean, Boolean)

Selects the data for the chart.

• C#
• VB.NET

public void SelectData(string range, bool switchRowColumn, bool excludeCategoryLabels)

Parameters

range

System.String

The cell range which contains data for the chart.

switchRowColumn

System.Boolean

if set to true category labels will be in first column (not row), series names will be in first row (not column) and series values will be in columns (not rows).

excludeCategoryLabels

System.Boolean

if set to true, category labels won't be resolved from range.

Exceptions

SpreadsheetException

Either chart is in invalid state or range parameter is not valid.

SelectData(String, Boolean, Boolean, Boolean)

Selects the data for the chart.

• C#
• VB.NET

public void SelectData(string range, bool switchRowColumn, bool excludeCategoryLabels, bool excludeSeriesNames)

Parameters

range

System.String

The cell range which contains data for the chart.

switchRowColumn

System.Boolean

if set to true category labels will be in first column (not row), series names will be in first row (not column) and series values will be in columns (not rows).

excludeCategoryLabels

System.Boolean

if set to true, category labels won't be resolved from range.

excludeSeriesNames

System.Boolean

if set to true, series names won't be resolved from range.

Exceptions

SpreadsheetException

Either chart is in invalid state or range parameter is not valid.

SendBackward()

Moves the chart one position backward in the drawings if the parent collection is ExcelChartCollection.

• C#
• VB.NET

public void SendBackward()

Remarks

The index of the chart in the ExcelChartCollection will not be updated if the item behind is a different type. But it will still update the position.

SendToBack()

Sends the chart to the back of the drawings if the parent collection is ExcelChartCollection.

• C#
• VB.NET

public void SendToBack()

SetCategoryLabels(IEnumerable<String>)

Sets the chart's category labels.

• C#
• VB.NET

public virtual void SetCategoryLabels(IEnumerable<string> categoryLabels)

Parameters

categoryLabels

System.Collections.Generic.IEnumerable<System.String>

The chart's category labels.

Exceptions

System.ArgumentNullException

categoryLabels is null.

SetCategoryLabels(String[])

Sets the chart's category labels.

• C#
• VB.NET

public void SetCategoryLabels(params string[] categoryLabels)

Parameters

categoryLabels

System.String[]

The chart's category labels.

ToString()

Returns a System.String that represents this ExcelChart instance.

• C#
• VB.NET

public sealed override string ToString()

Returns

System.String

A System.String that represents this ExcelChart instance.

Overrides

System.Object.ToString()

Remarks

This method should be used primarily for debugging purposes and should be considered volatile (format of its return value might change in future versions).

Inherited Properties

Hyperlink	Gets or sets the hyperlink on this drawing (picture, chart, etc.). (Inherited from ExcelDrawing)
Metadata	Gets the metadata (non-visual properties) of this ExcelDrawing instance. (Inherited from ExcelDrawing)
Position	Gets the position of this drawing (picture, chart, etc.) in the worksheet. (Inherited from ExcelDrawing)
Worksheet	Gets the parent worksheet. (Inherited from ExcelDrawing)
ZIndex	Gets the z-order position of the picture. -1 if the picture is not contained in proper collection. (Inherited from ExcelDrawing)

Inherited Methods

Format()	Formats this drawing (picture, chart, etc.) to its default size so it can be exported to PDF, XPS, image or be printed. (Inherited from ExcelDrawing)
Format(System.Double, System.Double, LengthUnit)	Formats this drawing (picture, chart, etc.) to specified size so it can be exported to PDF, XPS, image or be printed. (Inherited from ExcelDrawing)