1. /*

  2.  * @(#)DocumentFilter.java	1.5 03/01/23

  3.  *

  4.  * Copyright 2003 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. package javax.swing.text;

  8. 

  9. /**

  10.  * <code>DocumentFilter</code>, as the name implies, is a filter for the

  11.  * <code>Document</code> mutation methods. When a <code>Document</code>

  12.  * containing a <code>DocumentFilter</code> is modified (either through

  13.  * <code>insert</code> or <code>remove</code>), it forwards the appropriate

  14.  * method invocation to the <code>DocumentFilter</code>. The

  15.  * default implementation allows the modification to

  16.  * occur. Subclasses can filter the modifications by conditionally invoking

  17.  * methods on the superclass, or invoking the necessary methods on

  18.  * the passed in <code>FilterBypass</code>. Subclasses should NOT call back

  19.  * into the Document for the modification

  20.  * instead call into the superclass or the <code>FilterBypass</code>.

  21.  * <p>

  22.  * When <code>remove</code> or <code>insertString</code> is invoked

  23.  * on the <code>DocumentFilter</code>, the <code>DocumentFilter</code>

  24.  * may callback into the

  25.  * <code>FilterBypass</code> multiple times, or for different regions, but

  26.  * it should not callback into the <code>FilterBypass</code> after returning

  27.  * from the <code>remove</code> or <code>insertString</code> method.

  28.  *

  29.  * @see javax.swing.text.Document

  30.  *

  31.  * @version 1.5 01/23/03

  32.  * @since 1.4

  33.  */

  34. public class DocumentFilter {

  35.     /**

  36.      * Invoked prior to removal of the specified region in the

  37.      * specified Document. Subclasses that want to conditionally allow

  38.      * removal should override this and only call supers implementation as

  39.      * necessary, or call directly into the <code>FilterBypass</code> as

  40.      * necessary.

  41.      *

  42.      * @param fb FilterBypass that can be used to mutate Document

  43.      * @param offset the offset from the beginning >= 0

  44.      * @param length the number of characters to remove >= 0

  45.      * @exception BadLocationException  some portion of the removal range

  46.      *   was not a valid part of the document.  The location in the exception

  47.      *   is the first bad position encountered.

  48.      */

  49.     public void remove(FilterBypass fb, int offset, int length) throws

  50.                        BadLocationException {

  51.         fb.remove(offset, length);

  52.     }

  53. 

  54.     /**

  55.      * Invoked prior to insertion of text into the

  56.      * specified Document. Subclasses that want to conditionally allow

  57.      * insertion should override this and only call supers implementation as

  58.      * necessary, or call directly into the FilterBypass.

  59.      *

  60.      * @param fb FilterBypass that can be used to mutate Document

  61.      * @param offset  the offset into the document to insert the content >= 0.

  62.      *    All positions that track change at or after the given location 

  63.      *    will move.  

  64.      * @param string the string to insert

  65.      * @param attr      the attributes to associate with the inserted

  66.      *   content.  This may be null if there are no attributes.

  67.      * @exception BadLocationException  the given insert position is not a

  68.      *   valid position within the document

  69.      */

  70.     public void insertString(FilterBypass fb, int offset, String string,

  71.                              AttributeSet attr) throws BadLocationException {

  72.         fb.insertString(offset, string, attr);

  73.     }

  74. 

  75.     /**

  76.      * Invoked prior to replacing a region of text in the

  77.      * specified Document. Subclasses that want to conditionally allow

  78.      * replace should override this and only call supers implementation as

  79.      * necessary, or call directly into the FilterBypass.

  80.      *

  81.      * @param fb FilterBypass that can be used to mutate Document

  82.      * @param offset Location in Document

  83.      * @param length Length of text to delete

  84.      * @param text Text to insert, null indicates no text to insert

  85.      * @param attrs AttributeSet indicating attributes of inserted text,

  86.      *              null is legal.

  87.      * @exception BadLocationException  the given insert position is not a

  88.      *   valid position within the document

  89.      */

  90.     public void replace(FilterBypass fb, int offset, int length, String text,

  91.                         AttributeSet attrs) throws BadLocationException {

  92.         fb.replace(offset, length, text, attrs);

  93.     }

  94. 

  95. 

  96.     /**

  97.      * Used as a way to circumvent calling back into the Document to

  98.      * change it. Document implementations that wish to support

  99.      * a DocumentFilter must provide an implementation that will

  100.      * not callback into the DocumentFilter when the following methods

  101.      * are invoked from the DocumentFilter.

  102.      */

  103.     public static abstract class FilterBypass {

  104.         /**

  105.          * Returns the Document the mutation is occuring on.

  106.          *

  107.          * @return Document that remove/insertString will operate on

  108.          */

  109.         public abstract Document getDocument();

  110. 

  111.         /**

  112.          * Removes the specified region of text, bypassing the

  113.          * DocumentFilter.

  114.          *

  115.          * @param offset the offset from the beginning >= 0

  116.          * @param length the number of characters to remove >= 0

  117.          * @exception BadLocationException some portion of the removal range

  118.          *   was not a valid part of the document.  The location in the

  119.          *   exception is the first bad position encountered.

  120.          */

  121.         public abstract void remove(int offset, int length) throws

  122.                              BadLocationException;

  123. 

  124.         /**

  125.          * Inserts the specified text, bypassing the

  126.          * DocumentFilter.

  127.          * @param offset  the offset into the document to insert the

  128.          *   content >= 0. All positions that track change at or after the

  129.          *   given location will move.  

  130.          * @param string the string to insert

  131.          * @param attr the attributes to associate with the inserted

  132.          *   content.  This may be null if there are no attributes.

  133.          * @exception BadLocationException  the given insert position is not a

  134.          *   valid position within the document

  135.          */

  136.         public abstract void insertString(int offset, String string,

  137.                                           AttributeSet attr) throws

  138.                                    BadLocationException;

  139. 

  140.         /**

  141.          * Deletes the region of text from <code>offset</code> to

  142.          * <code>offset + length</code>, and replaces it with

  143.          *  <code>text</code>.

  144.          *

  145.          * @param offset Location in Document

  146.          * @param length Length of text to delete

  147.          * @param string Text to insert, null indicates no text to insert

  148.          * @param attrs AttributeSet indicating attributes of inserted text,

  149.          *              null is legal.

  150.          * @exception BadLocationException  the given insert is not a

  151.          *   valid position within the document

  152.          */

  153.         public abstract void replace(int offset, int length, String string,

  154.                                           AttributeSet attrs) throws

  155.                                    BadLocationException;

  156.     }

  157. }