Class TextRange

TextRange

A segment of the text contents of a Shape or a TableCell.

Methods

MethodReturn typeBrief description
appendParagraph(text)ParagraphAppends a paragraph at the end of the text range.
appendText(text)TextRangeAppends text at the end of the text range.
asRenderedString()StringReturns the rendered text bounded by this range of the associated shape or table cell in a format appropriate to display to end users.
asString()StringReturns the raw text bounded by this range of the associated shape or table cell.
clear()voidClears the text bounded by this range.
clear(startOffset, endOffset)voidClears the text bounded by the start and end offsets in the range.
find(pattern)TextRange[]Returns all the ranges matching the search pattern in the current text range.
find(pattern, startOffset)TextRange[]Returns all the ranges matching the search pattern in the current text range starting from the start offset.
getAutoTexts()AutoText[]Returns the auto texts within the current text range.
getEndIndex()IntegerReturns the exclusive, 0-based index for the last character in this range.
getLength()IntegerReturns the number of characters in this range.
getLinks()TextRange[]Returns a collection of text ranges that correspond to all Links within the current text range or overlapping the current text range.
getListParagraphs()Paragraph[]Returns the paragraphs in lists that overlap the current text range.
getListStyle()ListStyleReturns the ListStyle of the current text range.
getParagraphStyle()ParagraphStyleReturns the ParagraphStyle of the current text range.
getParagraphs()Paragraph[]Returns the paragraphs that overlap the current text range.
getRange(startOffset, endOffset)TextRangeReturns a new TextRange covering part of the range from which it is derived.
getRuns()TextRange[]Returns the text runs that overlap the current text range.
getStartIndex()IntegerReturns the inclusive, 0-based index for the first character in this range.
getTextStyle()TextStyleReturns the text style of the range, or null if the range is empty.
insertParagraph(startOffset, text)ParagraphInserts a paragraph at the start offset.
insertText(startOffset, text)TextRangeInserts text at the start offset.
isEmpty()BooleanReturns true if there are no characters in this range, and returns false otherwise.
replaceAllText(findText, replaceText)IntegerReplaces all instances of text matching find text with replace text.
replaceAllText(findText, replaceText, matchCase)IntegerReplaces all instances of text matching find text with replace text.
select()voidSelects only the TextRange in the active presentation and removes any previous selection.
setText(newText)TextRangeSets the text bounded by this range of the associated shape or table cell.

Detailed documentation

appendParagraph(text)

Appends a paragraph at the end of the text range. The paragraph maintains the styling of the end of the current text range.

The provided text string is appended as a paragraph by adding at least one surrounding newline character to the string.

When the provided text string contains newline characters (thus consisting of multiple paragraphs), the final paragraph added is returned.

Parameters

NameTypeDescription
textStringThe string to append as a paragraph.

Return

Paragraph — the appended Paragraph.


appendText(text)

Appends text at the end of the text range. The text maintains the styling of the end of the existing text.

Parameters

NameTypeDescription
textStringThe string to append.

Return

TextRange — the text range representing the appended text.


asRenderedString()

Returns the rendered text bounded by this range of the associated shape or table cell in a format appropriate to display to end users.

AutoText elements, such as generated slide numbers, are replaced with their rendered values. Any non-text elements in the range are omitted.

Return

String


asString()

Returns the raw text bounded by this range of the associated shape or table cell.

AutoText elements such as generated slide numbers and any non-text elements in the range are replaced with the Unicode character U+E907.

Return

String


clear()

Clears the text bounded by this range.

Since the entire text in a Shape or TableCell must end in a newline, the final newline in the text is not removed.


clear(startOffset, endOffset)

Clears the text bounded by the start and end offsets in the range.

Since the text must end in a newline, the final newline in text is not removed even if it's covered by the given offsets.

Parameters

NameTypeDescription
startOffsetIntegerThe number of characters past the start index of the current text range used to determine the inclusive start index of the range to clear. The start offset must be equal to or greater than 0 and less than or equal to endOffset. startOffset must also be less than the length of the current range.
endOffsetIntegerThe number of characters past the start index of the current text range used to determine the exclusive end index of the range to clear. The endOffset must be equal to or greater than startOffset. endOffset must also be less than or equal to the length of the current range.

find(pattern)

Returns all the ranges matching the search pattern in the current text range. The search is case sensitive.

Parameters

NameTypeDescription
patternStringThe regular expression pattern to search; any backslashes in the pattern should be escaped.

Return

TextRange[]


find(pattern, startOffset)

Returns all the ranges matching the search pattern in the current text range starting from the start offset. The search is case sensitive.

Parameters

NameTypeDescription
patternStringThe regular expression pattern to search; any backslashes in the pattern should be escaped.
startOffsetIntegerThe number of characters past the start index of the current text range used to determine the inclusive start index of the range to search. startOffset must also be less than the length of the current range.

Return

TextRange[]


getAutoTexts()

Returns the auto texts within the current text range.

