org.xwiki.gwt.dom.client.internal.ie
Class TextRange

java.lang.Object
  com.google.gwt.core.client.JavaScriptObject
      org.xwiki.gwt.dom.client.internal.ie.NativeRange
          org.xwiki.gwt.dom.client.internal.ie.TextRange

public final class TextRange
extends NativeRange

A text range is a DOM fragment that usually starts and ends inside a text node. It can be used to visually select a continuous text fragment.

Version:

$Id: TextRange.java 20039 2009-05-16 12:04:30Z sdumitriu $

Nested Class Summary

static class

TextRange.Unit A unit defining a fragment of a text range.

Constructor Summary

protected

TextRange() Default constructor.

Method Summary

void	collapse(boolean toStart) Moves the insertion point to the beginning or end of the current range.
short	compareEndPoints(RangeCompare how, TextRange range) Compares an end point of a TextRange object with an end point of another range.
TextRange	duplicate()
boolean	expand(TextRange.Unit unit) Expands the range so that partial units are completely contained.
boolean	findText(java.lang.String text, int searchScope, int flags) Searches for text in the document and positions the start and end points of the range to encompass the search string. The value passed for the searchScope parameter controls the part of the document, relative to the range, that is searched.
java.lang.String	getHTML()
int	getOffsetLeft() Retrieves the calculated left position of this range's start point relative to the layout or coordinate parent, as specified by the offsetParent property.
int	getOffsetTop() Retrieves the calculated top position of this range's start point relative to the layout or coordinate parent, as specified by the offsetParent property.
Element	getParentElement() The parent element is the element that completely encloses the text in the range.
java.lang.String	getText()
boolean	inRange(TextRange other) Tests whether one range is contained within another.
boolean	isEqual(TextRange other) Tests if this text range equals the given text range.
int	move(TextRange.Unit unit, int count) Collapses the given text range and moves the empty range by the given number of units.
int	moveEnd(TextRange.Unit unit, int count) Moves the end of this range by the given number of units.
int	moveStart(TextRange.Unit unit, int count) Moves the start of this range by the given number of units.
void	moveToElementText(Element element) Moves the text range so that the start and end positions of the range encompass the text in the given element.
void	moveToPoint(int x, int y) Moves the start and end positions of this text range to the given point.
static TextRange	newInstance(Document doc) Creates a new text range for the given document.
void	setEndPoint(RangeCompare how, TextRange range) Sets the end point of this range based on the end point of another range.
void	setHTML(java.lang.String html) Pastes HTML text into this text range, replacing any previous text and HTML elements in the range.
void	setText(java.lang.String text)

Methods inherited from class org.xwiki.gwt.dom.client.internal.ie.NativeRange

getOwnerDocument, isTextRange, select

Methods inherited from class com.google.gwt.core.client.JavaScriptObject

cast, createArray, createFunction, createObject, equals, hashCode, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

TextRange

protected TextRange()

Default constructor. Needs to be protected because all instances are created from JavaScript.

Method Detail

newInstance

public static TextRange newInstance(Document doc)

Creates a new text range for the given document. This range can be used to select only DOM nodes within this document.

Parameters:

doc - The owner document of the created range.

Returns:

The created text range.

getHTML

public java.lang.String getHTML()

Returns:

The HTML source as a valid HTML fragment.

setHTML

public void setHTML(java.lang.String html)

Pastes HTML text into this text range, replacing any previous text and HTML elements in the range. This method might alter the HTML text to make it fit the given text range. For example, pasting a table cell into a text range that does not contain a table might cause the method to insert a table element. For predictable results, paste only well-formed HTML text that fits within the given text range.

Parameters:

html - The HTML text to paste. The string can contain text and any combination of the HTML tags.

getText

public java.lang.String getText()

Returns:

The text contained within the range.

setText

public void setText(java.lang.String text)

Parameters:

text - The text to be placed inside the range.

collapse

public void collapse(boolean toStart)

Moves the insertion point to the beginning or end of the current range.

Parameters:

toStart - if true moves the insertion point to the beginning of the text range. Otherwise, moves the insertion point to the end of the text range.

compareEndPoints

public short compareEndPoints(RangeCompare how,
                              TextRange range)

Compares an end point of a TextRange object with an end point of another range. A text range has two end points. One end point is located at the beginning of the text range, and the other is located at the end of the text range. An end point also can be characterized as the position between two characters in an HTML document.

Parameters:

how - Specifies which end points to compare.

range - The range object to compare with this object.

Returns:

One of the following possible values:

