org.xwiki.gwt.dom.client

Class DOMUtils

java.lang.Object

org.xwiki.gwt.dom.client.DOMUtils

public class DOMUtils
extends Object

Utility class providing methods for manipulating the DOM tree. Add here only the methods that work with any kind of DOM node and the methods that have different implementation for different browsers. For specific node types see Document, Element or Text.

Version:

$Id: e697475b50f91ae36c7e74364c119402bae8c08f $

Field Summary

Fields

Modifier and Type	Field and Description
static String	BR The <br/> tag name.
static short	CDATA_NODE Constant for the CDATA node type.
static short	COMMENT_NODE Constant for the comment node type.
static short	DOCUMENT_FRAGMENT_NODE Constant for the DocumentFragment node type.
static String	HR The <hr/> tag name.
protected static String[]	HTML_EMPTY_TAGS The list of all HTML tags that must be empty.
static String	ID The id attribute.
static String	UNSUPPORTED_NODE_TYPE Common error message used when a particular node type is not supported by a method.

Constructor Summary

Constructors

Constructor and Description
DOMUtils()

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canHaveChildren(com.google.gwt.dom.client.Node node)
com.google.gwt.dom.client.Node	cloneNode(com.google.gwt.dom.client.Node node, int offset, boolean left) Clones the left or right side of the subtree rooted in the given node.
com.google.gwt.dom.client.Node	cloneNode(com.google.gwt.dom.client.Node node, int startOffset, int endOffset) Clones the given DOM node, keeping only the contents between start and end offset.
com.google.gwt.dom.client.Node	cloneNode(com.google.gwt.dom.client.Node parent, com.google.gwt.dom.client.Node descendant, int offset, boolean left) Clones the node specified by its parent and its descendant, including only the left or right part of the tree whose separator is the path from the given descendant to the parent of the cloned node.
DocumentFragment	cloneNodeContents(com.google.gwt.dom.client.Node node, int startOffset, int endOffset) Clones the contents of the given node.
short	comparePoints(com.google.gwt.dom.client.Node alice, int aliceOffset, com.google.gwt.dom.client.Node bob, int bobOffset) Compares two points in a Document.
void	deleteNodeContents(com.google.gwt.dom.client.Node node, int offset, boolean left) Deletes the left or right side of the subtree rooted in the given node.
void	deleteNodeContents(com.google.gwt.dom.client.Node node, int startOffset, int endOffset) Deletes the contents of the given node between the specified offsets.
void	deleteNodeContents(com.google.gwt.dom.client.Node parent, com.google.gwt.dom.client.Node descendant, int offset, boolean left) Given a subtree specified by its root parent and one of the inner nodes, this method deletes the left or right part delimited by the path from the given descendant (inner node) to the root parent.
void	deleteSiblings(com.google.gwt.dom.client.Node node, boolean left) Deletes left or right siblings of the given node.
void	detach(com.google.gwt.dom.client.Node node) Removes the given node from its parent.
void	ensureBlockIsEditable(Element block) Ensures the given block-level element can be edited in design mode.
com.google.gwt.dom.client.Node	extractNode(com.google.gwt.dom.client.Node node, int offset, boolean left) Extracts the left or right side of the subtree rooted in the given node.
com.google.gwt.dom.client.Node	extractNode(com.google.gwt.dom.client.Node node, int startOffset, int endOffset) Extracts the given DOM node, keeping only the contents between start and end offset.
com.google.gwt.dom.client.Node	extractNode(com.google.gwt.dom.client.Node parent, com.google.gwt.dom.client.Node descendant, int offset, boolean left) Extracts the node specified by its parent and its descendant, including only the left or right part of the tree whose separator is the path from the given descendant to the parent of the extracted node.
DocumentFragment	extractNodeContents(com.google.gwt.dom.client.Node node, int startOffset, int endOffset) Extracts the contents of the given node.
List<com.google.gwt.dom.client.Node>	getAncestors(com.google.gwt.dom.client.Node node)
String	getAttribute(Element element, String name) Returns the value of the named attribute of the specified element.
com.google.gwt.core.client.JsArrayString	getAttributeNames(Element element)
com.google.gwt.dom.client.Node	getChild(com.google.gwt.dom.client.Node parent, com.google.gwt.dom.client.Node descendant)
List<com.google.gwt.dom.client.Node>	getChildNodes(com.google.gwt.dom.client.Node node, int startOffset, int endOffset) Obtain a sub-list of child nodes.
String	getComputedStyleProperty(Element element, String propertyName) Returns the value of the specified CSS property for the given element as it is computed by the browser before it displays that element.
com.google.gwt.dom.client.Node	getFarthestInlineAncestor(com.google.gwt.dom.client.Node node) Walks from the given node up to the root of the DOM tree as long as the ancestors represent in-line content.
com.google.gwt.dom.client.Node	getFirstAncestor(com.google.gwt.dom.client.Node node, NodeFilter filter) Searches for the first ancestor of the given node, including the node itself, that matches the specified filter.
com.google.gwt.dom.client.Node	getFirstAncestor(com.google.gwt.dom.client.Node node, String... tagNames) Searches for the first ancestor with a name from tagNames of the passed node, including the node itself.
com.google.gwt.dom.client.Node	getFirstDescendant(com.google.gwt.dom.client.Node node, String tagName) Searches for the first element descendant with the name tagName.
com.google.gwt.dom.client.Node	getFirstLeaf(com.google.gwt.dom.client.Node node)
com.google.gwt.dom.client.Node	getFirstLeaf(Range range)
String	getInnerText(Element element) We need our own implementation because the one provided by GWT includes commented text in the output.
static DOMUtils	getInstance() NOTE: We use deferred binding because some of the methods don't have cross-browser implementation and we want to load the implementation specific to the browser used.
com.google.gwt.dom.client.Node	getLastAncestor(com.google.gwt.dom.client.Node node, NodeFilter filter) Searches for the last ancestor of the given node, including the node itself, that matches the specified filter.
com.google.gwt.dom.client.Node	getLastLeaf(com.google.gwt.dom.client.Node node)
com.google.gwt.dom.client.Node	getLastLeaf(Range range)
int	getLength(com.google.gwt.dom.client.Node node)
com.google.gwt.dom.client.Node	getNearestBlockContainer(com.google.gwt.dom.client.Node node)
com.google.gwt.dom.client.Node	getNearestCommonAncestor(com.google.gwt.dom.client.Node alice, com.google.gwt.dom.client.Node bob)
com.google.gwt.dom.client.Node	getNearestFlowContainer(com.google.gwt.dom.client.Node innerNode)
com.google.gwt.dom.client.Node	getNextLeaf(com.google.gwt.dom.client.Node node)
com.google.gwt.dom.client.Node	getNextLeaf(Range range)
com.google.gwt.dom.client.Node	getNextNode(Range range)
int	getNodeIndex(com.google.gwt.dom.client.Node node)
int	getNormalizedChildCount(com.google.gwt.dom.client.Node node)
int	getNormalizedNodeIndex(com.google.gwt.dom.client.Node node) Computes the index that can be used with getChildNodes().getItem() to retrieve the given node from its parent after the parent is serialized and deserialized.
com.google.gwt.dom.client.Node	getPreviousLeaf(com.google.gwt.dom.client.Node node)
com.google.gwt.dom.client.Node	getPreviousLeaf(Range range)
com.google.gwt.dom.client.Node	getPreviousNode(Range range)
Range	getTextRange(Range range) Computes the longest text range included in the specified range.
boolean	hasAttribute(Element element, String attributeName)
boolean	hasAttributes(Element element)
com.google.gwt.dom.client.Node	importNode(Document doc, com.google.gwt.dom.client.Node externalNode, boolean deep) Creates a copy of a node from an external document that can be inserted into the given document.
void	insertAfter(com.google.gwt.dom.client.Node newChild, com.google.gwt.dom.client.Node refChild) Inserts the given child node after the reference node.
void	insertAt(com.google.gwt.dom.client.Node parent, com.google.gwt.dom.client.Node newChild, int index) Inserts a node at the specified index under the given parent.
boolean	isBlock(com.google.gwt.dom.client.Node node)
boolean	isBlockLevelInlineContainer(com.google.gwt.dom.client.Node node)
boolean	isDesignMode(Document document)
boolean	isFlowContainer(com.google.gwt.dom.client.Node node)
boolean	isInline(com.google.gwt.dom.client.Node node)
void	isolate(com.google.gwt.dom.client.Node node) Isolates a node from its siblings.
boolean	isOrContainsLineBreak(com.google.gwt.dom.client.Node node)
boolean	isSerializable(com.google.gwt.dom.client.Node node) Specifies if a node's HTML serialization is included in its parent node's HTML serialization.
boolean	isSpecialBlock(com.google.gwt.dom.client.Node node)
void	removeAttribute(Element element, String attributeName) Removes an attribute by name.
void	removeProperty(Element element, String propertyName) Removes a property from an element.
void	scrollIntoView(Element element) Makes sure that the given DOM element is visible by scrolling it into view.
void	scrollIntoView(Range range) Makes sure that a given DOM range is visible by scrolling it into view.
void	setAttribute(Element element, String name, String value) Sets the value of the specified attribute for the given element.
void	setDesignMode(Document document, boolean designMode) Puts the given document in design mode or in view-only mode.
void	setInnerHTML(Element element, String html) Helps setting the inner HTML for an element, in a cross-browser manner, because IE seems to trim leading comments in the inner HTML.
Range	shrinkRange(Range range) Computes the maximal sub-range of the given range that satisfies the following two conditions: the start point is before a leaf element node that can't have child nodes (e.g.
com.google.gwt.dom.client.Node	splitHTMLNode(com.google.gwt.dom.client.Node parent, com.google.gwt.dom.client.Node descendant, int offset) Given a subtree specified by its root parent and one of the inner nodes, this method splits the subtree by the path from the given descendant (inner node) to the root parent.
com.google.gwt.dom.client.Node	splitNode(com.google.gwt.dom.client.Node node, int offset) Splits the given DOM node at the specified offset.
com.google.gwt.dom.client.Node	splitNode(com.google.gwt.dom.client.Node parent, com.google.gwt.dom.client.Node descendant, int offset) Given a subtree specified by its root parent and one of the inner nodes, this method splits the subtree by the path from the given descendant (inner node) to the root parent.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

