DocumentFilter


1   /*
2    * @(#)DocumentFilter.java  1.6 03/12/19
3    *
4    * Copyright 2004 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.6 12/19/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 }
158
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags