Class EmbeddedChart

EmbeddedChart

Represents a chart that has been embedded into a spreadsheet.

This example shows how to modify an existing chart:


 var sheet = SpreadsheetApp.getActiveSheet();
 var range = sheet.getRange("A2:B8")
 var chart = sheet.getCharts()[0];
 chart = chart.modify()
     .addRange(range)
     .setOption('title', 'Updated!')
     .setOption('animation.duration', 500)
     .setPosition(2,2,0,0)
     .build();
 sheet.updateChart(chart);
 

This example shows how to create a new chart:


 function newChart(range, sheet) {
   var sheet = SpreadsheetApp.getActiveSheet();
   var chartBuilder = sheet.newChart();
   chartBuilder.addRange(range)
       .setChartType(Charts.ChartType.LINE)
       .setOption('title', 'My Line Chart!');
   sheet.insertChart(chartBuilder.build());
 }
 

Methods

MethodReturn typeBrief description
getAs(contentType)BlobReturn the data inside this object as a blob converted to the specified content type.
getBlob()BlobReturn the data inside this object as a blob.
getContainerInfo()ContainerInfoReturns information about where the chart is positioned within a sheet.
getHiddenDimensionStrategy()ChartHiddenDimensionStrategyReturns the strategy to use for handling hidden rows and columns.
getId()StringReturns the id that has been assigned to this object.
getMergeStrategy()ChartMergeStrategyReturns the merge strategy used when more than one range exists.
getNumHeaders()IntegerReturns the number of rows or columns the range that are treated as headers.
getOptions()ChartOptionsReturns the options for this chart, such as height, colors, axes, etc.
getRanges()Range[]Returns the ranges that this chart uses as a data source.
getTransposeRowsAndColumns()BooleanIf true, the rows and columns used to populate the chart are switched.
getType()StringGets the type of this object.
modify()EmbeddedChartBuilderReturns an EmbeddedChartBuilder that can be used to modify this chart.
setId(id)ChartSets the id of this EmbeddedChart to be used with UiApp.

Detailed documentation

getAs(contentType)

Return the data inside this object as a blob converted to the specified content type. This method adds the appropriate extension to the filename—for example, "myfile.pdf". However, it assumes that the part of the filename that follows the last period (if any) is an existing extension that should be replaced. Consequently, "ShoppingList.12.25.2014" becomes "ShoppingList.12.25.pdf".

Parameters

NameTypeDescription
contentTypeStringthe MIME type to convert to. For most blobs, 'application/pdf' is the only valid option. For images in BMP, GIF, JPEG, or PNG format, any of 'image/bmp', 'image/gif', 'image/jpeg', or 'image/png' are also valid.

Return

Blob — the data as a blob


getBlob()

Return the data inside this object as a blob.

Return

Blob — the data as a blob


getContainerInfo()

Returns information about where the chart is positioned within a sheet.


 var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 var chart = sheet.newChart()
     .setChartType(Charts.ChartType.BAR)
     .addRange(sheet.getRange("A1:B8"))
     .setPosition(5, 5, 0, 0)
     .build();

 var containerInfo = chart.getContainerInfo();

 // Logs the values we used in setPosition()
 Logger.log("Anchor Column: %s\r\nAnchor Row %s\r\nOffset X %s\r\nOffset Y %s",
           containerInfo.getAnchorColumn(),
           containerInfo.getAnchorRow(),
           containerInfo.getOffsetX(),
           containerInfo.getOffsetY());
 

Return

ContainerInfo — an object containing the chart container's position


getHiddenDimensionStrategy()

Returns the strategy to use for handling hidden rows and columns. Defaults to IGNORE_ROWS.


 var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 var range = sheet.getRange("A1:B5");
 var chart = sheet.newChart()
     .setChartType(Charts.ChartType.BAR)
     .addRange(range)
     .setHiddenDimensionStrategy(Charts.ChartHiddenDimensionStrategy.IGNORE_COLUMNS)
     .setPosition(5, 5, 0, 0)
     .build()

 // Logs the strategy to use for hidden rows and columns which is
 // Charts.ChartHiddenDimensionStrategy.IGNORE_COLUMNS in this case.
 Logger.log(chart.getHiddenDimensionStrategy());
 