UNSUPPORTED_NODE_TYPE

public static final String UNSUPPORTED_NODE_TYPE

Common error message used when a particular node type is not supported by a method.

See Also:

Constant Field Values

BR

public static final String BR

The <br/> tag name.

See Also:

Constant Field Values

HR

public static final String HR

The <hr/> tag name.

See Also:

Constant Field Values

ID

public static final String ID

The id attribute.

See Also:

Constant Field Values

COMMENT_NODE

public static final short COMMENT_NODE

Constant for the comment node type.

See Also:

Constant Field Values

CDATA_NODE

public static final short CDATA_NODE

Constant for the CDATA node type.

See Also:

Constant Field Values

DOCUMENT_FRAGMENT_NODE

public static final short DOCUMENT_FRAGMENT_NODE

Constant for the DocumentFragment node type.

See Also:

Constant Field Values

HTML_EMPTY_TAGS

protected static final String[] HTML_EMPTY_TAGS

The list of all HTML tags that must be empty. All of them appear as <tagName/> in the HTML code.
NOTE: We had to move this array from Element because there is a problem with static field initialization for classes extending JavaScriptObject.

See Also:

http://code.google.com/p/google-web-toolkit/issues/detail?id=3192

Constructor Detail

DOMUtils

public DOMUtils()

