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 >= 0 72 * @param length the number of characters to remove >= 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 >= 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 abstract static 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 >= 0 145 * @param length the number of characters to remove >= 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 >= 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 } --- EOF ---