edu.princeton.swing.text
Class HighlightedDocument

java.lang.Object
  |
  +--edu.princeton.swing.text.HighlightedDocument

Direct Known Subclasses:

DefaultHighlightedDocument, TProgramDocument

public abstract class HighlightedDocument

extends Object

HighlightedDocument is an abstract representation of a document which supports syntax highlighting. This document can then be displayed with a THighlightedTextArea.

Nested Class Summary

class	HighlightedDocument.Position Position is a simple implementation of javax.swing.text.Position.
class	HighlightedDocument.PositionTriplet PositionTriplet maintains three positions which permits efficient synchronous changes.
class	HighlightedDocument.UndoableEdit UndoableEdit is a simple implementation of javax.swing.undo.UndoableEdit.

Field Summary

static boolean[]	CHARACTER_ALLOWED An array of all characters allowed in a HighlightedDocument.
protected int	charCount
protected char[]	chars
protected byte[]	charStyles
protected int	lineCount
protected short[]	lineOffsets
static char	MAX_ALLOWED_CHARACTER The allowed character with the greatest integer encoding.
protected int	maxLineLength

Constructor Summary

HighlightedDocument()
Constructs a HighlightedDocument.

Method Summary

void	addTextListener(TextListener listener) Adds a listener to monitor changes in the text of the document.
void	addUndoableEditListener(UndoableEditListener listener) Adds a listener to monitor undoable changes in the document.
void	allowRender(HighlightedDocumentRenderer renderer, Object extraInfo) Obtains a read lock and passes the protected data to an implementation of HighlightedDocumentRenderer.
protected abstract void	assignStyles() Updates the charStyles array based on chars, charCount, lineOffsets, and lineCount.
int	coordinateToOffset(int column, int line) Takes a (column, line) pair and returns the nearest valid offset.
int	coordinateToOffset(Point p) Takes a (column, line) pair and returns the nearest valid offset.
HighlightedDocument.Position	createPosition(int offset) Creates a position at a given offset which will move with the text.
HighlightedDocument.PositionTriplet	createPositionTriplet() Creates a position triplet.
StringBuffer	filterString(String string) Filters out all "non-standard" ASCII characters from the string.
void	freePosition(HighlightedDocument.Position position) Frees a position from future updates.
void	freePositionTriplet(HighlightedDocument.PositionTriplet positionTriplet) Frees a position triplet from future updates.
int	getLength() Returns the number of characters in the document.
int	getLineCount() Returns the number of lines in the document.
int	getMaxLineLength() Returns the length of the longest line.
protected int[]	getPositionOffsets() Returns an integer array containing a backup image of the position HashSet.
abstract int	getStyleCount() Returns the number of distinct styles used by this type of document.
abstract int	getTabSize() Returns the number of spaces to replace all tabs with.
String	getText() Returns the text of the document.
String	getText(int start, int end) Returns part of the text of the document.
int[]	getWordBounds(int offset) Returns the bounds of the word containing the character at the given offset.
void	insertString(int offset, String string, boolean mergable) Inserts a string at the specified index.
Point	offsetToCoordinate(int offset) Takes an offset and returns the nearest valid (column, line) pair.
protected void	readLock() Obtains a read-lock for this HighlightedDocument.
protected void	readUnlock() Releases the read-lock for this HighlightedDocument.
void	remove(int offset, int length, boolean mergable) Removes a segment of text specified by its offset and length.
void	removeTextListener(TextListener listener) Removes a listener from this document.
void	removeUndoableEditListener(UndoableEditListener listener) Removes a listener from this document.
void	replace(int offset, int length, String string, boolean mergable) Replaces the text in a given range with the specified string.
protected void	replace(int offset, int length, String string, boolean mergable, boolean generateUndoEvent, int[] positionOffsets, boolean disablePositionUpdate) Replaces the text in a given range with the specified string.
void	setText(String string) Sets the text to the given string.
protected void	writeLock() Obtains a write-lock for this HighlightedDocument.
protected void	writeUnlock() Releases the write-lock for this HighlightedDocument.

Methods inherited from class java.lang.Object

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

Field Detail

MAX_ALLOWED_CHARACTER

public static final char MAX_ALLOWED_CHARACTER

The allowed character with the greatest integer encoding.

See Also:

Constant Field Values

CHARACTER_ALLOWED