Method Detail

getInstance

public static DOMUtils getInstance()

NOTE: We use deferred binding because some of the methods don't have cross-browser implementation and we want to load the implementation specific to the browser used.

Returns:

the instance in use.

getComputedStyleProperty

public String getComputedStyleProperty(Element element,
                              String propertyName)

Returns the value of the specified CSS property for the given element as it is computed by the browser before it displays that element. The CSS property doesn't have to be applied explicitly or directly on the given element. It can be inherited or assumed by default on that element.
NOTE: You have to pass the JavaScript name of the property and not its CSS name. The JavaScript name has camel case style (fontWeight) and it is used like this object.style.propertyJSName = value. The CSS name has dash style (font-weight) and it is used like this propertyCSSName: value;.

Parameters:

element - the element for which we retrieve the property value.

propertyName - the script name of the CSS property whose value is returned.

Returns:

the computed value of the specified CSS property for the given element.

getNextLeaf

public com.google.gwt.dom.client.Node getNextLeaf(com.google.gwt.dom.client.Node node)

Parameters:

node - the node from where to begin the search for the next leaf.

Returns:

the next leaf node in a deep-first search, considering we already looked in the subtree whose root is the given node.

getNextLeaf

public com.google.gwt.dom.client.Node getNextLeaf(Range range)

Parameters:

range - the range after which to look for a leaf

Returns:

the next leaf which is not touched by the specified range.

getPreviousLeaf

public com.google.gwt.dom.client.Node getPreviousLeaf(Range range)

Parameters:

range - the range before which to look for a leaf

Returns:

the previous leaf which is not touched by the specified range.

getPreviousLeaf

public com.google.gwt.dom.client.Node getPreviousLeaf(com.google.gwt.dom.client.Node node)

Parameters:

node - the node from where to begin the search for the previous leaf.

Returns:

the previous leaf node in a reverse deep-first search, considering we already looked in the subtree whose root is the given node.

getFirstLeaf

public com.google.gwt.dom.client.Node getFirstLeaf(com.google.gwt.dom.client.Node node)

