CheckboxGridItem

A question item, presented as a grid of columns and rows, that allows the respondent to select
multiple choices per row from a sequence of checkboxes. Items can be accessed or created from a
`https://developers.google.com/apps-script/reference/forms/form`.

```javascript
// Open a form by ID and add a new checkbox grid item.
const form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz');
const item = form.addCheckboxGridItem();
item.setTitle('Where did you celebrate New Years?')
    .setRows(['New York', 'San Francisco', 'London'])
    .setColumns(['2014', '2015', '2016', '2017']);
```

### Methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#clearValidation()` | `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#` | Removes any data validation for this grid item. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#createResponse(String)` | `https://developers.google.com/apps-script/reference/forms/item-response` | Creates a new `https://developers.google.com/apps-script/reference/forms/item-response` for this checkbox grid item. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#duplicate()` | `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#` | Creates a copy of this item and appends it to the end of the form. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#getColumns()` | `String[]` | Gets the values for every column in the grid. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#getHelpText()` | `String` | Gets the item's help text (sometimes called description text for layout items like `https://developers.google.com/apps-script/reference/forms/image-item`, `https://developers.google.com/apps-script/reference/forms/page-break-item`, and `https://developers.google.com/apps-script/reference/forms/section-header-item`). |
| `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#getId()` | `Integer` | Gets the item's unique identifier. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#getIndex()` | `Integer` | Gets the index of the item among all the items in the form. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#getRows()` | `String[]` | Gets the values for every row in the grid. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#getTitle()` | `String` | Gets the item's title (sometimes called header text, in the case of a `https://developers.google.com/apps-script/reference/forms/section-header-item`). |
| `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#getType()` | `https://developers.google.com/apps-script/reference/forms/item-type` | Gets the item's type, represented as an `https://developers.google.com/apps-script/reference/forms/item-type`. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#isRequired()` | `Boolean` | Determines whether the respondent must answer the question. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#setColumns(String)` | `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#` | Sets the columns of the grid based on an array of values. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#setHelpText(String)` | `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#` | Sets the item's help text (sometimes called description text for layout items like `https://developers.google.com/apps-script/reference/forms/image-item`, `https://developers.google.com/apps-script/reference/forms/page-break-item`, and `https://developers.google.com/apps-script/reference/forms/section-header-item`). |
| `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#setRequired(Boolean)` | `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#` | Sets whether the respondent must answer the question. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#setRows(String)` | `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#` | Sets the rows of the grid based on an array of values. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#setTitle(String)` | `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#` | Sets the item's title (sometimes called header text, in the case of a `https://developers.google.com/apps-script/reference/forms/section-header-item`). |
| `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#setValidation(CheckboxGridValidation)` | `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#` | Sets the data validation for this checkbox grid item. |

## Detailed documentation

### `clearValidation()`

Removes any data validation for this grid item.

#### Return


`https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#` --- this item, for chaining

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `createResponse(responses)`

Creates a new `https://developers.google.com/apps-script/reference/forms/item-response` for this checkbox grid item. The argument `responses`
must be a `String[][]` array of arrays containing as many values as the number of inputs
in the checkbox grid. A `null` element for a non-required checkbox grid question
indicates no response to that row. Throws an exception if any of the values does not match a
valid choice.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `responses` | `String[][]` | an array of arrays of valid answers for this checkbox grid item |

#### Return


`https://developers.google.com/apps-script/reference/forms/item-response` --- the item response

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `duplicate()`

Creates a copy of this item and appends it to the end of the form.

#### Return


`https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#` --- a duplicate of this `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#`, for chaining

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `getColumns()`

Gets the values for every column in the grid.

#### Return


`String[]` --- an array of column values, which respondents see as labels when viewing the form

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `getHelpText()`

Gets the item's help text (sometimes called description text for layout items like `https://developers.google.com/apps-script/reference/forms/image-item`, `https://developers.google.com/apps-script/reference/forms/page-break-item`, and `https://developers.google.com/apps-script/reference/forms/section-header-item`).

#### Return


`String` --- the item's help text or description text

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `getId()`

Gets the item's unique identifier.

#### Return


`Integer` --- the item's ID

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `getIndex()`

Gets the index of the item among all the items in the form.

#### Return


`Integer` --- the index of the item

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `getRows()`

Gets the values for every row in the grid.

#### Return


`String[]` --- an array of row values, which respondents see as labels when viewing the form

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `getTitle()`

Gets the item's title (sometimes called header text, in the case of a `https://developers.google.com/apps-script/reference/forms/section-header-item`).

#### Return


`String` --- the item's title or header text

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `getType()`

Gets the item's type, represented as an `https://developers.google.com/apps-script/reference/forms/item-type`.

#### Return


`https://developers.google.com/apps-script/reference/forms/item-type` --- the item's type

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `isRequired()`

Determines whether the respondent must answer the question.

#### Return


`Boolean` --- whether the respondent must answer the question

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `setColumns(columns)`

Sets the columns of the grid based on an array of values. Throws an exception if the given
array is empty.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `columns` | `String[]` | an array of column values, which respondents see as labels when viewing the form |

#### Return


`https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#` --- this item, for chaining

#### Throws


[`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) --- if the given array is `null` or empty

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `setHelpText(text)`

Sets the item's help text (sometimes called description text for layout items like `https://developers.google.com/apps-script/reference/forms/image-item`, `https://developers.google.com/apps-script/reference/forms/page-break-item`, and `https://developers.google.com/apps-script/reference/forms/section-header-item`).

#### Parameters

| Name | Type | Description |
|---|---|---|
| `text` | `String` | the new help text |

#### Return


`https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#` --- this `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#`, for chaining

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `setRequired(enabled)`

Sets whether the respondent must answer the question.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `enabled` | `Boolean` | whether the respondent must answer the question |

#### Return


`https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#` --- the current item (for chaining)

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `setRows(rows)`

Sets the rows of the grid based on an array of values. Throws an exception if the given array
is empty.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `rows` | `String[]` | an array of row values, which respondents see as labels when viewing the form |

#### Return


`https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#` --- this item, for chaining

#### Throws


[`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) --- if the given array is `null` or empty

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `setTitle(title)`

Sets the item's title (sometimes called header text, in the case of a `https://developers.google.com/apps-script/reference/forms/section-header-item`).

#### Parameters

| Name | Type | Description |
|---|---|---|
| `title` | `String` | the new title or header text |

#### Return


`https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#` --- this `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#`, for chaining

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `setValidation(validation)`

Sets the data validation for this checkbox grid item. Passing in null or a validation without
any require functions called will remove any prior validation.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `validation` | `https://developers.google.com/apps-script/reference/forms/checkbox-grid-validation` | a CheckboxGridValidation to apply to this item. |

#### Return


`https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#` --- this `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item#`, for chaining

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`