public static final boolean[] CHARACTER_ALLOWED

An array of all characters allowed in a HighlightedDocument.

chars

protected char[] chars

charStyles

protected byte[] charStyles

charCount

protected int charCount

lineOffsets

protected short[] lineOffsets

lineCount

protected int lineCount

maxLineLength

protected int maxLineLength

Constructor Detail

HighlightedDocument

public HighlightedDocument()

Constructs a HighlightedDocument.

Method Detail

getStyleCount

public abstract int getStyleCount()

Returns the number of distinct styles used by this type of document. This must always return the same number.

Returns:

The number of distinct styles used by this type of document.

getTabSize

public abstract int getTabSize()

Returns the number of spaces to replace all tabs with.

Returns:

The number of spaces to replace all tabs with.

addTextListener

public void addTextListener(TextListener listener)

Adds a listener to monitor changes in the text of the document.

Parameters:

listener - The listener to add to this document. A null value will cause a NullPointerException.

removeTextListener

public void removeTextListener(TextListener listener)

Removes a listener from this document. Nothing will happen if no match was found.

Parameters:

listener - The listener to remove from this document. A null value will cause a NullPointerException.

addUndoableEditListener

public void addUndoableEditListener(UndoableEditListener listener)

Adds a listener to monitor undoable changes in the document. Duplicates will be ignored.

Parameters:

listener - The listener to add to this document. A null value will cause a NullPointerException.

removeUndoableEditListener

public void removeUndoableEditListener(UndoableEditListener listener)

Removes a listener from this document. Nothing will happen if no match was found.

Parameters:

listener - The listener to remove from this document. A null value will cause a NullPointerException.

createPosition

public HighlightedDocument.Position createPosition(int offset)

Creates a position at a given offset which will move with the text.

Parameters:

offset - The offset at which the position will start.

Returns:

The position object which will move with the text.

freePosition

public void freePosition(HighlightedDocument.Position position)

Frees a position from future updates.

Parameters:

position - The position object to be detached.

createPositionTriplet

public HighlightedDocument.PositionTriplet createPositionTriplet()

Creates a position triplet.

Returns:

The position triplet.

freePositionTriplet

public void freePositionTriplet(HighlightedDocument.PositionTriplet positionTriplet)

Frees a position triplet from future updates.

Parameters:

positionTriplet - The positionTriplet object to be detached.

getPositionOffsets

protected int[] getPositionOffsets()

Returns an integer array containing a backup image of the position HashSet.

remove

public void remove(int offset,
                   int length,
                   boolean mergable)

Removes a segment of text specified by its offset and length. A TextEvent will be dispatched to the listeners.

Parameters:

offset - The index of the start of the segment to remove.

length - The length of the segment to remove.

mergable - Wheter or not the UndoableEdit generated can be merged with appropriately similar mergable UndoableEdits.

insertString

public void insertString(int offset,
                         String string,
                         boolean mergable)

Inserts a string at the specified index. A TextEvent and an UndoableEditEvent will be dispatched to the listeners.

Parameters:

offset - The index at which to insert the string.

string - The string to insert.

mergable - Wheter or not the UndoableEdit generated can be merged with appropriately similar mergable UndoableEdits.

replace

public void replace(int offset,
                    int length,
                    String string,
                    boolean mergable)

Replaces the text in a given range with the specified string. A TextEvent and an UndoableEditEvent will be dispatched to the listeners.

Parameters:

offset - The offset of the range about to be replaced.

length - The length of the range about to be replaced.

string - The string with which to replace the range.

mergable - Wheter or not the UndoableEdit generated can be merged with appropriately similar mergable UndoableEdits.

setText

public void setText(String string)

Sets the text to the given string. A TextEvent will be dispatched to the listeners.

Parameters:

string - The string replace the old text with.

replace

protected void replace(int offset,
                       int length,
                       String string,
                       boolean mergable,
                       boolean generateUndoEvent,
                       int[] positionOffsets,
                       boolean disablePositionUpdate)

Replaces the text in a given range with the specified string. And moves the positions around (if a positions array is specified). A TextEvent and an UndoableEditEvent will be dispatched to the listeners.

Parameters:

offset - The offset of the range about to be replaced.

length - The length of the range about to be replaced.

string - The string with which to replace the range.

mergable - Wheter or not the UndoableEdit generated can be merged with appropriately similar mergable UndoableEdits.