Parameters:

node - the root of the DOM subtree whose first leaf is returned.

Returns:

the first leaf node of the DOM subtree whose root is the given node.

getLastLeaf

public com.google.gwt.dom.client.Node getLastLeaf(com.google.gwt.dom.client.Node node)

Parameters:

node - the root of the DOM subtree whose last leaf is returned.

Returns:

the last leaf node of the DOM subtree whose root is the given node.

getNodeIndex

public int getNodeIndex(com.google.gwt.dom.client.Node node)

Parameters:

node - the node whose index is returned.

Returns:

the index of the given node among its siblings.

getNormalizedNodeIndex

public int getNormalizedNodeIndex(com.google.gwt.dom.client.Node node)

Computes the index that can be used with getChildNodes().getItem() to retrieve the given node from its parent after the parent is serialized and deserialized.

Parameters:

node - a DOM node

Returns:

the index of the given DOM node among its siblings, considering successive text nodes as one single node and ignoring hidden siblings

isSerializable

public boolean isSerializable(com.google.gwt.dom.client.Node node)

Specifies if a node's HTML serialization is included in its parent node's HTML serialization. Normally the inner HTML of an element includes the HTML representation of all of its descendants. This is not the case when one of the descendants is an element with an empty meta data associated. Associating empty meta data to an element is a way to hide that element from the inner HTML of his ancestors.

Parameters:

node - a DOM node

Returns:

true if the given node is represented in its parent inner HTML

getNormalizedChildCount

public int getNormalizedChildCount(com.google.gwt.dom.client.Node node)

Parameters:

node - a DOM node.

Returns:

the child count for the given DOM node, considering successive child text nodes as one single child.

See Also:

getNormalizedNodeIndex(Node)

isInline

public boolean isInline(com.google.gwt.dom.client.Node node)

Parameters:

node - a DOM node

Returns:

true if the given DOM node represents in-line content

isBlock

public boolean isBlock(com.google.gwt.dom.client.Node node)

Parameters:

node - a DOM node

Returns:

true if the given node is a block-level element, false otherwise

isBlockLevelInlineContainer

public boolean isBlockLevelInlineContainer(com.google.gwt.dom.client.Node node)

Parameters:

node - a DOM node

Returns:

true if the given node is a block-level element that can have only in-line content, false otherwise

See Also:

HTML_BLOCK_LEVEL_INLINE_CONTAINERS

isSpecialBlock

public boolean isSpecialBlock(com.google.gwt.dom.client.Node node)

Parameters:

node - a DOM node

Returns:

true if the given node is a block-level element that can have only special content, false otherwise

See Also:

HTML_SPECIAL_BLOCK_LEVEL_ELEMENTS

getTextRange

public Range getTextRange(Range range)

Computes the longest text range included in the specified range. By text range we understand any range that starts and ends in a text node. The end points of a text range can be in different text nodes.

Parameters:

range - any range

Returns:

the longest text range included in the given range.

shrinkRange

public Range shrinkRange(Range range)

Computes the maximal sub-range of the given range that satisfies the following two conditions:

• the start point is before a leaf element node that can't have child nodes (e.g. an image) or inside a leaf node at position 0 (e.g. an empty span or a text node)
• the end point is after a leaf element node that can't have child nodes (e.g. an image) or inside a leaf node at the end (e.g. inside an empty span or at the end of a text node)