• -1 if the end point of this object is further to the left than the end point of the given range.
• 0 if the end point of this object is at the same location as the end point of the given range.
• 1 if the end point of this object is further to the right than the end point of the given range.

duplicate

public TextRange duplicate()

Returns:

A duplicate of this TextRange.

move

public int move(TextRange.Unit unit,
                int count)

Collapses the given text range and moves the empty range by the given number of units.

Parameters:

unit - Specifies the units to move

count - Specifies the number of units to move. This can be positive or negative.

Returns:

The number of units moved.

moveEnd

public int moveEnd(TextRange.Unit unit,
                   int count)

Moves the end of this range by the given number of units.

Parameters:

unit - Specifies the units to move.

count - Specifies the number of units to move. This can be positive or negative.

Returns:

The number of units moved.

moveStart

public int moveStart(TextRange.Unit unit,
                     int count)

Moves the start of this range by the given number of units.

Parameters:

unit - Specifies the units to move.

count - Specifies the number of units to move. This can be positive or negative.

Returns:

The number of units moved.

moveToElementText

public void moveToElementText(Element element)

Moves the text range so that the start and end positions of the range encompass the text in the given element.

Parameters:

element - The element object to move to.

getParentElement

public Element getParentElement()

The parent element is the element that completely encloses the text in the range. If the text range spans text in more than one element, this method returns the smallest element that encloses all the elements. When you insert text into a range that spans multiple elements, the text is placed in the parent element rather than in any of the contained elements.

Returns:

The parent element for this text range.

setEndPoint

public void setEndPoint(RangeCompare how,
                        TextRange range)

Sets the end point of this range based on the end point of another range. A text range has two end points: one at the beginning of the text range and one at the end. An end point can also be the position between two characters in an HTML document.

Parameters:

how - Specifies which end point of this text range should be moved and which of the given text range's end points is the reference.

range - The text range used as the reference.

findText

public boolean findText(java.lang.String text,
                        int searchScope,
                        int flags)

Searches for text in the document and positions the start and end points of the range to encompass the search string.
The value passed for the searchScope parameter controls the part of the document, relative to the range, that is searched. The behavior of the findText method depends on whether the range is collapsed or not:

• If the range is collapsed, passing a large positive number causes the text to the right of the range to be searched. Passing a large negative number causes the text to the left of the range to be searched.
• If the range is not collapsed, passing a large positive number causes the text to the right of the start of the range to be searched. Passing a large negative number causes the text to the left of the end of the range to be searched. Passing 0 causes only the text selected by the range to be searched.

A text range is not modified if the text specified for the findText method is not found.

Parameters:

text - The text to find.

searchScope - The number of characters to search from the starting point of the range. A positive integer indicates a forward search; a negative integer indicates a backward search.

flags - One or more of the following flags to indicate the type of search:

0	Default. Match partial words.
1	Match backwards.
2	Match whole words only.
4	Match case.
131072	Match bytes.
536870912	Match diacritical marks.
1073741824	Match Kashida character.
2147483648	Match AlefHamza character.

Returns:

true if the given text was found.

isEqual

public boolean isEqual(TextRange other)

Tests if this text range equals the given text range.

Parameters:

other - the text range to compare with this text range.

Returns:

true if the given text range is equal to this text rage.

inRange

public boolean inRange(TextRange other)

Tests whether one range is contained within another.

Parameters:

other - The text range that might be contained in this text range.

Returns:

true if the given text range is contained within or is equal to this text range.

expand

public boolean expand(TextRange.Unit unit)

Expands the range so that partial units are completely contained.

Parameters:

unit - specifies the units that have to be completely included in the range

Returns:

true if the range was successfully expanded, false otherwise

moveToPoint

public void moveToPoint(int x,
                        int y)

Moves the start and end positions of this text range to the given point.

The coordinates of the point must be in pixels and be relative to the upper-left corner of the window. The resulting text range is empty, but you can expand and move the range using methods such as expand(Unit) and moveEnd(Unit, int).

Parameters:

x - integer that specifies the horizontal offset relative to the upper-left corner of the window, in pixels

y - integer that specifies the vertical offset relative to the upper-left corner of the window, in pixels

getOffsetLeft

public int getOffsetLeft()

Retrieves the calculated left position of this range's start point relative to the layout or coordinate parent, as specified by the offsetParent property.

Returns:

an integer that specifies the left position, in pixels

getOffsetTop

public int getOffsetTop()

Retrieves the calculated top position of this range's start point relative to the layout or coordinate parent, as specified by the offsetParent property.

Returns:

an integer that specifies the top position, in pixels