FilterCriteria

Use this class to get information about or copy the criteria on existing filters.

- To create a new filter, refer to the following:
  - For sheets, use `https://developers.google.com/apps-script/reference/spreadsheet/range#createFilter()`.
  - For pivot tables, use `https://developers.google.com/apps-script/reference/spreadsheet/pivot-table#addFilter(Integer,FilterCriteria)`.
  - For sheets that are connected to a database, use `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#addFilter(String,FilterCriteria)`.
  - For pivot tables that are connected to a database, use `https://developers.google.com/apps-script/reference/spreadsheet/data-source-pivot-table#addFilter(String,FilterCriteria)`.
- To create the criteria for any type of filter, refer to `https://developers.google.com/apps-script/reference/spreadsheet/spreadsheet-app#newFilterCriteria()` and `https://developers.google.com/apps-script/reference/spreadsheet/filter-criteria-builder`.

### Common uses

#### Copy criteria

The following sample gets the filter that applies to the range `A1:C20`, gets the criteria applied to column C, and copies the criteria to column B.

```javascript
const ss = SpreadsheetApp.getActiveSheet();
const range = ss.getRange('A1:C20');
// Copies the filter criteria applied to column C.
const filter = range.getFilter();
const criteria = filter.getColumnFilterCriteria(3).copy().build();
// Applies the copied criteria to column B. The copied criteria overwrites any
// existing criteria on column B.
filter.setColumnFilterCriteria(2, criteria);
```

#### Get values hidden by the filter

The following sample gets the filter that applies to the given range and logs the values from column B that the filter hides.

```javascript
const ss = SpreadsheetApp.getActiveSheet();
const range = ss.getRange('A1:C20');
const filter = range.getFilter();
// Gets the filter criteria applied to column B, then gets the hidden values.
const filterCriteria = filter.getColumnFilterCriteria(2).getHiddenValues();
// Logs the hidden values.
console.log(filterCriteria);
```

### Methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/spreadsheet/filter-criteria#copy()` | `https://developers.google.com/apps-script/reference/spreadsheet/filter-criteria-builder` | Copies this filter criteria and creates a criteria builder that you can apply to another filter. |
| `https://developers.google.com/apps-script/reference/spreadsheet/filter-criteria#getCriteriaType()` | `https://developers.google.com/apps-script/reference/spreadsheet/boolean-criteria|null` | Returns the criteria's boolean type, for example, `CELL_EMPTY`. |
| `https://developers.google.com/apps-script/reference/spreadsheet/filter-criteria#getCriteriaValues()` | `Object[]` | Returns an array of arguments for boolean criteria. |
| `https://developers.google.com/apps-script/reference/spreadsheet/filter-criteria#getHiddenValues()` | `String[]` | Returns the values that the filter hides. |
| `https://developers.google.com/apps-script/reference/spreadsheet/filter-criteria#getVisibleBackgroundColor()` | `https://developers.google.com/apps-script/reference/spreadsheet/color|null` | Returns the background color used as filter criteria. |
| `https://developers.google.com/apps-script/reference/spreadsheet/filter-criteria#getVisibleForegroundColor()` | `https://developers.google.com/apps-script/reference/spreadsheet/color|null` | Returns the foreground color used as a filter criteria. |
| `https://developers.google.com/apps-script/reference/spreadsheet/filter-criteria#getVisibleValues()` | `String[]` | Returns the values that the pivot table filter shows. |

## Detailed documentation

### `copy()`

Copies this filter criteria and creates a criteria builder that you can apply to another
filter.

You can use this method with any type of filter. If you're using a sheet filter, you can
copy the criteria to another column.

```javascript
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Makes a copy of the filter criteria applied to column C.
const criteria = filter.getColumnFilterCriteria(3).copy().build();
// Applies the copied criteria to column B. The copied criteria overwrites any
// existing criteria on column B.
filter.setColumnFilterCriteria(2, criteria);
```

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/filter-criteria-builder` --- A filter criteria builder based on this filter criteria.

*** ** * ** ***

### `getCriteriaType()`

Returns the criteria's boolean type, for example, `CELL_EMPTY`. To learn about the types
of boolean criteria, see the `https://developers.google.com/apps-script/reference/spreadsheet/boolean-criteria` enum.

People often use this method to add boolean condition criteria to a filter without replacing
existing criteria.

- To get the arguments for the criteria, use `https://developers.google.com/apps-script/reference/spreadsheet/filter-criteria#getCriteriaValues()`.
- To use the criteria type and criteria values to create or modify filter criteria, see `https://developers.google.com/apps-script/reference/spreadsheet/filter-criteria-builder#withCriteria(BooleanCriteria,Object)`.

