< prev index next >

src/java.desktop/share/classes/javax/swing/text/DocumentFilter.java

Print this page




   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      *


 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 }


   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 &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      *


 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} 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 }
< prev index next >