Class Position

    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 to the document.

     // 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
    get Element()
    		Element Gets the element that contains this Position .
    get Offset()
    		Integer Gets this Position 's relative location within the element that contains it.
    get Surrounding Text()
    		Text Creates an artificial Text element that represents the text and formatting of the Paragraph or List Item that contains the Position , either directly or through a chain of child elements.
    get Surrounding Text Offset()
    		Integer Gets the offset of this Position within the Text element returned by get Surrounding Text() .
    insert Bookmark()
    		Bookmark Creates and inserts a new Bookmark at this Position .
    insert Inline Image(image)
    		Inline Image Creates and inserts a new Inline Image at this Position from the specified image blob.
    insert Text(text)
    		Text Inserts the specified text at this Position .

    Detailed documentation

    get Element()

    Gets the element that contains this Position . This will be either a Text element or a container element like Paragraph . In either case, the relative position within the element can be determined with get Offset() .

    Return

    Element — the container or Text element in which this Position object is located

    get Offset()

    Gets this Position 's relative location within the element that contains it. If the element is a 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 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://www.googleapis.com/auth/documents.currentonly
    • https://www.googleapis.com/auth/documents

    get Surrounding Text()

    Creates an artificial Text element that represents the text and formatting of the Paragraph or 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 get Surrounding Text Offset() .

    Return

    Text — an element equivalent to the result of calling edit As Text() on the Paragraph or 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://www.googleapis.com/auth/documents.currentonly
    • https://www.googleapis.com/auth/documents

    get Surrounding Text Offset()

    Gets the offset of this Position within the Text element returned by get Surrounding Text() . 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 Paragraph or 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://www.googleapis.com/auth/documents.currentonly
    • https://www.googleapis.com/auth/documents

    insert Bookmark()

    Creates and inserts a new Bookmark at this Position .

    Return

    Bookmark — the new bookmark

    Authorization

    Scripts that use this method require authorization with one or more of the following scopes :

    • https://www.googleapis.com/auth/documents.currentonly
    • https://www.googleapis.com/auth/documents

    insert Inline Image(image)

    Creates and inserts a new Inline Image at this Position from the specified image blob.

    Parameters

    Name Type Description
    image
    		Blob Source the image data to insert at this Position

    Return

    Inline Image — 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://www.googleapis.com/auth/documents.currentonly
    • https://www.googleapis.com/auth/documents

    insert Text(text)

    Inserts the specified text at this Position . This method creates a new 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

    Text — 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://www.googleapis.com/auth/documents.currentonly
    • https://www.googleapis.com/auth/documents
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: