EmbeddedChartBuilder

Builder used to edit an `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart`. Changes made to the chart are not saved until
`https://developers.google.com/apps-script/reference/spreadsheet/sheet#updateChart(EmbeddedChart)` is called on the rebuilt chart.

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

### Methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#addRange(Range)` | `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#` | Adds a range to the chart this builder modifies. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#asAreaChart()` | `https://developers.google.com/apps-script/reference/spreadsheet/embedded-area-chart-builder` | Sets the chart type to AreaChart and returns an `https://developers.google.com/apps-script/reference/spreadsheet/embedded-area-chart-builder`. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#asBarChart()` | `https://developers.google.com/apps-script/reference/spreadsheet/embedded-bar-chart-builder` | Sets the chart type to BarChart and returns an `https://developers.google.com/apps-script/reference/spreadsheet/embedded-bar-chart-builder`. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#asColumnChart()` | `https://developers.google.com/apps-script/reference/spreadsheet/embedded-column-chart-builder` | Sets the chart type to ColumnChart and returns an `https://developers.google.com/apps-script/reference/spreadsheet/embedded-column-chart-builder`. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#asComboChart()` | `https://developers.google.com/apps-script/reference/spreadsheet/embedded-combo-chart-builder` | Sets the chart type to ComboChart and returns an `https://developers.google.com/apps-script/reference/spreadsheet/embedded-combo-chart-builder`. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#asHistogramChart()` | `https://developers.google.com/apps-script/reference/spreadsheet/embedded-histogram-chart-builder` | Sets the chart type to HistogramChart and returns an `https://developers.google.com/apps-script/reference/spreadsheet/embedded-histogram-chart-builder`. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#asLineChart()` | `https://developers.google.com/apps-script/reference/spreadsheet/embedded-line-chart-builder` | Sets the chart type to LineChart and returns an `https://developers.google.com/apps-script/reference/spreadsheet/embedded-line-chart-builder`. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#asPieChart()` | `https://developers.google.com/apps-script/reference/spreadsheet/embedded-pie-chart-builder` | Sets the chart type to PieChart and returns an `https://developers.google.com/apps-script/reference/spreadsheet/embedded-pie-chart-builder`. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#asScatterChart()` | `https://developers.google.com/apps-script/reference/spreadsheet/embedded-scatter-chart-builder` | Sets the chart type to ScatterChart and returns an `https://developers.google.com/apps-script/reference/spreadsheet/embedded-scatter-chart-builder`. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#asTableChart()` | `https://developers.google.com/apps-script/reference/spreadsheet/embedded-table-chart-builder` | Sets the chart type to TableChart and returns an `https://developers.google.com/apps-script/reference/spreadsheet/embedded-table-chart-builder`. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#build()` | `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart` | Builds the chart to reflect all changes made to it. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#clearRanges()` | `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#` | Removes all ranges from the chart this builder modifies. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#getChartType()` | `https://developers.google.com/apps-script/reference/charts/chart-type.html` | Returns the current chart type. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#getContainer()` | `https://developers.google.com/apps-script/reference/spreadsheet/container-info` | Return the chart `https://developers.google.com/apps-script/reference/spreadsheet/container-info`, which encapsulates where the chart appears on the sheet. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#getRanges()` | `https://developers.google.com/apps-script/reference/spreadsheet/range` | Returns a copy of the list of ranges currently providing data for this chart. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#removeRange(Range)` | `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#` | Removes the specified range from the chart this builder modifies. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#setChartType(ChartType)` | `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#` | Changes the type of chart. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#setHiddenDimensionStrategy(ChartHiddenDimensionStrategy)` | `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#` | Sets the strategy to use for hidden rows and columns. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#setMergeStrategy(ChartMergeStrategy)` | `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#` | Sets the merge strategy to use when more than one range exists. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#setNumHeaders(Integer)` | `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#` | Sets the number of rows or columns of the range that should be treated as headers. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#setOption(String,Object)` | `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#` | Sets advanced options for this chart. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#setPosition(Integer,Integer,Integer,Integer)` | `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#` | Sets the position, changing where the chart appears on the sheet. |
| `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#setTransposeRowsAndColumns(Boolean)` | `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#` | Sets whether the chart's rows and columns are transposed. |

## Detailed documentation

### `addRange(range)`