You can use this method for any type of filter. If the filter criteria isn't a boolean
condition, returns `null`.

```javascript
const ss = SpreadsheetApp.getActiveSheet();
// Gets the filter on the active sheet.
const filter = ss.getFilter();
// Gets the criteria type and returns a string representing the criteria type
// object.
const criteriaType =
    filter.getColumnFilterCriteria(2).getCriteriaType().toString();
// Logs the criteria type.
console.log(criteriaType);
```

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/boolean-criteria|null` --- The type of boolean criteria, or `null` if the criteria isn't a boolean
condition.

*** ** * ** ***

### `getCriteriaValues()`

Returns an array of arguments for boolean criteria. Some boolean criteria types don't have
arguments and return an empty array, for example, `CELL_NOT_EMPTY`.

People often use this method to add boolean condition criteria to a filter without replacing
existing criteria.

- To get the boolean criteria type, use `https://developers.google.com/apps-script/reference/spreadsheet/filter-criteria#getCriteriaType()`.
- To use the criteria type and criteria values to create or modify a filter criteria, see `https://developers.google.com/apps-script/reference/spreadsheet/filter-criteria-builder#withCriteria(BooleanCriteria,Object)`.

  You can use this method for any type of filter.

  ```javascript
  const ss = SpreadsheetApp.getActiveSheet();
  const filter = ss.getFilter();
  // Gets the values of the boolean criteria and logs them. For example, if the
  // boolean condition is whenNumberGreaterThan(10), then the logged value is 10.
  const criteriaValues = filter.getColumnFilterCriteria(2).getCriteriaValues();
  console.log(criteriaValues);
  ```

  #### Return


  `Object[]` --- An array of arguments appropriate to the boolean criteria type. The number of arguments
  and their type match the corresponding `when...()` method of the `https://developers.google.com/apps-script/reference/spreadsheet/filter-criteria-builder` class.

*** ** * ** ***

### `getHiddenValues()`

Returns the values that the filter hides.

Use this criteria with filters on `https://developers.google.com/apps-script/reference/spreadsheet/sheet-type` sheets, the default type of sheet.
Returns `null` if you call this method for other types of filters.

```javascript
const ss = SpreadsheetApp.getActiveSheet();
const range = ss.getRange('A1:C20');
const filter = range.getFilter();
// Gets the filter criteria applied to column B, then gets the hidden values.
const filterCriteria = filter.getColumnFilterCriteria(2).getHiddenValues();
// Logs the hidden values.
console.log(filterCriteria);
```

#### Return


`String[]` --- An array of values that the filter hides.

*** ** * ** ***

### `getVisibleBackgroundColor()`

Returns the background color used as filter criteria. Cells with this background color remain
visible.

Use this criteria with filters on `https://developers.google.com/apps-script/reference/spreadsheet/sheet-type` sheets, the default type of sheet.
Returns `null` if you call this method for other types of filters.

```javascript
const ss = SpreadsheetApp.getActiveSheet();
const range = ss.getRange('A1:C20');
// Logs the background color that column B is filtered by as a hexadecimal
// string.
const filter = range.getFilter();
const color = filter.getColumnFilterCriteria(2)
                  .getVisibleBackgroundColor()
                  .asRgbColor()
                  .asHexString();
console.log(color);
```

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/color|null` --- The background color used as filter criteria.

*** ** * ** ***

### `getVisibleForegroundColor()`

Returns the foreground color used as a filter criteria. Cells with this foreground color remain
visible.

Use this criteria with filters on `https://developers.google.com/apps-script/reference/spreadsheet/sheet-type` sheets, the default type of sheet.
Returns `null` if you call this method for other types of filters.

```javascript
const ss = SpreadsheetApp.getActiveSheet();
const range = ss.getRange('A1:C20');
// Logs the foreground color that column B is filtered by as a hexadecimal
// string.
const filter = range.getFilter();
const color = filter.getColumnFilterCriteria(2)
                  .getVisibleForegroundColor()
                  .asRgbColor()
                  .asHexString();
console.log(color);
```

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/color|null` --- The foreground color used as a filter criteria.

*** ** * ** ***

### `getVisibleValues()`

Returns the values that the pivot table filter shows.

This criteria is only for filters on pivot tables that aren't connected to a database.
Returns an empty array for other types of filters.

```javascript
const ss = SpreadsheetApp.getActiveSheet();
// Gets the first pivot table on the sheet, then gets the visible values of its
// first filter.
const pivotTable = ss.getPivotTables()[0];
const pivotFilterValues =
    pivotTable.getFilters()[0].getFilterCriteria().getVisibleValues();
// Logs the visible values.
console.log(pivotFilterValues);
```

#### Return


`String[]` --- An array of values that the pivot table filter shows.