. If no such sub-range exists (because the given range doesn't wrap any leaf node and none of its end points satisfies the corresponding condition) then the given range is returned unmodified.

Parameters:

range - a DOM range

Returns:

the maximal sub-range that selects the same content as the given range

importNode

public com.google.gwt.dom.client.Node importNode(Document doc,
                                        com.google.gwt.dom.client.Node externalNode,
                                        boolean deep)

Creates a copy of a node from an external document that can be inserted into the given document.

Parameters:

doc - The document in which we want to insert the returned copy.

externalNode - The node from another document to be imported.

deep - Indicates whether the children of the given node need to be imported.

Returns:

a copy of the given node that can be inserted into the specified document.

getAttributeNames

public com.google.gwt.core.client.JsArrayString getAttributeNames(Element element)

Parameters:

element - The DOM element whose attribute names are returned.

Returns:

The names of DOM attributes present on the given element.

getFirstAncestor

public com.google.gwt.dom.client.Node getFirstAncestor(com.google.gwt.dom.client.Node node,
                                              String... tagNames)

Searches for the first ancestor with a name from tagNames of the passed node, including the node itself. The search order starts with node and continues to the root of the tree.

Parameters:

node - the node to find ancestor for

tagNames - the tag names to look for up in the DOM tree.

Returns:

the first node a name from tagNames found.

getFirstAncestor

public com.google.gwt.dom.client.Node getFirstAncestor(com.google.gwt.dom.client.Node node,
                                              NodeFilter filter)

Searches for the first ancestor of the given node, including the node itself, that matches the specified filter. The search order starts with node and continues to the root of the tree.

Parameters:

node - the node whose ancestor needs to be found

filter - the object used to filter the ancestors

Returns:

the first ancestor of the given node that matches the filter

getLastAncestor

public com.google.gwt.dom.client.Node getLastAncestor(com.google.gwt.dom.client.Node node,
                                             NodeFilter filter)

Searches for the last ancestor of the given node, including the node itself, that matches the specified filter. The search order starts with node and continues to the root of the tree.

Parameters:

node - the node whose ancestor needs to be found

filter - the object used to filter the ancestors

Returns:

the last ancestor of the given node that matches the filter

getFirstDescendant

public com.google.gwt.dom.client.Node getFirstDescendant(com.google.gwt.dom.client.Node node,
                                                String tagName)

Searches for the first element descendant with the name tagName. Searching is done in a DFS order with node processing on first pass through them.

Parameters:

node - the node to start the search from

tagName - the name of the searched element

Returns:

the first descendant of type tagName of the passed node, in DFS order.

setInnerHTML

public void setInnerHTML(Element element,
                String html)

Helps setting the inner HTML for an element, in a cross-browser manner, because IE seems to trim leading comments in the inner HTML. This method is overwritten in IE's specific implementation.

Parameters:

element - element to set the inner HTML for

html - the HTML string to set

See Also:

http://code.google.com/p/google-web-toolkit/issues/detail?id=3146

getNearestCommonAncestor

public com.google.gwt.dom.client.Node getNearestCommonAncestor(com.google.gwt.dom.client.Node alice,
                                                      com.google.gwt.dom.client.Node bob)

Parameters:

alice - A DOM node.

bob - A DOM node.

Returns:

The nearest common ancestor of the given nodes.

getAncestors

public List<com.google.gwt.dom.client.Node> getAncestors(com.google.gwt.dom.client.Node node)

Parameters:

node - a DOM node

Returns:

the list of ancestors of the given node, starting with it

cloneNodeContents

public DocumentFragment cloneNodeContents(com.google.gwt.dom.client.Node node,
                                 int startOffset,
                                 int endOffset)

Clones the contents of the given node. If node type is text, CDATA or comment then only the data between startOffset (including) and endOffset is kept. If node type is element then only the child nodes with indexes between startOffset (including) and endOffset are included in the document fragment returned.

Parameters:

node - The DOM node whose contents will be cloned.

startOffset - the index of the first child to clone or the first character to include in the cloned contents.

endOffset - specifies where the cloned contents end.

Returns:

the cloned contents of the given node, between start offset and end offset.

cloneNode

public com.google.gwt.dom.client.Node cloneNode(com.google.gwt.dom.client.Node node,
                                       int startOffset,
                                       int endOffset)

Clones the given DOM node, keeping only the contents between start and end offset. If node type is text, CDATA or comment then both offsets represent character indexes. Otherwise they represent child indexes.

Parameters:

node - The DOM node to be cloned.

startOffset - specifies where to start the cloning.

endOffset - specifies where to end the cloning.

Returns:

A clone of the given node, containing only the contents between start and end offset.

getLength

public int getLength(com.google.gwt.dom.client.Node node)

Parameters:

node - A DOM node.

Returns:

the number of characters if the given node is a text, a CDATA section or a comment. Otherwise the returned value is the number of child nodes.

cloneNode

public com.google.gwt.dom.client.Node cloneNode(com.google.gwt.dom.client.Node node,
                                       int offset,
                                       boolean left)

Clones the left or right side of the subtree rooted in the given node.

Parameters:

node - The root of the subtree whose left or right side will be cloned.

offset - Marks the boundary between the left and the right subtrees. It can be either a character index or a child index, depending on the type of the given node.

left - Specifies which of the subtrees to be cloned.

Returns:

The clone of the specified subtree.

cloneNode

public com.google.gwt.dom.client.Node cloneNode(com.google.gwt.dom.client.Node parent,
                                       com.google.gwt.dom.client.Node descendant,
                                       int offset,
                                       boolean left)

Clones the node specified by its parent and its descendant, including only the left or right part of the tree whose separator is the path from the given descendant to the parent of the cloned node.

Parameters:

parent - The parent of the cloned node.

descendant - A descendant of the cloned node.

offset - The offset within the given descendant. It can be either a character index or a child index depending on the descendant node type.

left - Specifies which subtree to be cloned. Left and right subtrees are delimited by the path from the given descendant to the parent of the cloned node.

Returns:

The clone of the specified subtree.

getChild

public com.google.gwt.dom.client.Node getChild(com.google.gwt.dom.client.Node parent,
                                      com.google.gwt.dom.client.Node descendant)

Parameters:

parent - the parent node of the retrieved child

descendant - a descendant of the retrieved child

Returns:

the child of the given parent, which has the specified descendant

insertAfter

public void insertAfter(com.google.gwt.dom.client.Node newChild,
               com.google.gwt.dom.client.Node refChild)

Inserts the given child node after the reference node.

Parameters:

newChild - The child node to be inserted.

refChild - The reference node.

deleteNodeContents

public void deleteNodeContents(com.google.gwt.dom.client.Node node,
                      int startOffset,
                      int endOffset)

Deletes the contents of the given node between the specified offsets. If node type is text, CDATA or comment then only the data between startOffset (including) and endOffset is deleted. If node type is element then only the child nodes with indexes between startOffset (including) and endOffset are deleted.

Parameters:

node - The DOM node whose contents will be deleted.

startOffset - the index of the first child or the first character to delete, depending on node type.

endOffset - specifies where to stop deleting content.

deleteNodeContents

public void deleteNodeContents(com.google.gwt.dom.client.Node node,
                      int offset,
                      boolean left)

Deletes the left or right side of the subtree rooted in the given node.

Parameters:

node - The root of the subtree whose left or right side will be deleted.

offset - Marks the boundary between the left and the right subtrees. It can be either a character index or a child index, depending on the type of the given node.

left - Specifies which of the subtrees to be deleted.

deleteSiblings

public void deleteSiblings(com.google.gwt.dom.client.Node node,
                  boolean left)

Deletes left or right siblings of the given node.

Parameters:

node - The DOM node whose left or right siblings will be deleted.

left - Specifies which siblings to delete.

deleteNodeContents

public void deleteNodeContents(com.google.gwt.dom.client.Node parent,
                      com.google.gwt.dom.client.Node descendant,
                      int offset,
                      boolean left)

Given a subtree specified by its root parent and one of the inner nodes, this method deletes the left or right part delimited by the path from the given descendant (inner node) to the root parent.

Parameters:

parent - The parent node of the subtree's root.

descendant - An inner node within the specified subtree.

offset - The offset within the given descendant. It can be either a character index or a child index depending on the descendant node type.

left - Specifies which side of the subtree to be deleted. Left and right parts are delimited by the path from the given descendant to the parent of the subtree's root.

splitNode

public com.google.gwt.dom.client.Node splitNode(com.google.gwt.dom.client.Node node,
                                       int offset)

Splits the given DOM node at the specified offset.

Parameters:

node - The node to be split.

offset - Specifies where to split. It can be either a character index or a child index depending on node type.

Returns:

The node resulted after the split. It should be the next sibling of the given node.

splitNode

public com.google.gwt.dom.client.Node splitNode(com.google.gwt.dom.client.Node parent,
                                       com.google.gwt.dom.client.Node descendant,
                                       int offset)

Given a subtree specified by its root parent and one of the inner nodes, this method splits the subtree by the path from the given descendant (inner node) to the root parent.

Parameters:

parent - The parent node of the subtree's root.

descendant - An inner node within the specified subtree.

offset - The offset within the given descendant. It can be either a character index or a child index depending on the descendant node type.

Returns:

The node resulted from splitting the descendant.

splitHTMLNode

public com.google.gwt.dom.client.Node splitHTMLNode(com.google.gwt.dom.client.Node parent,
                                           com.google.gwt.dom.client.Node descendant,
                                           int offset)

Given a subtree specified by its root parent and one of the inner nodes, this method splits the subtree by the path from the given descendant (inner node) to the root parent. Additionally to what splitNode(Node, Node, int)) does this method ensures that both subtrees are editable in design mode. This method is required because most browsers prevent the user from placing the caret inside empty block elements such as paragraphs or headers. This empty block elements can be obtained by splitting at the beginning or at the end of such a block element.