Adds a range to the chart this builder modifies. Does not add the range if it has already been
added to the chart.

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

sheet.insertChart(chart);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `range` | `https://developers.google.com/apps-script/reference/spreadsheet/range` | The range to add. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#` --- This builder, for chaining.

*** ** * ** ***

### `asAreaChart()`

Sets the chart type to AreaChart and returns an `https://developers.google.com/apps-script/reference/spreadsheet/embedded-area-chart-builder`.

#### Return


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

*** ** * ** ***

### `asBarChart()`

Sets the chart type to BarChart and returns an `https://developers.google.com/apps-script/reference/spreadsheet/embedded-bar-chart-builder`.

#### Return


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

*** ** * ** ***

### `asColumnChart()`

Sets the chart type to ColumnChart and returns an `https://developers.google.com/apps-script/reference/spreadsheet/embedded-column-chart-builder`.

#### Return


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

*** ** * ** ***

### `asComboChart()`

Sets the chart type to ComboChart and returns an `https://developers.google.com/apps-script/reference/spreadsheet/embedded-combo-chart-builder`.

#### Return


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

*** ** * ** ***

### `asHistogramChart()`

Sets the chart type to HistogramChart and returns an `https://developers.google.com/apps-script/reference/spreadsheet/embedded-histogram-chart-builder`.

#### Return


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

*** ** * ** ***

### `asLineChart()`

Sets the chart type to LineChart and returns an `https://developers.google.com/apps-script/reference/spreadsheet/embedded-line-chart-builder`.

#### Return


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

*** ** * ** ***

### `asPieChart()`

Sets the chart type to PieChart and returns an `https://developers.google.com/apps-script/reference/spreadsheet/embedded-pie-chart-builder`.

#### Return


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

*** ** * ** ***

### `asScatterChart()`

Sets the chart type to ScatterChart and returns an `https://developers.google.com/apps-script/reference/spreadsheet/embedded-scatter-chart-builder`.

#### Return


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

*** ** * ** ***

### `asTableChart()`

Sets the chart type to TableChart and returns an `https://developers.google.com/apps-script/reference/spreadsheet/embedded-table-chart-builder`.

#### Return


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

*** ** * ** ***

### `build()`

Builds the chart to reflect all changes made to it.

This method does not automatically draw the chart on top of the spreadsheet. A new chart
must be inserted via `sheet.insertChart(chart)`, and an existing chart should be updated
via `sheet.updateChart(chart)`.

```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)
                  .setPosition(5, 5, 0, 0)
                  .build();

sheet.insertChart(chart);
```

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart` --- The created chart, which must still be added to the spreadsheet.

*** ** * ** ***

### `clearRanges()`

Removes all ranges from the chart this builder modifies.

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

// This code updates the chart to use only the new ranges while preserving the
// existing formatting of the chart.
const chart = sheet.getCharts()[0];
const newChart = chart.modify()
                     .clearRanges()
                     .addRange(sheet.getRange('A1:A5'))
                     .addRange(sheet.getRange('B1:B5'))
                     .build();
sheet.updateChart(newChart);
```

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#` --- This builder, for chaining.

*** ** * ** ***

### `getChartType()`

Returns the current chart type.

#### Return


`https://developers.google.com/apps-script/reference/charts/chart-type.html` --- The chart type.

*** ** * ** ***

### `getContainer()`

Return the chart `https://developers.google.com/apps-script/reference/spreadsheet/container-info`, which encapsulates where the chart appears on the
sheet.

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

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

// This method returns the exact same data as Chart#getContainerInfo()
const containerInfo = chartBuilder.getContainer();

// 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.

*** ** * ** ***

### `getRanges()`

Returns a copy of the list of ranges currently providing data for this chart. Use `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#addRange(Range)` and `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#removeRange(Range)` to modify this list.

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

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

const ranges = chartBuilder.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 the chart to be built's data source.

*** ** * ** ***

### `removeRange(range)`

Removes the specified range from the chart this builder modifies. Does not throw an error if
the range is not in this chart.

The range removed must match up with a range added via `https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#addRange(Range)`;
otherwise no change is made to the chart. This method cannot be used to partially remove values
from a range.

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

const firstRange = sheet.getRange('A1:B5');
const secondRange = sheet.getRange('A6:B8');

