Position

A reference to a location in the document tab, relative to a specific element. The user's cursor
is represented as a `Position`, among other uses. Scripts can only access the cursor of the
user who is running the script, and only if the script is [bound](https://developers.google.com/apps-script/scripts_containers) to the document.

```javascript
// Insert some text at the cursor position and make it bold.
const cursor = DocumentApp.getActiveDocument().getCursor();
if (cursor) {
  // Attempt to insert text at the cursor position. If the insertion returns
  // null, the cursor's containing element doesn't allow insertions, so show the
  // user an error message.
  const element = cursor.insertText('ಠ‿ಠ');
  if (element) {
    element.setBold(true);
  } else {
    DocumentApp.getUi().alert('Cannot insert text here.');
  }
} else {
  DocumentApp.getUi().alert('Cannot find a cursor.');
}
```

### Methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/document/position#getElement()` | `https://developers.google.com/apps-script/reference/document/element` | Gets the element that contains this `Position`. |
| `https://developers.google.com/apps-script/reference/document/position#getOffset()` | `Integer` | Gets this `Position`'s relative location within the element that contains it. |
| `https://developers.google.com/apps-script/reference/document/position#getSurroundingText()` | `https://developers.google.com/apps-script/reference/document/text` | Creates an artificial `https://developers.google.com/apps-script/reference/document/text` element that represents the text and formatting of the `https://developers.google.com/apps-script/reference/document/paragraph` or `https://developers.google.com/apps-script/reference/document/list-item` that contains the `Position`, either directly or through a chain of child elements. |
| `https://developers.google.com/apps-script/reference/document/position#getSurroundingTextOffset()` | `Integer` | Gets the offset of this `Position` within the `https://developers.google.com/apps-script/reference/document/text` element returned by `https://developers.google.com/apps-script/reference/document/position#getSurroundingText()`. |
| `https://developers.google.com/apps-script/reference/document/position#insertBookmark()` | `https://developers.google.com/apps-script/reference/document/bookmark` | Creates and inserts a new `https://developers.google.com/apps-script/reference/document/bookmark` at this `Position`. |
| `https://developers.google.com/apps-script/reference/document/position#insertInlineImage(BlobSource)` | `https://developers.google.com/apps-script/reference/document/inline-image|null` | Creates and inserts a new `https://developers.google.com/apps-script/reference/document/inline-image` at this `Position` from the specified image blob. |
| `https://developers.google.com/apps-script/reference/document/position#insertText(String)` | `https://developers.google.com/apps-script/reference/document/text|null` | Inserts the specified text at this `Position`. |

## Detailed documentation

### `getElement()`

Gets the element that contains this `Position`. This will be either a `https://developers.google.com/apps-script/reference/document/text`
element or a container element like `https://developers.google.com/apps-script/reference/document/paragraph`. In either case, the relative
position within the element can be determined with `https://developers.google.com/apps-script/reference/document/position#getOffset()`.

#### Return


`https://developers.google.com/apps-script/reference/document/element` --- the container or `https://developers.google.com/apps-script/reference/document/text` element in which this `Position` object is located

*** ** * ** ***

### `getOffset()`

Gets this `Position`'s relative location within the element that contains it. If the
element is a `https://developers.google.com/apps-script/reference/document/text` element, the offset is the number of characters before the `Position` (that is, the index of the character after this `Position`); for any other
element, the offset is the number of child elements before this `Position` within the
same container element (that is, the index of the child element after the `Position`).

#### Return


`Integer` --- for `https://developers.google.com/apps-script/reference/document/text` elements, the number of characters before this `Position`; for
other elements, the number of child elements before this `Position` within the same
container element

#### 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/documents.currentonly`
- `https://www.googleapis.com/auth/documents`

*** ** * ** ***

### `getSurroundingText()`

Creates an artificial `https://developers.google.com/apps-script/reference/document/text` element that represents the text and formatting of the
`https://developers.google.com/apps-script/reference/document/paragraph` or `https://developers.google.com/apps-script/reference/document/list-item` that contains the `Position`, either directly or through a chain of child elements. To determine the `Position`'s offset in the returned `Text` element, use `https://developers.google.com/apps-script/reference/document/position#getSurroundingTextOffset()`.

#### Return


`https://developers.google.com/apps-script/reference/document/text` --- an element equivalent to the result of calling `https://developers.google.com/apps-script/reference/document/paragraph#editAsText()`
on the `https://developers.google.com/apps-script/reference/document/paragraph` or `https://developers.google.com/apps-script/reference/document/list-item` that contains the `Position`, either directly or through a chain of child elements

#### 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/documents.currentonly`
- `https://www.googleapis.com/auth/documents`

*** ** * ** ***

### `getSurroundingTextOffset()`

Gets the offset of this `Position` within the `https://developers.google.com/apps-script/reference/document/text` element returned by `https://developers.google.com/apps-script/reference/document/position#getSurroundingText()`. The offset is the number of characters before the `Position`
(that is, the index of the character after this `Position`).

#### Return


`Integer` --- the number of characters before this `Position` in the `https://developers.google.com/apps-script/reference/document/paragraph` or `https://developers.google.com/apps-script/reference/document/list-item` that contains the `Position`, either directly or through a chain of child elements

#### 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/documents.currentonly`
- `https://www.googleapis.com/auth/documents`

*** ** * ** ***

### `insertBookmark()`

Creates and inserts a new `https://developers.google.com/apps-script/reference/document/bookmark` at this `Position`.

#### Return


`https://developers.google.com/apps-script/reference/document/bookmark` --- the new bookmark

#### 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/documents.currentonly`
- `https://www.googleapis.com/auth/documents`

*** ** * ** ***

### `insertInlineImage(image)`

Creates and inserts a new `https://developers.google.com/apps-script/reference/document/inline-image` at this `Position` from the specified image
blob.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `image` | `https://developers.google.com/apps-script/reference/base/blob-source.html` | the image data to insert at this `Position` |

#### Return


`https://developers.google.com/apps-script/reference/document/inline-image|null` --- the new image element, or `null` if the element in which this `Position` is
located does not allow images to be inserted

#### 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/documents.currentonly`
- `https://www.googleapis.com/auth/documents`

*** ** * ** ***

### `insertText(text)`

Inserts the specified text at this `Position`. This method creates a new `https://developers.google.com/apps-script/reference/document/text`
element, even if the string is inserted within an existing `Text` element, so that it is
easy to style the new element.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `text` | `String` | the string to insert at this `Position` |

#### Return


`https://developers.google.com/apps-script/reference/document/text|null` --- the new text element, or `null` if the element in which this `Position` is
located does not allow text to be inserted

#### 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/documents.currentonly`
- `https://www.googleapis.com/auth/documents`