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

Public MustInherit Class ExcelChart
    Inherits 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; }

Public Overridable ReadOnly Property CategoryLabels As IEnumerable(Of String)

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; }

Public Overridable Property CategoryLabelsReference As String

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; }

Public MustOverride ReadOnly Property ChartType As ChartType

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; }

Public ReadOnly Property DataLabels As ChartDataLabels

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; }

Public Property Fill As FillFormat

Property Value

FillFormat

The fill formatting options.

Legend

Gets the chart's legend.

• C#
• VB.NET

public ChartLegend Legend { get; }

Public ReadOnly Property Legend As ChartLegend

Property Value

ChartLegend

The chart's legend.

Outline

Gets or sets the outline formatting options.

• C#
• VB.NET

public LineFormat Outline { get; set; }

Public Property Outline As LineFormat

Property Value

LineFormat

The outline formatting options.

PlotArea

Gets the chart's plot area.

• C#
• VB.NET

public ChartPlotArea PlotArea { get; }

Public ReadOnly Property PlotArea As ChartPlotArea

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; }

Public Property RoundedCorners As Boolean

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; }

Public ReadOnly Property Series As ChartSeriesCollection

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; }

Public Property ShowDataInHiddenCells As Boolean

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; }

Public Property ShowEmptyCellsAs As EmptyCellDisplayMode

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; }

Public Property TextFormat As TextFormat

Property Value

TextFormat

The text formatting options.

Title

Gets the chart's title.

• C#
• VB.NET

public ChartTitle Title { get; }

Public ReadOnly Property Title As ChartTitle

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; }

Public Property UseSecondaryAxis As Boolean

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()

Public Sub 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()

Public Sub BringToFront

ChangeChartType(ChartType)

Changes the chart to a different type of chart.

• C#
• VB.NET

public ExcelChart ChangeChartType(ChartType chartType)

Public Function ChangeChartType(chartType As ChartType) As ExcelChart

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

Public Function ChangeChartType(Of TChart As ExcelChart) As TChart

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)

Public Sub MoveZIndex(relativeIndex As Integer)

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)

Public Sub SelectData(range As CellRange)

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)

Public Sub SelectData(range As CellRange, switchRowColumn As Boolean)

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)

Public Sub SelectData(range As CellRange, switchRowColumn As Boolean, excludeCategoryLabels As Boolean)

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)

Public Sub SelectData(range As CellRange, switchRowColumn As Boolean, excludeCategoryLabels As Boolean, excludeSeriesNames As Boolean)

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)

Public Sub SelectData(range As String)

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)

Public Sub SelectData(range As String, switchRowColumn As Boolean)

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)

Public Sub SelectData(range As String, switchRowColumn As Boolean, excludeCategoryLabels As Boolean)

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)

Public Sub SelectData(range As String, switchRowColumn As Boolean, excludeCategoryLabels As Boolean, excludeSeriesNames As Boolean)

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()

Public Sub 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()

Public Sub SendToBack

SetCategoryLabels(IEnumerable<String>)

Sets the chart's category labels.

• C#
• VB.NET

public virtual void SetCategoryLabels(IEnumerable<string> categoryLabels)

Public Overridable Sub SetCategoryLabels(categoryLabels As IEnumerable(Of String))

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)

Public Sub SetCategoryLabels(ParamArray categoryLabels As String())

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()

Public NotOverridable Overrides Function ToString As String

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)