const chartBuilder = sheet.newChart()
                         .setChartType(Charts.ChartType.BAR)
                         .addRange(firstRange)
                         // This range renders in a different color
                         .addRange(secondRange)
                         .setPosition(5, 5, 0, 0);

// Note that you can use either of these two formats, but the range
// MUST match up with a range that was added via addRange(), or it
// is not removed, and does not throw an exception
chartBuilder.removeRange(firstRange);
chartBuilder.removeRange(sheet.getRange('A6:B8'));

const chart = chartBuilder.build();

sheet.insertChart(chart);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `range` | `https://developers.google.com/apps-script/reference/spreadsheet/range` | The range to remove. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#` --- This builder, for chaining.

*** ** * ** ***

### `setChartType(type)`

Changes the type of chart. Not all embedded chart types are currently supported. See `https://developers.google.com/apps-script/reference/charts/chart-type.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)
                  .setPosition(5, 5, 0, 0)
                  .build();

sheet.insertChart(chart);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `type` | `https://developers.google.com/apps-script/reference/charts/chart-type.html` | The type to change this chart into. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#` --- This builder, for chaining.

*** ** * ** ***

### `setHiddenDimensionStrategy(strategy)`

Sets the strategy to use for 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();

sheet.insertChart(chart);
```

#### Parameters

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

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#` --- This builder, for chaining.

*** ** * ** ***

### `setMergeStrategy(mergeStrategy)`

Sets the merge strategy to use when more than one range exists. If `https://developers.google.com/apps-script/reference/charts/chart-merge-strategy.html`, rows are merged; if `https://developers.google.com/apps-script/reference/charts/chart-merge-strategy.html`, columns are merged. Defaults to `https://developers.google.com/apps-script/reference/charts/chart-merge-strategy.html`.

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

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

sheet.insertChart(chart);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `mergeStrategy` | `https://developers.google.com/apps-script/reference/charts/chart-merge-strategy.html` | The merge strategy to use. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#` --- This builder, for chaining.

*** ** * ** ***

### `setNumHeaders(headers)`

Sets the number of rows or columns of the range that should be 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();

sheet.insertChart(chart);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `headers` | `Integer` | The number of rows or columns to treat as headers. Negative values cause headers to be auto-detected. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#` --- This builder, for chaining.

*** ** * ** ***

### `setOption(option, value)`

Sets advanced options for this chart. To view a list of the available options, see [Chart
configuration options](https://developers.google.com/apps-script/chart-configuration-options).

This method doesn't validate the option you specify is valid for this chart type nor if the
value is of the correct format/structure.

This example shows how to change the title and set a legend.

```javascript
const spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
const sheet = spreadsheet.getSheets()[0];
const chart = sheet.newChart()
 .setOption('title', 'Earnings projections')
 .setOption('legend', {
   position: 'top',
   textStyle: { color: 'blue', fontSize: 16 },
 }).build();
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `option` | `String` | The name of the option. |
| `value` | `Object` | The value of the option. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#` --- This builder, for chaining.

*** ** * ** ***

### `setPosition(anchorRowPos, anchorColPos, offsetX, offsetY)`

Sets the position, changing where the chart appears on the sheet. `anchorRowPos` and
`anchorColPos` are 1-indexed.

```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)
                  .setPosition(5, 5, 0, 0)
                  .build();

sheet.insertChart(chart);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `anchorRowPos` | `Integer` | The chart's top side is anchored in this row. |
| `anchorColPos` | `Integer` | The chart's left side is anchored in this column. |
| `offsetX` | `Integer` | The chart's upper right-hand corner is offset by this many pixels. |
| `offsetY` | `Integer` | The chart's lower left-hand corner is offset by this many pixels. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#` --- This builder, for chaining.

*** ** * ** ***

### `setTransposeRowsAndColumns(transpose)`

Sets whether the chart's rows and columns are transposed. If set to `true`, the rows and
columns 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()
                  .setChartType(Charts.ChartType.BAR)
                  .addRange(range)
                  .setTransposeRowsAndColumns(true)
                  .setPosition(5, 5, 0, 0)
                  .build();

sheet.insertChart(chart);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `transpose` | `Boolean` | If `true`, the rows and columns used to construct the chart are transposed. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/embedded-chart-builder#` --- This builder, for chaining.