Parameters:

parent - the parent node of the subtree's root

descendant - an inner node within the specified subtree

offset - the offset within the given descendant. It can be either a character index or a child index depending on the descendant node type.

Returns:

the node resulted from splitting the descendant

See Also:

splitNode(Node, Node, int)

isFlowContainer

public boolean isFlowContainer(com.google.gwt.dom.client.Node node)

Parameters:

node - A DOM node.

Returns:

true is the given node is an element that can have both in-line and block content.

getNearestFlowContainer

public com.google.gwt.dom.client.Node getNearestFlowContainer(com.google.gwt.dom.client.Node innerNode)

Parameters:

innerNode - A DOM node.

Returns:

The nearest ancestor of the given node that can contain both in-line and block content.

insertAt

public void insertAt(com.google.gwt.dom.client.Node parent,
            com.google.gwt.dom.client.Node newChild,
            int index)

Inserts a node at the specified index under the given parent.

Parameters:

parent - The parent node which will adopt the given node.

newChild - The node to be inserted.

index - Specifies the position inside the parent node where the new child should be placed.

getFarthestInlineAncestor

public com.google.gwt.dom.client.Node getFarthestInlineAncestor(com.google.gwt.dom.client.Node node)

Walks from the given node up to the root of the DOM tree as long as the ancestors represent in-line content. Returns the last node in the walk.

