An element representing a function in a mathematical Equation
. An
EquationFunction
may contain EquationFunction
,
EquationFunctionArgumentSeparator
, EquationSymbol
, and Text
elements. For
more information on document structure, see the
guide to extending Google Docs.
Methods
Method | Return type | Brief description |
---|---|---|
clear() | EquationFunction | Clears the contents of the element. |
copy() | EquationFunction | Returns a detached, deep copy of the current element. |
editAsText() | Text | Obtains a Text version of the current element, for editing. |
findElement(elementType) | RangeElement | Searches the contents of the element for a descendant of the specified type. |
findElement(elementType, from) | RangeElement | Searches the contents of the element for a descendant of the specified
type, starting from the specified RangeElement . |
findText(searchPattern) | RangeElement | Searches the contents of the element for the specified text pattern using regular expressions. |
findText(searchPattern, from) | RangeElement | Searches the contents of the element for the specified text pattern, starting from a given search result. |
getAttributes() | Object | Retrieves the element's attributes. |
getChild(childIndex) | Element | Retrieves the child element at the specified child index. |
getChildIndex(child) | Integer | Retrieves the child index for the specified child element. |
getCode() | String | Retrieves the code corresponding to the equation function. |
getLinkUrl() | String | Retrieves the link url. |
getNextSibling() | Element | Retrieves the element's next sibling element. |
getNumChildren() | Integer | Retrieves the number of children. |
getParent() | ContainerElement | Retrieves the element's parent element. |
getPreviousSibling() | Element | Retrieves the element's previous sibling element. |
getText() | String | Retrieves the contents of the element as a text string. |
getTextAlignment() | TextAlignment | Gets the text alignment. |
getType() | ElementType | Retrieves the element's ElementType . |
isAtDocumentEnd() | Boolean | Determines whether the element is at the end of the
Document . |
merge() | EquationFunction | Merges the element with the preceding sibling of the same type. |
removeFromParent() | EquationFunction | Removes the element from its parent. |
replaceText(searchPattern, replacement) | Element | Replaces all occurrences of a given text pattern with a given replacement string, using regular expressions. |
setAttributes(attributes) | EquationFunction | Sets the element's attributes. |
setLinkUrl(url) | EquationFunction | Sets the link url. |
setTextAlignment(textAlignment) | EquationFunction | Sets the text alignment. |
Detailed documentation
copy()
Returns a detached, deep copy of the current element.
Any child elements present in the element are also copied. The new element will not have a parent.
Return
EquationFunction
— the new copy
editAsText()
Obtains a Text
version of the current element, for editing.
Use editAsText
for manipulating the elements contents as rich
text. The editAsText
mode ignores non-text elements (such as
InlineImage
and HorizontalRule
).
Child elements fully contained within a deleted text range are removed from the element.
var body = DocumentApp.getActiveDocument().getBody();
// Insert two paragraphs separated by a paragraph containing an
// horizontal rule.
body.insertParagraph(0, "An editAsText sample.");
body.insertHorizontalRule(0);
body.insertParagraph(0, "An example.");
// Delete " sample.\n\n An" removing the horizontal rule in the process.
body.editAsText().deleteText(14, 25);
Return
Text
— a text version of the current element
findElement(elementType)
Searches the contents of the element for a descendant of the specified type.
Parameters
Name | Type | Description |
---|---|---|
elementType | ElementType | the type of element to search for |
Return
RangeElement
— a search result indicating the position of the search element
findElement(elementType, from)
Searches the contents of the element for a descendant of the specified
type, starting from the specified RangeElement
.
// Get the body section of the active document.
var body = DocumentApp.getActiveDocument().getBody();
// Define the search parameters.
var searchType = DocumentApp.ElementType.PARAGRAPH;
var searchHeading = DocumentApp.ParagraphHeading.HEADING1;
var searchResult = null;
// Search until the paragraph is found.
while (searchResult = body.findElement(searchType, searchResult)) {
var par = searchResult.getElement().asParagraph();
if (par.getHeading() == searchHeading) {
// Found one, update and stop.
par.setText('This is the first header.');
return;
}
}
Parameters
Name | Type | Description |
---|---|---|
elementType | ElementType | the type of element to search for |
from | RangeElement | the search result to search from |
Return
RangeElement
— a search result indicating the next position of the search element
findText(searchPattern)
Searches the contents of the element for the specified text pattern using regular expressions.
A subset of the JavaScript regular expression features are not fully supported, such as capture groups and mode modifiers.
The provided regular expression pattern is independently matched against each text block contained in the current element.
Parameters
Name | Type | Description |
---|---|---|
searchPattern | String | the pattern to search for |
Return
RangeElement
— a search result indicating the position of the search text, or null
if there is no match
findText(searchPattern, from)
Searches the contents of the element for the specified text pattern, starting from a given search result.
A subset of the JavaScript regular expression features are not fully supported, such as capture groups and mode modifiers.
The provided regular expression pattern is independently matched against each text block contained in the current element.
Parameters
Name | Type | Description |
---|---|---|
searchPattern | String | the pattern to search for |
from | RangeElement | the search result to search from |
Return
RangeElement
— a search result indicating the next position of the search text, or
null if there is no match
getAttributes()
Retrieves the element's attributes.
The result is an object containing a property for each valid element
attribute where each property name corresponds to an item in the
DocumentApp.Attribute
enumeration.
var body = DocumentApp.getActiveDocument().getBody();
// Append a styled paragraph.
var par = body.appendParagraph('A bold, italicized paragraph.');
par.setBold(true);
par.setItalic(true);
// Retrieve the paragraph's attributes.
var atts = par.getAttributes();
// Log the paragraph attributes.
for (var att in atts) {
Logger.log(att + ":" + atts[att]);
}
Return
Object
— the element's attributes
getChild(childIndex)
Retrieves the child element at the specified child index.
// Get the body section of the active document.
var body = DocumentApp.getActiveDocument().getBody();
// Obtain the first element in the document.
var firstChild = body.getChild(0);
// If it's a paragraph, set its contents.
if (firstChild.getType() == DocumentApp.ElementType.PARAGRAPH) {
firstChild.asParagraph().setText("This is the first paragraph.");
}
Parameters
Name | Type | Description |
---|---|---|
childIndex | Integer | the index of the child element to retrieve |
Return
Element
— the child element at the specified index
getChildIndex(child)
Retrieves the child index for the specified child element.
Parameters
Name | Type | Description |
---|---|---|
child | Element | the child element for which to retrieve the index |
Return
Integer
— the child index
getCode()
Retrieves the code corresponding to the equation function.
Return
String
— the function code
getLinkUrl()
Retrieves the link url.
Return
String
— the link url, or null if the element contains multiple values
for this attribute
getNextSibling()
Retrieves the element's next sibling element.
The next sibling has the same parent and follows the current element.
Return
Element
— the next sibling element
getNumChildren()
Retrieves the number of children.
// Get the body section of the active document.
var body = DocumentApp.getActiveDocument().getBody();
// Log the number of elements in the document.
Logger.log("There are " + body.getNumChildren() +
" elements in the document body.");
Return
Integer
— the number of children
getParent()
Retrieves the element's parent element.
The parent element contains the current element.
Return
ContainerElement
— the parent element
getPreviousSibling()
Retrieves the element's previous sibling element.
The previous sibling has the same parent and precedes the current element.
Return
Element
— the previous sibling element
getText()
Retrieves the contents of the element as a text string.
Return
String
— the contents of the element as text string
getTextAlignment()
Gets the text alignment. The available types of alignment are
DocumentApp.TextAlignment.NORMAL
, DocumentApp.TextAlignment.SUBSCRIPT
, and
DocumentApp.TextAlignment.SUPERSCRIPT
.
Return
TextAlignment
— the type of text alignment, or null
if the text contains multiple types of
text alignments or if the text alignment has never been set
getType()
Retrieves the element's ElementType
.
Use getType()
to determine the exact type of a given element.
var body = DocumentApp.getActiveDocument().getBody();
// Obtain the first element in the document body.
var firstChild = body.getChild(0);
// Use getType() to determine the element's type.
if (firstChild.getType() == DocumentApp.ElementType.PARAGRAPH) {
Logger.log('The first element is a paragraph.');
} else {
Logger.log('The first element is not a paragraph.');
}
Return
ElementType
— the element type
isAtDocumentEnd()
Determines whether the element is at the end of the
Document
.
Return
Boolean
— whether the element is at the end of the document
merge()
Merges the element with the preceding sibling of the same type.
Only elements of the same ElementType
may be merged. Any
child elements contained in the current element are moved to the preceding
sibling element.
The current element is removed from the document.
var body = DocumentApp.getActiveDocument().getBody();
// Append two paragraphs to the document.
var par1 = body.appendParagraph('Paragraph 1.');
var par2 = body.appendParagraph('Paragraph 2.');
// Merge the newly added paragraphs into a single paragraph.
par2.merge();
Return
EquationFunction
— the merged element
removeFromParent()
Removes the element from its parent.
var body = DocumentApp.getActiveDocument().getBody();
// Remove all images in the document body.
var imgs = body.getImages();
for (var i = 0; i < imgs.length; i++) {
imgs[i].removeFromParent();
}
Return
EquationFunction
— the removed element
replaceText(searchPattern, replacement)
Replaces all occurrences of a given text pattern with a given replacement string, using regular expressions.
A subset of the JavaScript regular expression features are not fully supported, such as capture groups and mode modifiers.
The provided regular expression pattern is independently matched against each text block contained in the current element.
var body = DocumentApp.getActiveDocument().getBody();
// Clear the text surrounding "Apps Script", with or without text.
body.replaceText("^.*Apps ?Script.*$", "Apps Script");
Parameters
Name | Type | Description |
---|---|---|
searchPattern | String | the regex pattern to search for |
replacement | String | the text to use as replacement |
Return
Element
— the current element
setAttributes(attributes)
Sets the element's attributes.
The specified attributes parameter must be an object where each
property name is an item in the DocumentApp.Attribute
enumeration
and each property value is the new value to be applied.
var body = DocumentApp.getActiveDocument().getBody();
// Define a custom paragraph style.
var style = {};
style[DocumentApp.Attribute.HORIZONTAL_ALIGNMENT] =
DocumentApp.HorizontalAlignment.RIGHT;
style[DocumentApp.Attribute.FONT_FAMILY] =
DocumentApp.FontFamily.CALIBRI;
style[DocumentApp.Attribute.FONT_SIZE] = 18;
style[DocumentApp.Attribute.BOLD] = true;
// Append a plain paragraph.
var par = body.appendParagraph('A paragraph with custom style.');
// Apply the custom style.
par.setAttributes(style);
Parameters
Name | Type | Description |
---|---|---|
attributes | Object | the element's attributes |
Return
EquationFunction
— the current element
setLinkUrl(url)
Sets the link url.
Parameters
Name | Type | Description |
---|---|---|
url | String | the link url |
Return
EquationFunction
— the current element
setTextAlignment(textAlignment)
Sets the text alignment. The available types of alignment are
DocumentApp.TextAlignment.NORMAL
, DocumentApp.TextAlignment.SUBSCRIPT
, and
DocumentApp.TextAlignment.SUPERSCRIPT
.
// Make the entire first paragraph be superscript.
var text = DocumentApp.getActiveDocument().getBody().getParagraphs()[0].editAsText();
text.setTextAlignment(DocumentApp.TextAlignment.SUPERSCRIPT);
Parameters
Name | Type | Description |
---|---|---|
textAlignment | TextAlignment | the type of text alignment to apply |
Return
EquationFunction
— the current element