aboutsummaryrefslogtreecommitdiff
path: root/ext/js/dom/text-source-element.js
diff options
context:
space:
mode:
authortoasted-nutbread <toasted-nutbread@users.noreply.github.com>2022-09-26 19:37:14 -0400
committerGitHub <noreply@github.com>2022-09-26 19:37:14 -0400
commitbe7855bad2e3b452ca0700246a376f107a75e79e (patch)
treedf73805af15c5bd98a370ccbded679125d98e46d /ext/js/dom/text-source-element.js
parent38c3d1b98c269739b7be3b3c8b33a58a65af5e52 (diff)
More API documentation (#2238)
* Document TextSourceRange * Document TextSourceElement * Document DocumentUtil * Document DocumentFocusController
Diffstat (limited to 'ext/js/dom/text-source-element.js')
-rw-r--r--ext/js/dom/text-source-element.js88
1 files changed, 88 insertions, 0 deletions
diff --git a/ext/js/dom/text-source-element.js b/ext/js/dom/text-source-element.js
index 13c5cd86..1c60a5b8 100644
--- a/ext/js/dom/text-source-element.js
+++ b/ext/js/dom/text-source-element.js
@@ -20,7 +20,18 @@
* StringUtil
*/
+/**
+ * This class represents a text source that is attached to a HTML element, such as an <img>
+ * with alt text or a <button>.
+ */
class TextSourceElement {
+ /**
+ * Creates a new instance of the class.
+ * @param {Element} element The source element.
+ * @param {string} fullContent The string representing the element's full text value.
+ * @param {number} startOffset The text start offset position within the full content.
+ * @param {number} endOffset The text end offset position within the full content.
+ */
constructor(element, fullContent, startOffset, endOffset) {
this._element = element;
this._fullContent = fullContent;
@@ -29,38 +40,76 @@ class TextSourceElement {
this._content = this._fullContent.substring(this._startOffset, this._endOffset);
}
+ /**
+ * Gets the type name of this instance.
+ * @type {string}
+ */
get type() {
return 'element';
}
+ /**
+ * The source element.
+ * @type {Element}
+ */
get element() {
return this._element;
}
+ /**
+ * The string representing the element's full text value.
+ * @type {string}
+ */
get fullContent() {
return this._fullContent;
}
+ /**
+ * The text start offset position within the full content.
+ * @type {number}
+ */
get startOffset() {
return this._startOffset;
}
+ /**
+ * The text end offset position within the full content.
+ * @type {number}
+ */
get endOffset() {
return this._endOffset;
}
+ /**
+ * Creates a clone of the instance.
+ * @returns {TextSourceElement} The new clone.
+ */
clone() {
return new TextSourceElement(this._element, this._fullContent, this._startOffset, this._endOffset);
}
+ /**
+ * Performs any cleanup that is necessary after the element has been used.
+ */
cleanup() {
// NOP
}
+ /**
+ * Gets the selected text of element, which is a substring of the full content
+ * starting at `startOffset` and ending at `endOffset`.
+ * @returns {string} The text content.
+ */
text() {
return this._content;
}
+ /**
+ * Moves the end offset of the text by a set amount of unicode codepoints.
+ * @param {number} length The maximum number of codepoints to move by.
+ * @param {boolean} fromEnd Whether to move the offset from the current end position (if `true`) or the start position (if `false`).
+ * @returns {number} The actual number of characters (not codepoints) that were read.
+ */
setEndOffset(length, fromEnd) {
const offset = fromEnd ? this._endOffset : this._startOffset;
length = Math.min(this._fullContent.length - offset, length);
@@ -72,6 +121,11 @@ class TextSourceElement {
return length;
}
+ /**
+ * Moves the start offset of the text by a set amount of unicode codepoints.
+ * @param {number} length The maximum number of codepoints to move by.
+ * @returns {number} The actual number of characters (not codepoints) that were read.
+ */
setStartOffset(length) {
length = Math.min(this._startOffset, length);
if (length > 0) {
@@ -82,22 +136,42 @@ class TextSourceElement {
return length;
}
+ /**
+ * Gets the rects that represent the position and bounds of the text source.
+ * @returns {DOMRect[]} The rects.
+ */
getRects() {
return DocumentUtil.convertMultipleRectZoomCoordinates(this._element.getClientRects(), this._element);
}
+ /**
+ * Gets writing mode that is used for this element.
+ * See: https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode.
+ * @returns {string} The rects.
+ */
getWritingMode() {
return 'horizontal-tb';
}
+ /**
+ * Selects the text source in the document.
+ */
select() {
// NOP
}
+ /**
+ * Deselects the text source in the document.
+ */
deselect() {
// NOP
}
+ /**
+ * Checks whether another text source has the same starting point.
+ * @param {TextSourceElement|TextSourceRange} other The other source to test.
+ * @returns {boolean} `true` if the starting points are equivalent, `false` otherwise.
+ */
hasSameStart(other) {
return (
typeof other === 'object' &&
@@ -109,14 +183,28 @@ class TextSourceElement {
);
}
+ /**
+ * Gets a list of the nodes in this text source's range.
+ * @returns {Node[]} The nodes in the range.
+ */
getNodesInRange() {
return [this._element];
}
+ /**
+ * Creates a new instance for a given element.
+ * @param {Element} element The source element.
+ * @returns {TextSourceElement} A new instance of the class corresponding to the element.
+ */
static create(element) {
return new TextSourceElement(element, this._getElementContent(element), 0, 0);
}
+ /**
+ * Gets the full content string for a given element.
+ * @param {Element} element The element to get the full content of.
+ * @returns {string} The content string.
+ */
static _getElementContent(element) {
let content;
switch (element.nodeName.toUpperCase()) {