Parameters:

node - a DOM node

Returns:

the farthest ancestor of the given node that represents in-line content

getFirstLeaf

public com.google.gwt.dom.client.Node getFirstLeaf(Range range)

Parameters:

range - A DOM range.

Returns:

the first leaf node that is partially or entirely included in the given range.

getLastLeaf

public com.google.gwt.dom.client.Node getLastLeaf(Range range)

Parameters:

range - A DOM range.

Returns:

the last leaf node that is partially or entirely included in the given range.

detach

public void detach(com.google.gwt.dom.client.Node node)

Removes the given node from its parent.

Parameters:

node - A DOM node.

getNearestBlockContainer

public com.google.gwt.dom.client.Node getNearestBlockContainer(com.google.gwt.dom.client.Node node)

Parameters:

node - A DOM node

Returns:

The nearest block level ancestor of the given node.

getAttribute

public String getAttribute(Element element,
                  String name)

Returns the value of the named attribute of the specified element. This method will be overwritten for Internet Explorer browsers to overcome the fact that the native implementation doesn't return the value from some of the standard attributes like style and class. This method should be used only when the attribute name is not know.

Parameters:

element - the element to get the attribute for

name - the name of the attribute to return

Returns:

the value of the attribute

setAttribute

public void setAttribute(Element element,
                String name,
                String value)

Sets the value of the specified attribute for the given element. This method will be overwritten for Internet Explorer to overcome that fact that the style attribute cannot be set in the standard way.

Parameters:

element - the element whose attribute is set

name - the name of the attribute

value - the value of the attribute

comparePoints

public short comparePoints(com.google.gwt.dom.client.Node alice,
                  int aliceOffset,
                  com.google.gwt.dom.client.Node bob,
                  int bobOffset)

Compares two points in a Document. Each point is specified by a DOM node and an offset within that node.

Parameters:

alice - first point's node

aliceOffset - first point's offset

bob - second point's node

bobOffset - second point's offset

Returns:

-1, 0 or 1 depending on whether the first point is respectively before, equal to, or after the second point

getInnerText

public String getInnerText(Element element)

We need our own implementation because the one provided by GWT includes commented text in the output.

Parameters:

element - the element whose inner text to return

Returns:

the text between the start and end tags of the given element

See Also:

http://code.google.com/p/google-web-toolkit/issues/detail?id=3275

hasAttributes

public boolean hasAttributes(Element element)

Parameters:

element - a DOM element

Returns:

true if the given element has any attributes

extractNodeContents

public DocumentFragment extractNodeContents(com.google.gwt.dom.client.Node node,
                                   int startOffset,
                                   int endOffset)

Extracts the contents of the given node. If node type is text, CDATA or comment then only the data between startOffset (including) and endOffset is kept. If node type is element then only the child nodes with indexes between startOffset (including) and endOffset are included in the document fragment returned.

Parameters:

node - the DOM node whose contents will be extracted

startOffset - the index of the first child to extract or the first character to include in the extracted contents

endOffset - specifies where the extracted contents end

Returns:

the extracted contents of the given node, between start offset and end offset

getChildNodes

public List<com.google.gwt.dom.client.Node> getChildNodes(com.google.gwt.dom.client.Node node,
                                                 int startOffset,
                                                 int endOffset)

Obtain a sub-list of child nodes.

Parameters:

node - the parent node

startOffset - the index of the first child node to return

endOffset - the index where to stop

Returns:

the children of the given node that have the index between the specified values (including start offset and excluding end offset)

extractNode

public com.google.gwt.dom.client.Node extractNode(com.google.gwt.dom.client.Node parent,
                                         com.google.gwt.dom.client.Node descendant,
                                         int offset,
                                         boolean left)

