Class core.PositionIterator
Defined in: PositionIterator.js.
| Constructor Attributes | Constructor Name and Description |
|---|---|
|
core.PositionIterator(root, whatToShow, filter, expandEntityReferences)
An iterator that iterators through positions in a DOM tree.
|
| Field Attributes | Field Name and Description |
|---|---|
|
This function exposes class internals and should be avoided.
|
| Method Attributes | Method Name and Description |
|---|---|
|
Return the container for the current position.
|
|
|
This function exposes class internals and should be avoided.
|
|
|
Return the next sibling of the current node
|
|
|
Return the filter that is used in this iterator.
|
|
|
Return the previous sibling of the current node
|
|
|
Returns true if the iterator is just to the left of a node.
|
|
|
leftNode()
Return the node to the left of the current iterator position.
|
|
| <inner> |
Advance the walker to the first node that is accepted by the node filter
(i.e.
|
|
Move the iterator to its last possible position.
|
|
|
moveToEndOfNode(node)
Places the iterator at the last position inside the given node.
|
|
| <inner> | |
|
Move the iterator to the previous position.
|
|
|
Return the node to the right of the current iterator position.
|
|
|
setPositionBeforeElement(element)
Set the current position of the iterator to just before the supplied element.
|
|
|
setUnfilteredPosition(container, offset)
Set the current position of the iterator to the specified container + offset.
|
|
|
Returns the current position within the container of the iterator.
|
Class Detail
core.PositionIterator(root, whatToShow, filter, expandEntityReferences)
An iterator that iterators through positions in a DOM tree.
Positions in the DOM tree are places between nodes and between characters.
Undesired positions can be avoided by passing a filter to constructor of the
PositionIterator.
In the following example '|' designates positions that an unfiltered
PositionIterator would visit.
|||a|b| |a||||
Certain positions are considered equivalent in by the PositionIterator.
Position 0 in a Text node is the same as the position preceding the Text node
in the parent node. The last position in a Text node is considered equal to
the subsequent position in the parent node. As such, these two Text node
positions are ommitted from the PositionIterator's traversal throught the
DOM. If the PositionIterator is set to a first or last position in a Text
node, it is instead set the equivalent position in the parent node.
Omitting the first and last Text node positions serves two functions:
- It ensures that the number of iterated steps is independent of how
characters are split up over text nodes.
- The iterator avoids positions that not distinguised by the API for
range and selections purposes.
- Parameters:
- {!Node} root
- {!number=} whatToShow
- {!NodeFilter=} filter
- {!boolean=} expandEntityReferences
Field Detail
previousNode
This function exposes class internals and should be avoided.
Method Detail
{!Element|!Text}
container()
Return the container for the current position.
- Returns:
- {!Element|!Text}
{!Element|!Text}
getCurrentNode()
This function exposes class internals and should be avoided.
- Returns:
- {!Element|!Text}
{Node}
getNextSibling()
Return the next sibling of the current node
- Returns:
- {Node}
{!function(?Node):!number}
getNodeFilter()
Return the filter that is used in this iterator.
- Returns:
- {!function(?Node):!number}
{Node}
getPreviousSibling()
Return the previous sibling of the current node
- Returns:
- {Node}
{!boolean}
isBeforeNode()
Returns true if the iterator is just to the left of a node. In this position,
calls to container() will return the parent of the node, and unfilteredDomOffset
will return the position of the node within the parent container.
Calls to unfilteredDomOffset are extremely slow when the iterator is just before a
node, so querying this method can provide warning when a slow offset is necessary.
- Returns:
- {!boolean}
{?Node}
leftNode()
Return the node to the left of the current iterator position.
See rightNode().
- Returns:
- {?Node}
<inner>
{!boolean}
moveToAcceptedNode()
Advance the walker to the first node that is accepted by the node filter
(i.e., nodeFilter(node) === FILTER_ACCEPT)
- Returns:
- {!boolean} Returns true if the walker found an accepted node. Otherwise returns false.
{undefined}
moveToEnd()
Move the iterator to its last possible position.
This is at the last position in the root node if the iterator.
- Returns:
- {undefined}
{undefined}
moveToEndOfNode(node)
Places the iterator at the last position inside the given node.
- Parameters:
- {!Node} node
- Returns:
- {undefined}
{!boolean}
nextPosition()
- Returns:
- {!boolean}
<inner>
{!boolean}
previousNode()
- Returns:
- {!boolean}
{!boolean}
previousPosition()
Move the iterator to the previous position.
If the iterator is already at the first position, it is not moved and
false is returned instead of true.
- Returns:
- {!boolean}
{?Node}
rightNode()
Return the node to the right of the current iterator position.
If the iterator is placed between two characters in a text node,
the text node will be returned.
If there is no right neighbor in the container node, then null is
returned.
Only filtered nodes will be returned.
- Returns:
- {?Node}
{!boolean}
setPositionBeforeElement(element)
Set the current position of the iterator to just before the supplied element.
Querying the iterator then will return the container of the element and the offset
of the element within it's container (assuming the supplied element is accepted by
the nodeFilter).
E.g.,
p1.setPositionBeforeElement(span);
p1.container() === span.parentNode
p1.unfilteredDomOffset === positionInParent(span)
If the element is not accepted by the nodeFilter, the iterator will immediately
move to the next accepted node.
- Parameters:
- {!Element} element
- Returns:
- {!boolean} Returns true if the iterator was set to a valid position (i.e., is currently on a node that is accepted by the nodeFilter)
{!boolean}
setUnfilteredPosition(container, offset)
Set the current position of the iterator to the specified container + offset.
Querying the iterator will then return the supplied container + offset
(assuming the supplied element is accepted by the nodeFilter).
E.g.,
p2.setUnfilteredPosition(container, offset);
p2.container() === container
p2.unfilteredDomOffset() === offset;
If the container is not accepted by the nodeFilter, the iterator will immediately
move to the next accepted node.
- Parameters:
- {!Node} container
- {!number} offset
- offset in unfiltered DOM world. Will immediately advance the iterator to the numbered child node of the provided container.
- Returns:
- {!boolean} Returns true if the iterator was set to a valid position (i.e., is currently on a node that is accepted by the nodeFilter)
{!number}
unfilteredDomOffset()
Returns the current position within the container of the iterator.
This function is useful for communication iterator position with
components that do not use a filter.
- Returns:
- {!number}