Return

ChartHiddenDimensionStrategy — The strategy to use for hidden rows and columns.


getId()

Returns the id that has been assigned to this object.

This can be used in conjunction with app.getElementById() to retrieve a reference to this object.

Return

String — the id that has been assigned to this object


getMergeStrategy()

Returns the merge strategy used when more than one range exists. If MERGE_ROWS, row are merged; if MERGE_COLUMNS, columns are merged. Defaults to MERGE_COLUMNS.


 var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 var range = sheet.getRange("A1:B10");
 var range2 = sheet.getRange("C1:C10");
 var chart = sheet.newChart()
     .setChartType(Charts.ChartType.BAR)
     .addRange(range)
     .addRange(range2)
     .setMergeStrategy(Charts.ChartMergeStrategy.MERGE_ROWS)
     .setPosition(5, 5, 0, 0)
     .build()

 // Logs whether rows of multiple ranges are merged, which is MERGE_ROWS in this case.
 Logger.log(chart.getMergeStrategy());
 

Return

ChartMergeStrategyMERGE_ROWS if rows are merged across multiple ranges; MERGE_COLUMNS if columns are merged across multiple ranges


getNumHeaders()

Returns the number of rows or columns the range that are treated as headers.


 var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 var range = sheet.getRange("A1:B5");
 var chart = sheet.newChart()
     .setChartType(Charts.ChartType.BAR)
     .addRange(range)
     .setNumHeaders(1)
     .setPosition(5, 5, 0, 0)
     .build()

 // Logs the number of rows or columns to use as headers, which is 1 in this case.
 Logger.log(chart.getHeaders());
 

Return

Integer — The number of rows or columns treated as headers. Negative values indicate the headers are auto-detected.


getOptions()

Returns the options for this chart, such as height, colors, axes, etc.

The returned options are immutable.

Return

ChartOptions — the options for this chart, such as height, colors, axes, etc.


getRanges()

Returns the ranges that this chart uses as a data source.


 var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 var chart = sheet.newChart()
     .setChartType(Charts.ChartType.BAR)
     .addRange(sheet.getRange("A1:B8"))
     .setPosition(5, 5, 0, 0)
     .build();

 var ranges = chart.getRanges();

 // There's only one range as a data source for this chart,
 // so this logs "A1:B8"
 for (var i in ranges) {
   var range = ranges[i];
   Logger.log(range.getA1Notation());
 }
 

Return

Range[] — an array of ranges that serve as this chart's data source


getTransposeRowsAndColumns()

If true, the rows and columns used to populate the chart are switched. Defaults to false.


 var ss = SpreadsheetApp.getActiveSpreadsheet();
 var sheet = ss.getSheets()[0];

 var range = sheet.getRange("A1:B5");
 var chart = sheet.newChart()
     .addRange(range)
     .setChartType(Charts.ChartType.BAR)
     .setTransposeRowsAndColumns(true)
     .setPosition(5, 5, 0, 0)
     .build()

 // Logs whether rows and columns should be transposed, which is true in this case.
 Logger.log(chart.getTransposeRowsAndColumns());
 

Return

Booleantrue if the rows and columns used to construct the chart are transposed.


getType()

Gets the type of this object.

Return

String — the object type


modify()

Returns an EmbeddedChartBuilder that can be used to modify this chart. Invoke sheet.updateChart(chart) to save any changes.


 var sheet = SpreadsheetApp.getActiveSheet();
 var chart = sheet.getCharts()[0];
 chart = chart.modify()
     .setOption('width', 800)
     .setOption('height', 640)
     .setPosition(5, 5, 0, 0)
     .build();
 sheet.updateChart(chart);
 

Return

EmbeddedChartBuilder — a builder for creating embedded charts


setId(id)

Sets the id of this EmbeddedChart to be used with UiApp.

Parameters

NameTypeDescription
idStringthe new id, which can be used to retrieve the EmbeddedChart from app.getElementById(id).

Return

Chart — the EmbeddedChart itself, useful for chaining.

Send feedback about...

Apps Script
Apps Script
Need help? Visit our support page.