Extracts the node specified by its parent and its descendant, including only the left or right part of the tree whose separator is the path from the given descendant to the parent of the extracted node.

Parameters:

parent - the parent of the extracted node

descendant - a descendant of the extracted node

offset - the offset within the given descendant. It can be either a character index or a child index depending on the descendant node type.

left - specifies which subtree to be extracted. Left and right subtrees are delimited by the path from the given descendant to the parent of the extracted node.

Returns:

the extracted subtree

extractNode

public com.google.gwt.dom.client.Node extractNode(com.google.gwt.dom.client.Node node,
                                         int offset,
                                         boolean left)

Extracts the left or right side of the subtree rooted in the given node.

Parameters:

node - the root of the subtree whose left or right side will be extracted

offset - marks the boundary between the left and the right subtrees. It can be either a character index or a child index, depending on the type of the given node.

left - specifies which of the subtrees to be extracted

Returns:

the extracted subtree

extractNode

public com.google.gwt.dom.client.Node extractNode(com.google.gwt.dom.client.Node node,
                                         int startOffset,
                                         int endOffset)

Extracts the given DOM node, keeping only the contents between start and end offset. If node type is text, CDATA or comment then both offsets represent character indexes. Otherwise they represent child indexes.

Parameters:

node - the DOM node to be extracted

startOffset - specifies where to start the extraction

endOffset - specifies where to end the extraction

Returns:

a shallow clone of the given node, containing only the contents between start and end offset, which have been extracted from the input node

getNextNode

public com.google.gwt.dom.client.Node getNextNode(Range range)

Parameters:

range - a DOM range

Returns:

the node that follows after the end point of the given range, in a depth-first pre-order search

getPreviousNode

public com.google.gwt.dom.client.Node getPreviousNode(Range range)

Parameters:

range - a DOM range

Returns:

the node that precedes the start point of the given range, in a depth-first pre-order search

scrollIntoView

public void scrollIntoView(Range range)

Makes sure that a given DOM range is visible by scrolling it into view.

Parameters:

range - a DOM range

scrollIntoView

public void scrollIntoView(Element element)

Makes sure that the given DOM element is visible by scrolling it into view.

Parameters:

element - the element to scroll into view

ensureBlockIsEditable

public void ensureBlockIsEditable(Element block)

Ensures the given block-level element can be edited in design mode. This method is required because most browsers don't allow the caret inside elements that don't have any visible content and thus we cannot edit them otherwise.

The default implementation adds a BR element. Overwrite for browsers that don't like it.

Parameters:

block - a block-level DOM element

isOrContainsLineBreak

public boolean isOrContainsLineBreak(com.google.gwt.dom.client.Node node)

Parameters:

node - the node to check for line breaks

Returns:

true if the given node or one of its descendants is a BR (line break), false otherwise

setDesignMode

public void setDesignMode(Document document,
                 boolean designMode)

Puts the given document in design mode or in view-only mode.

NOTE: The standard implementation of this method sets the CONTENT_EDITABLE_ATTR attribute on the body element because otherwise read-only regions, marked with contentEditable=false, would be ignored. Browser specific implementations might use document's designMode property instead.

Parameters:

document - a DOM document

designMode - true to enter design mode, false to go back to view-only mode

isDesignMode

public boolean isDesignMode(Document document)

Parameters:

document - a DOM document

Returns:

true if the given document is in design mode, false otherwise

See Also:

setDesignMode(Document, boolean)

removeProperty

public void removeProperty(Element element,
                  String propertyName)

Removes a property from an element.

Parameters:

element - a DOM element

propertyName - the name of the property to be removed

canHaveChildren

public boolean canHaveChildren(com.google.gwt.dom.client.Node node)

Parameters:

node - a HTML DOM node

Returns:

true if the given node can have children, following the HTML strict DTD, false otherwise

hasAttribute

public boolean hasAttribute(Element element,
                   String attributeName)

Parameters:

element - a DOM element

attributeName - the name of an attribute

Returns:

true if the given element has the specified attribute, false otherwise

removeAttribute

public void removeAttribute(Element element,
                   String attributeName)

Removes an attribute by name.

Parameters:

element - a DOM element

attributeName - the name of the attribute to remove

isolate

public void isolate(com.google.gwt.dom.client.Node node)

Isolates a node from its siblings. Previous siblings are moved in a clone of their parent placed before their parent. Next siblings are moved in a clone of their parent placed after their parent. As an example, isolating the em from
<ins>a<em>b</em>c</ins>
results in
<ins>a</ins><ins><em>b</em></ins><ins>c</ins>.

Parameters:

node - the node to isolate