/*

 * 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;

/**

 * <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 <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 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 <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;

    }

}