/*
* Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package javax.swing.text;
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 Also: Since: 1.4
/**
* <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.
* <p>
* By default, text related document mutation methods such as
* <code>insertString</code>, <code>replace</code> and <code>remove</code>
* in <code>AbstractDocument</code> use <code>DocumentFilter</code> when
* available, and <code>Element</code> related mutation methods such as
* <code>create</code>, <code>insert</code> and <code>removeElement</code> in
* <code>DefaultStyledDocument</code> do not use <code>DocumentFilter</code>.
* 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.
Params: - fb – FilterBypass that can be used to mutate Document
- offset – the offset from the beginning >= 0
- length – the number of characters to remove >= 0
Throws: - 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.
/**
* 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.
Params: - fb – FilterBypass that can be used to mutate Document
- offset – the offset into the document to insert the content >= 0.
All positions that track change at or after the given location
will move.
- string – the string to insert
- attr – the attributes to associate with the inserted
content. This may be null if there are no attributes.
Throws: - BadLocationException – the given insert position is not a
valid position within the document
/**
* 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.
Params: - fb – FilterBypass that can be used to mutate Document
- offset – Location in Document
- length – Length of text to delete
- text – Text to insert, null indicates no text to insert
- attrs – AttributeSet indicating attributes of inserted text,
null is legal.
Throws: - BadLocationException – the given insert position is not a
valid position within the document
/**
* 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
/**
* 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 occurring on.
Returns: Document that remove/insertString will operate on
/**
* Returns the Document the mutation is occurring on.
*
* @return Document that remove/insertString will operate on
*/
public abstract Document getDocument();
Removes the specified region of text, bypassing the
DocumentFilter.
Params: - offset – the offset from the beginning >= 0
- length – the number of characters to remove >= 0
Throws: - 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.
/**
* 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.
Params: - offset – the offset into the document to insert the
content >= 0. All positions that track change at or after the
given location will move.
- string – the string to insert
- attr – the attributes to associate with the inserted
content. This may be null if there are no attributes.
Throws: - BadLocationException – the given insert position is not a
valid position within the document
/**
* 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.
Params: - offset – Location in Document
- length – Length of text to delete
- string – Text to insert, null indicates no text to insert
- attrs – AttributeSet indicating attributes of inserted text,
null is legal.
Throws: - BadLocationException – the given insert is not a
valid position within the document
/**
* 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;
}
}