/*
* 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 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 abstract static class FilterBypass {
/**
* 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.
*
* @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;
}
}