edu.princeton.swing.text
Class HighlightedDocument

java.lang.Object
  extended by 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:

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()