Home » openjdk-7 » javax » swing » text » [javadoc | source]

    1   /*
    2    * Copyright (c) 2000, 2007, 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 static abstract class FilterBypass {
  133           /**
  134            * Returns the Document the mutation is occuring 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   }

Home » openjdk-7 » javax » swing » text » [javadoc | source]