EmbeddedChart

Represents a chart that has been embedded into a spreadsheet.

This example shows how to modify an existing chart:

```javascript
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('A2:B8');
let 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:

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

### Methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart#asDataSourceChart()` | `https://developers.google.com/apps-script/reference/spreadsheet/data-source-chart|null` | Casts to a data source chart instance if the chart is a data source chart, or `null` otherwise. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart#getAs(String)` | `https://developers.google.com/apps-script/reference/base/blob.html` | Return the data inside this object as a blob converted to the specified content type. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart#getBlob()` | `https://developers.google.com/apps-script/reference/base/blob.html` | Return the data inside this object as a blob. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart#getChartId()` | `Integer|null` | Returns a stable identifier for the chart that is unique across the spreadsheet containing the chart or `null` if the chart is not in a spreadsheet. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart#getContainerInfo()` | `https://developers.google.com/apps-script/reference/spreadsheet/container-info` | Returns information about where the chart is positioned within a sheet. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart#getHiddenDimensionStrategy()` | `https://developers.google.com/apps-script/reference/charts/chart-hidden-dimension-strategy.html` | Returns the strategy to use for handling hidden rows and columns. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart#getMergeStrategy()` | `https://developers.google.com/apps-script/reference/charts/chart-merge-strategy.html` | Returns the merge strategy used when more than one range exists. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart#getNumHeaders()` | `Integer` | Returns the number of rows or columns the range that are treated as headers. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart#getOptions()` | `https://developers.google.com/apps-script/reference/charts/chart-options.html` | Returns the options for this chart, such as height, colors, and axes. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart#getRanges()` | `https://developers.google.com/apps-script/reference/spreadsheet/range` | Returns the ranges that this chart uses as a data source. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart#getTransposeRowsAndColumns()` | `Boolean` | If `true`, the rows and columns used to populate the chart are switched. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart#modify()` | `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder` | Returns an `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder` that can be used to modify this chart. |

## Detailed documentation

### `asDataSourceChart()`

Casts to a data source chart instance if the chart is a data source chart, or `null`
otherwise.

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/data-source-chart|null` --- The data source chart.

*** ** * ** ***

### `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".

To view the daily quotas for conversions, see [Quotas for Google
Services](https://developers.google.com/apps-script/guides/services/quotas). Newly created Google Workspace domains might be temporarily subject to stricter
quotas.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `contentType` | `String` | The 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. For a Google Docs document, `'text/markdown'` is also valid. |

#### Return


`https://developers.google.com/apps-script/reference/base/blob.html` --- The data as a blob.

*** ** * ** ***

### `getBlob()`

Return the data inside this object as a blob.

#### Return


`https://developers.google.com/apps-script/reference/base/blob.html` --- The data as a blob.

*** ** * ** ***

### `getChartId()`

Returns a stable identifier for the chart that is unique across the spreadsheet containing the
chart or `null` if the chart is not in a spreadsheet.

#### Return


`Integer|null` --- A stable chart identifier.

*** ** * ** ***

### `getContainerInfo()`

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

```javascript
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

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

const containerInfo = chart.getContainerInfo();

// Logs the values 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


`https://developers.google.com/apps-script/reference/spreadsheet/container-info` --- An object containing the chart container's position.

*** ** * ** ***

### `getHiddenDimensionStrategy()`

Returns the strategy to use for handling hidden rows and columns. Defaults to `https://developers.google.com/apps-script/reference/charts/chart-hidden-dimension-strategy.html`.

```javascript
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

const range = sheet.getRange('A1:B5');
const 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


`https://developers.google.com/apps-script/reference/charts/chart-hidden-dimension-strategy.html` --- The strategy to use for hidden rows and columns.

*** ** * ** ***

### `getMergeStrategy()`

Returns the merge strategy used when more than one range exists. If `https://developers.google.com/apps-script/reference/charts/chart-merge-strategy.html#MERGE_ROWS`, row are merged; if `https://developers.google.com/apps-script/reference/charts/chart-merge-strategy.html#MERGE_COLUMNS`, columns are merged. Defaults to `https://developers.google.com/apps-script/reference/charts/chart-merge-strategy.html#MERGE_COLUMNS`.

```javascript
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

const range = sheet.getRange('A1:B10');
const range2 = sheet.getRange('C1:C10');
const 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


`https://developers.google.com/apps-script/reference/charts/chart-merge-strategy.html` --- `https://developers.google.com/apps-script/reference/charts/chart-merge-strategy.html#MERGE_ROWS` If rows are merged across multiple
ranges; `https://developers.google.com/apps-script/reference/charts/chart-merge-strategy.html#MERGE_COLUMNS` if columns are merged
across multiple ranges.

*** ** * ** ***

### `getNumHeaders()`

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

```javascript
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

const range = sheet.getRange('A1:B5');
const 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, and axes.

The returned options are immutable.

#### Return


`https://developers.google.com/apps-script/reference/charts/chart-options.html` --- The options for this chart, such as height, colors, and axes.

*** ** * ** ***

### `getRanges()`

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

```javascript
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

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

const ranges = chart.getRanges();

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

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/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`.

```javascript
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

const range = sheet.getRange('A1:B5');
const 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


`Boolean` --- `True` if the rows and columns used to construct the chart are transposed.

*** ** * ** ***

### `modify()`

Returns an `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder` that can be used to modify this chart. Invoke `sheet.updateChart(chart)` to save any changes.

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

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder` --- A builder for creating embedded charts.