Return

AutoText[]


getEndIndex()

Returns the exclusive, 0-based index for the last character in this range. If the start and end indices are equal, the range is considered to be empty.

Return

Integer


getLength()

Returns the number of characters in this range.

Return

Integer


getLinks()

Returns a collection of text ranges that correspond to all Links within the current text range or overlapping the current text range.

Each returned range is guaranteed to span one link when it is created. Text modifications can cause it to no longer represent exactly one link.

Each Link on the returned ranges can be accessed via TextStyle.getLink().

 // Accesses the first link on a TextRange object.
 var linkTextRange = textRange.getLinks()[0];
 var textStyle = textRange.getTextStyle();
 Logger.log(textStyle.hasLink()); // logs 'true'
 var link = textStyle.getLink();  // Link object
 

Return

TextRange[]


getListParagraphs()

Returns the paragraphs in lists that overlap the current text range.

Return

Paragraph[]


getListStyle()

Returns the ListStyle of the current text range.

Return

ListStyle


getParagraphStyle()

Returns the ParagraphStyle of the current text range.

Return

ParagraphStyle


getParagraphs()

Returns the paragraphs that overlap the current text range.

Return

Paragraph[]


getRange(startOffset, endOffset)

Returns a new TextRange covering part of the range from which it is derived.

Parameters

NameTypeDescription
startOffsetIntegerThe number of characters past the start index of the current text range used to determine the inclusive start index of the returned range. The start offset must be equal to or greater than 0 and less than or equal to endOffset. startOffset must also be less than the length of the current range.
endOffsetIntegerThe number of characters past the start index of the current text range used to determine the exclusive end index of the returned range. The endOffset must be equal to or greater than startOffset. endOffset must also be less than or equal to the length of the current range.

Return

TextRange


getRuns()

Returns the text runs that overlap the current text range. A text run is a segment of text where all the characters have the same text style.

Each returned range is only guaranteed to span one run when it is created. Text or style modifications can cause it to no longer represent exactly one run.

Return

TextRange[]


getStartIndex()

Returns the inclusive, 0-based index for the first character in this range. If the start and end indices are equal, the range is considered to be empty.

Return

Integer


getTextStyle()

Returns the text style of the range, or null if the range is empty.

Return

TextStyle


insertParagraph(startOffset, text)

Inserts a paragraph at the start offset. The paragraph maintains the styling of the current text range at the start offset.

The provided text string is inserted as a paragraph by adding at least one surrounding newline character to the string.

When the provided text string contains newline characters (thus consisting of multiple paragraphs), the final paragraph added is returned.

Parameters

NameTypeDescription
startOffsetIntegerThe number of characters past the start index of the current text range used to determine the inclusive start index of the text to insert.
textStringThe string to insert.

Return

Paragraph — the inserted Paragraph.


insertText(startOffset, text)

Inserts text at the start offset. The text maintains the styling of the existing text at the start offset.

Parameters

NameTypeDescription
startOffsetIntegerThe number of characters past the start index of the current text range used to determine the inclusive start index of the text to insert.
textStringThe string to insert.

Return

TextRange — the text range representing the inserted text.


isEmpty()

Returns true if there are no characters in this range, and returns false otherwise.

Return

Boolean


replaceAllText(findText, replaceText)

Replaces all instances of text matching find text with replace text. The search is case insensitive.

Parameters

NameTypeDescription
findTextStringThe text to find.
replaceTextStringThe text to replace the matched text.

Return

Integer — the number of occurrences changed


replaceAllText(findText, replaceText, matchCase)

Replaces all instances of text matching find text with replace text.

Parameters

NameTypeDescription
findTextStringThe text to find.
replaceTextStringThe text to replace the matched text.
matchCaseBooleanIf true, the search is case sensitive; if false, the search is case insensitive.

Return

Integer — the number of occurrences changed


select()

Selects only the TextRange in the active presentation and removes any previous selection.

A script can only access the selection of the user who is running the script, and only if the script is bound to the presentation.

The parent Page of the corresponding Shape or the TableCell is set as the current page selection. The Shape or the TableCell is set as the selected page element.

    The Selection can be of two types:
    • 1. Range of text, use select on a non-empty TextRange to select the range of the characters.
    • 2. Cursor position, use an empty TextRange to place the cursor at the desired index.
       var shape = SlidesApp.getActivePresentation().getSlides()[0].getShapes()[0];
       shape.getText().setText("Hello");
       // Range selection: Select the text range "He".
       shape.getText().getRange(0, 2).select();
       // Cursor selection: Place the cursor after "H" like "H|ello".
       shape.getText().getRange(1, 1).select();
       

    setText(newText)

    Sets the text bounded by this range of the associated shape or table cell. The text maintains the styling of the start of the existing text.

    Parameters

    NameTypeDescription
    newTextStringThe string to set as the new text.

    Return

    TextRange — the text range representing the set text

    Send feedback about...

    Apps Script
    Apps Script