DocumentFilter, as the name implies, is a filter for the
* Document mutation methods. When a Document
* containing a DocumentFilter is modified (either through
* insert or remove), it forwards the appropriate
* method invocation to the DocumentFilter. The
* default implementation allows the modification to
* occur. Subclasses can filter the modifications by conditionally invoking
* methods on the superclass, or invoking the necessary methods on
* the passed in FilterBypass. Subclasses should NOT call back
* into the Document for the modification
* instead call into the superclass or the FilterBypass.
*
* When remove or insertString is invoked
* on the DocumentFilter, the DocumentFilter
* may callback into the
* FilterBypass multiple times, or for different regions, but
* it should not callback into the FilterBypass after returning
* from the remove or insertString method.
*
* By default, text related document mutation methods such as
* insertString, replace and remove
* in AbstractDocument use DocumentFilter when
* available, and Element related mutation methods such as
* create, insert and removeElement in
* DefaultStyledDocument do not use DocumentFilter.
* If a method doesn't follow these defaults, this must be explicitly stated
* in the method documentation.
*
* @see javax.swing.text.Document
* @see javax.swing.text.AbstractDocument
* @see javax.swing.text.DefaultStyledDocument
*
* @since 1.4
*/
public class DocumentFilter {
/**
* Invoked prior to removal of the specified region in the
* specified Document. Subclasses that want to conditionally allow
* removal should override this and only call supers implementation as
* necessary, or call directly into the FilterBypass as
* necessary.
*
* @param fb FilterBypass that can be used to mutate Document
* @param offset the offset from the beginning >= 0
* @param length the number of characters to remove >= 0
* @exception BadLocationException some portion of the removal range
* was not a valid part of the document. The location in the exception
* is the first bad position encountered.
*/
public void remove(FilterBypass fb, int offset, int length) throws
BadLocationException {
fb.remove(offset, length);
}
/**
* Invoked prior to insertion of text into the
* specified Document. Subclasses that want to conditionally allow
* insertion should override this and only call supers implementation as
* necessary, or call directly into the FilterBypass.
*
* @param fb FilterBypass that can be used to mutate Document
* @param offset the offset into the document to insert the content >= 0.
* All positions that track change at or after the given location
* will move.
* @param string the string to insert
* @param attr the attributes to associate with the inserted
* content. This may be null if there are no attributes.
* @exception BadLocationException the given insert position is not a
* valid position within the document
*/
public void insertString(FilterBypass fb, int offset, String string,
AttributeSet attr) throws BadLocationException {
fb.insertString(offset, string, attr);
}
/**
* Invoked prior to replacing a region of text in the
* specified Document. Subclasses that want to conditionally allow
* replace should override this and only call supers implementation as
* necessary, or call directly into the FilterBypass.
*
* @param fb FilterBypass that can be used to mutate Document
* @param offset Location in Document
* @param length Length of text to delete
* @param text Text to insert, null indicates no text to insert
* @param attrs AttributeSet indicating attributes of inserted text,
* null is legal.
* @exception BadLocationException the given insert position is not a
* valid position within the document
*/
public void replace(FilterBypass fb, int offset, int length, String text,
AttributeSet attrs) throws BadLocationException {
fb.replace(offset, length, text, attrs);
}
/**
* Used as a way to circumvent calling back into the Document to
* change it. Document implementations that wish to support
* a DocumentFilter must provide an implementation that will
* not callback into the DocumentFilter when the following methods
* are invoked from the DocumentFilter.
* @since 1.4
*/
public static abstract class FilterBypass {
/**
* Returns the Document the mutation is occuring on.
*
* @return Document that remove/insertString will operate on
*/
public abstract Document getDocument();
/**
* Removes the specified region of text, bypassing the
* DocumentFilter.
*
* @param offset the offset from the beginning >= 0
* @param length the number of characters to remove >= 0
* @exception BadLocationException some portion of the removal range
* was not a valid part of the document. The location in the
* exception is the first bad position encountered.
*/
public abstract void remove(int offset, int length) throws
BadLocationException;
/**
* Inserts the specified text, bypassing the
* DocumentFilter.
* @param offset the offset into the document to insert the
* content >= 0. All positions that track change at or after the
* given location will move.
* @param string the string to insert
* @param attr the attributes to associate with the inserted
* content. This may be null if there are no attributes.
* @exception BadLocationException the given insert position is not a
* valid position within the document
*/
public abstract void insertString(int offset, String string,
AttributeSet attr) throws
BadLocationException;
/**
* Deletes the region of text from offset to
* offset + length, and replaces it with
* text.
*
* @param offset Location in Document
* @param length Length of text to delete
* @param string Text to insert, null indicates no text to insert
* @param attrs AttributeSet indicating attributes of inserted text,
* null is legal.
* @exception BadLocationException the given insert is not a
* valid position within the document
*/
public abstract void replace(int offset, int length, String string,
AttributeSet attrs) throws
BadLocationException;
}
}