positionOffsets - An id-indexed array of position offsets to restore (this will be done before the position adjustment step). Leave as null if positions should be moved around normally.

disablePositionUpdate - Wheter or not to disable position update.

assignStyles

protected abstract void assignStyles()

Updates the charStyles array based on chars, charCount, lineOffsets, and lineCount. The implementation should assume that a write lock will have been obtained by the caller of this function.

filterString

public StringBuffer filterString(String string)

Filters out all "non-standard" ASCII characters from the string.

Parameters:

string - The string to be filtered. A null value will result in a NullPointerException.

Returns:

A StringBuffer containing the original string, without any "non-standard" ASCII characters.

getText

public String getText()

Returns the text of the document.

Returns:

The text of the document.

getText

public String getText(int start,
                      int end)

Returns part of the text of the document.

Parameters:

start - The offset at which to begin.

end - The offset at which to end.

Returns:

The text of the document.

getLength

public int getLength()

Returns the number of characters in the document.

Returns:

The number of characters in the document.

getLineCount

public int getLineCount()

Returns the number of lines in the document.

Returns:

The number of lines in the document.

getMaxLineLength

public int getMaxLineLength()

Returns the length of the longest line.

Returns:

The length of the longest line.

getWordBounds

public int[] getWordBounds(int offset)

Returns the bounds of the word containing the character at the given offset. The following are the rules used to get the word bounds:

• If that character is a newline, the bounds will enclose that one newline.
• If that character is a space, the bounds will enclose all spaces adjacent to that space.
• If that character is an identifier character (letter, digit, or underscore), then the bounds will enclose all identifier characters adjacent to that character.
• If that charater is something else, the bounds will just enclose all identical characters adjacent to that character.

Parameters:

offset - The offset of one of the characters in the desired word.

Returns:

The bounds (a integer array of size 2) of the word. The word will span the half-open interval [retVal[0], retVal[1]).

allowRender

public void allowRender(HighlightedDocumentRenderer renderer,
                        Object extraInfo)

Obtains a read lock and passes the protected data to an implementation of HighlightedDocumentRenderer. The implementation of HighlightedDocumentRenderer should not modify the data or presume that it will be valid after the method returns.

Parameters:

renderer - The renderer that will recieve access to the protected data.

extraInfo - An object to hold additional parameters from the caller of allowRender.

See Also:

HighlightedDocumentRenderer.doRender(char[], byte[], int, short[], int, Object)

coordinateToOffset

public int coordinateToOffset(Point p)

Takes a (column, line) pair and returns the nearest valid offset.

Parameters:

p - The point (where x is the column, and y is the line) to convert to an offset.

Returns:

The nearest valid offset for the coordinate.

coordinateToOffset

public int coordinateToOffset(int column,
                              int line)

Takes a (column, line) pair and returns the nearest valid offset.

Parameters:

column - The column of the coordinate to convert to an offset.

line - The line of the coordinate to convert to an offset.

Returns:

The nearest valid offset for the coordinate.

offsetToCoordinate

public Point offsetToCoordinate(int offset)

Takes an offset and returns the nearest valid (column, line) pair.

Parameters:

offset - The offset to convert to a coordinate.

Returns:

The nearest valid point (where x is the column, and y is the line) to corresponding to the given offset.

writeLock

protected final void writeLock()

Obtains a write-lock for this HighlightedDocument. While this Thread has a write-lock, all Threads requesting either a read or write lock will be suspended. A call to this should be followed by a call to writeUnlock() in a finally block: try
{
writeLock();

...
}
finally
{
writeUnlock();
}

See Also:

writeUnlock(), readLock(), readUnlock()

writeUnlock

protected final void writeUnlock()

Releases the write-lock for this HighlightedDocument.

See Also:

writeLock(), readLock(), readUnlock()

readLock

protected final void readLock()

Obtains a read-lock for this HighlightedDocument. While this Thread has a read-lock, all Threads requesting a write lock will be suspended. A call to this should be followed by a call to readUnlock() in a finally block: try
{
readLock();

...
}
finally
{
readUnlock();
}

See Also:

writeLock(), writeUnlock(), readUnlock()

readUnlock

protected final void readUnlock()

Releases the read-lock for this HighlightedDocument.

See Also:

writeLock(), writeUnlock(), readLock()