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 * 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 } | 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}, as the name implies, is a filter for the 29 * {@code Document} mutation methods. When a {@code Document} 30 * containing a {@code DocumentFilter} is modified (either through 31 * {@code insert} or {@code remove}), it forwards the appropriate 32 * method invocation to the {@code DocumentFilter}. 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}. Subclasses should NOT call back 37 * into the Document for the modification 38 * instead call into the superclass or the {@code FilterBypass}. 39 * <p> 40 * When {@code remove} or {@code insertString} is invoked 41 * on the {@code DocumentFilter}, the {@code DocumentFilter} 42 * may callback into the 43 * {@code FilterBypass} multiple times, or for different regions, but 44 * it should not callback into the {@code FilterBypass} after returning 45 * from the {@code remove} or {@code insertString} method. 46 * <p> 47 * By default, text related document mutation methods such as 48 * {@code insertString}, {@code replace} and {@code remove} 49 * in {@code AbstractDocument} use {@code DocumentFilter} when 50 * available, and {@code Element} related mutation methods such as 51 * {@code create}, {@code insert} and {@code removeElement} in 52 * {@code DefaultStyledDocument} do not use {@code DocumentFilter}. 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} 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 * 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} to 171 * {@code offset + length}, and replaces it with 172 * {@code text}. 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 } |