View Javadoc
1   /*
2    * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  package javax.swing.text;
26  
27  /**
28   * <code>DocumentFilter</code>, as the name implies, is a filter for the
29   * <code>Document</code> mutation methods. When a <code>Document</code>
30   * containing a <code>DocumentFilter</code> is modified (either through
31   * <code>insert</code> or <code>remove</code>), it forwards the appropriate
32   * method invocation to the <code>DocumentFilter</code>. The
33   * default implementation allows the modification to
34   * occur. Subclasses can filter the modifications by conditionally invoking
35   * methods on the superclass, or invoking the necessary methods on
36   * the passed in <code>FilterBypass</code>. Subclasses should NOT call back
37   * into the Document for the modification
38   * instead call into the superclass or the <code>FilterBypass</code>.
39   * <p>
40   * When <code>remove</code> or <code>insertString</code> is invoked
41   * on the <code>DocumentFilter</code>, the <code>DocumentFilter</code>
42   * may callback into the
43   * <code>FilterBypass</code> multiple times, or for different regions, but
44   * it should not callback into the <code>FilterBypass</code> after returning
45   * from the <code>remove</code> or <code>insertString</code> method.
46   * <p>
47   * By default, text related document mutation methods such as
48   * <code>insertString</code>, <code>replace</code> and <code>remove</code>
49   * in <code>AbstractDocument</code> use <code>DocumentFilter</code> when
50   * available, and <code>Element</code> related mutation methods such as
51   * <code>create</code>, <code>insert</code> and <code>removeElement</code> in
52   * <code>DefaultStyledDocument</code> do not use <code>DocumentFilter</code>.
53   * If a method doesn't follow these defaults, this must be explicitly stated
54   * in the method documentation.
55   *
56   * @see javax.swing.text.Document
57   * @see javax.swing.text.AbstractDocument
58   * @see javax.swing.text.DefaultStyledDocument
59   *
60   * @since 1.4
61   */
62  public class DocumentFilter {
63      /**
64       * Invoked prior to removal of the specified region in the
65       * specified Document. Subclasses that want to conditionally allow
66       * removal should override this and only call supers implementation as
67       * necessary, or call directly into the <code>FilterBypass</code> as
68       * necessary.
69       *
70       * @param fb FilterBypass that can be used to mutate Document
71       * @param offset the offset from the beginning &gt;= 0
72       * @param length the number of characters to remove &gt;= 0
73       * @exception BadLocationException  some portion of the removal range
74       *   was not a valid part of the document.  The location in the exception
75       *   is the first bad position encountered.
76       */
77      public void remove(FilterBypass fb, int offset, int length) throws
78                         BadLocationException {
79          fb.remove(offset, length);
80      }
81  
82      /**
83       * Invoked prior to insertion of text into the
84       * specified Document. Subclasses that want to conditionally allow
85       * insertion should override this and only call supers implementation as
86       * necessary, or call directly into the FilterBypass.
87       *
88       * @param fb FilterBypass that can be used to mutate Document
89       * @param offset  the offset into the document to insert the content &gt;= 0.
90       *    All positions that track change at or after the given location
91       *    will move.
92       * @param string the string to insert
93       * @param attr      the attributes to associate with the inserted
94       *   content.  This may be null if there are no attributes.
95       * @exception BadLocationException  the given insert position is not a
96       *   valid position within the document
97       */
98      public void insertString(FilterBypass fb, int offset, String string,
99                               AttributeSet attr) throws BadLocationException {
100         fb.insertString(offset, string, attr);
101     }
102 
103     /**
104      * Invoked prior to replacing a region of text in the
105      * specified Document. Subclasses that want to conditionally allow
106      * replace should override this and only call supers implementation as
107      * necessary, or call directly into the FilterBypass.
108      *
109      * @param fb FilterBypass that can be used to mutate Document
110      * @param offset Location in Document
111      * @param length Length of text to delete
112      * @param text Text to insert, null indicates no text to insert
113      * @param attrs AttributeSet indicating attributes of inserted text,
114      *              null is legal.
115      * @exception BadLocationException  the given insert position is not a
116      *   valid position within the document
117      */
118     public void replace(FilterBypass fb, int offset, int length, String text,
119                         AttributeSet attrs) throws BadLocationException {
120         fb.replace(offset, length, text, attrs);
121     }
122 
123 
124     /**
125      * Used as a way to circumvent calling back into the Document to
126      * change it. Document implementations that wish to support
127      * a DocumentFilter must provide an implementation that will
128      * not callback into the DocumentFilter when the following methods
129      * are invoked from the DocumentFilter.
130      * @since 1.4
131      */
132     public static abstract class FilterBypass {
133         /**
134          * Returns the Document the mutation is occurring on.
135          *
136          * @return Document that remove/insertString will operate on
137          */
138         public abstract Document getDocument();
139 
140         /**
141          * Removes the specified region of text, bypassing the
142          * DocumentFilter.
143          *
144          * @param offset the offset from the beginning &gt;= 0
145          * @param length the number of characters to remove &gt;= 0
146          * @exception BadLocationException some portion of the removal range
147          *   was not a valid part of the document.  The location in the
148          *   exception is the first bad position encountered.
149          */
150         public abstract void remove(int offset, int length) throws
151                              BadLocationException;
152 
153         /**
154          * Inserts the specified text, bypassing the
155          * DocumentFilter.
156          * @param offset  the offset into the document to insert the
157          *   content &gt;= 0. All positions that track change at or after the
158          *   given location will move.
159          * @param string the string to insert
160          * @param attr the attributes to associate with the inserted
161          *   content.  This may be null if there are no attributes.
162          * @exception BadLocationException  the given insert position is not a
163          *   valid position within the document
164          */
165         public abstract void insertString(int offset, String string,
166                                           AttributeSet attr) throws
167                                    BadLocationException;
168 
169         /**
170          * Deletes the region of text from <code>offset</code> to
171          * <code>offset + length</code>, and replaces it with
172          *  <code>text</code>.
173          *
174          * @param offset Location in Document
175          * @param length Length of text to delete
176          * @param string Text to insert, null indicates no text to insert
177          * @param attrs AttributeSet indicating attributes of inserted text,
178          *              null is legal.
179          * @exception BadLocationException  the given insert is not a
180          *   valid position within the document
181          */
182         public abstract void replace(int offset, int length, String string,
183                                           AttributeSet attrs) throws
184                                    BadLocationException;
185     }
186 }