/*
* @(#)DocumentFilter.java 1.8 06/04/07
*
* Copyright 2006 Sun Microsystems, Inc. All rights reserved.
* SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
*/
package javax.swing.text;
/**
* <code>DocumentFilter</code>, as the name implies, is a filter for the
* <code>Document</code> mutation methods. When a <code>Document</code>
* containing a <code>DocumentFilter</code> is modified (either through
* <code>insert</code> or <code>remove</code>), it forwards the appropriate
* method invocation to the <code>DocumentFilter</code>. 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 <code>FilterBypass</code>. Subclasses should NOT call back
* into the Document for the modification
* instead call into the superclass or the <code>FilterBypass</code>.
* <p>
* When <code>remove</code> or <code>insertString</code> is invoked
* on the <code>DocumentFilter</code>, the <code>DocumentFilter</code>
* may callback into the
* <code>FilterBypass</code> multiple times, or for different regions, but
* it should not callback into the <code>FilterBypass</code> after returning
* from the <code>remove</code> or <code>insertString</code> method.
*
* @see javax.swing.text.Document
*
* @version 1.8 04/07/06
* @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 <code>FilterBypass</code> 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 <code>offset</code> to
* <code>offset + length</code>, and replaces it with
* <code>text</code>.
*
* @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;
}
}
|
