ojluni/src/main/java/javax/swing/text/DocumentFilter.java - platform/libcore.git - Git at Google

 /*
  * Copyright (c) 2000, 2007, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.  Oracle designates this
  * particular file as subject to the "Classpath" exception as provided
  * by Oracle in the LICENSE file that accompanied this code.
  *
  * This code is distributed in the hope that it will be useful, but WITHOUT
  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  * version 2 for more details (a copy is included in the LICENSE file that
  * accompanied this code).
  *
  * You should have received a copy of the GNU General Public License version
  * 2 along with this work; if not, write to the Free Software Foundation,
  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  *
  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  * or visit www.oracle.com if you need additional information or have any
  * questions.
  */
 package javax.swing.text;

 /**
  * <code>DocumentFilter</code>, as the name implies, is a filter for the
  * <code>Document</code> mutation methods. When a <code>Document</code>
  * containing a <code>DocumentFilter</code> is modified (either through
  * <code>insert</code> or <code>remove</code>), it forwards the appropriate
  * method invocation to the <code>DocumentFilter</code>. The
  * default implementation allows the modification to
  * occur. Subclasses can filter the modifications by conditionally invoking
  * methods on the superclass, or invoking the necessary methods on
  * the passed in <code>FilterBypass</code>. Subclasses should NOT call back
  * into the Document for the modification
  * instead call into the superclass or the <code>FilterBypass</code>.
  * <p>
  * When <code>remove</code> or <code>insertString</code> is invoked
  * on the <code>DocumentFilter</code>, the <code>DocumentFilter</code>
  * may callback into the
  * <code>FilterBypass</code> multiple times, or for different regions, but
  * it should not callback into the <code>FilterBypass</code> after returning
  * from the <code>remove</code> or <code>insertString</code> method.
  * <p>
  * By default, text related document mutation methods such as
  * <code>insertString</code>, <code>replace</code> and <code>remove</code>
  * in <code>AbstractDocument</code> use <code>DocumentFilter</code> when
  * available, and <code>Element</code> related mutation methods such as
  * <code>create</code>, <code>insert</code> and <code>removeElement</code> in
  * <code>DefaultStyledDocument</code> do not use <code>DocumentFilter</code>.
  * If a method doesn't follow these defaults, this must be explicitly stated
  * in the method documentation.
  *
  * @see javax.swing.text.Document
  * @see javax.swing.text.AbstractDocument
  * @see javax.swing.text.DefaultStyledDocument
  *
  * @since 1.4
  */
 public class DocumentFilter {
     /**
      * Invoked prior to removal of the specified region in the
      * specified Document. Subclasses that want to conditionally allow
      * removal should override this and only call supers implementation as
      * necessary, or call directly into the <code>FilterBypass</code> as
      * necessary.
      *
      * @param fb FilterBypass that can be used to mutate Document
      * @param offset the offset from the beginning >= 0
      * @param length the number of characters to remove >= 0
      * @exception BadLocationException  some portion of the removal range
      *   was not a valid part of the document.  The location in the exception
      *   is the first bad position encountered.
      */
     public void remove(FilterBypass fb, int offset, int length) throws
                        BadLocationException {
         fb.remove(offset, length);
     }

     /**
      * Invoked prior to insertion of text into the
      * specified Document. Subclasses that want to conditionally allow
      * insertion should override this and only call supers implementation as
      * necessary, or call directly into the FilterBypass.
      *
      * @param fb FilterBypass that can be used to mutate Document
      * @param offset  the offset into the document to insert the content >= 0.
      *    All positions that track change at or after the given location
      *    will move.
      * @param string the string to insert
      * @param attr      the attributes to associate with the inserted
      *   content.  This may be null if there are no attributes.
      * @exception BadLocationException  the given insert position is not a
      *   valid position within the document
      */
     public void insertString(FilterBypass fb, int offset, String string,
                              AttributeSet attr) throws BadLocationException {
         fb.insertString(offset, string, attr);
     }

     /**
      * Invoked prior to replacing a region of text in the
      * specified Document. Subclasses that want to conditionally allow
      * replace should override this and only call supers implementation as
      * necessary, or call directly into the FilterBypass.
      *
      * @param fb FilterBypass that can be used to mutate Document
      * @param offset Location in Document
      * @param length Length of text to delete
      * @param text Text to insert, null indicates no text to insert
      * @param attrs AttributeSet indicating attributes of inserted text,
      *              null is legal.
      * @exception BadLocationException  the given insert position is not a
      *   valid position within the document
      */
     public void replace(FilterBypass fb, int offset, int length, String text,
                         AttributeSet attrs) throws BadLocationException {
         fb.replace(offset, length, text, attrs);
     }


     /**
      * Used as a way to circumvent calling back into the Document to
      * change it. Document implementations that wish to support
      * a DocumentFilter must provide an implementation that will
      * not callback into the DocumentFilter when the following methods
      * are invoked from the DocumentFilter.
      * @since 1.4
      */
     public static abstract class FilterBypass {
         /**
          * Returns the Document the mutation is occuring on.
          *
          * @return Document that remove/insertString will operate on
          */
         public abstract Document getDocument();

         /**
          * Removes the specified region of text, bypassing the
          * DocumentFilter.
          *
          * @param offset the offset from the beginning >= 0
          * @param length the number of characters to remove >= 0
          * @exception BadLocationException some portion of the removal range
          *   was not a valid part of the document.  The location in the
          *   exception is the first bad position encountered.
          */
         public abstract void remove(int offset, int length) throws
                              BadLocationException;

         /**
          * Inserts the specified text, bypassing the
          * DocumentFilter.
          * @param offset  the offset into the document to insert the
          *   content >= 0. All positions that track change at or after the
          *   given location will move.
          * @param string the string to insert
          * @param attr the attributes to associate with the inserted
          *   content.  This may be null if there are no attributes.
          * @exception BadLocationException  the given insert position is not a
          *   valid position within the document
          */
         public abstract void insertString(int offset, String string,
                                           AttributeSet attr) throws
                                    BadLocationException;

         /**
          * Deletes the region of text from <code>offset</code> to
          * <code>offset + length</code>, and replaces it with
          *  <code>text</code>.
          *
          * @param offset Location in Document
          * @param length Length of text to delete
          * @param string Text to insert, null indicates no text to insert
          * @param attrs AttributeSet indicating attributes of inserted text,
          *              null is legal.
          * @exception BadLocationException  the given insert is not a
          *   valid position within the document
          */
         public abstract void replace(int offset, int length, String string,
                                           AttributeSet attrs) throws
                                    BadLocationException;
     }
 }
	/*
	* Copyright (c) 2000, 2007, Oracle and/or its affiliates. All rights reserved.
	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
	*
	* This code is free software; you can redistribute it and/or modify it
	* under the terms of the GNU General Public License version 2 only, as
	* published by the Free Software Foundation. Oracle designates this
	* particular file as subject to the "Classpath" exception as provided
	* by Oracle in the LICENSE file that accompanied this code.
	*
	* This code is distributed in the hope that it will be useful, but WITHOUT
	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	* version 2 for more details (a copy is included in the LICENSE file that
	* accompanied this code).
	*
	* You should have received a copy of the GNU General Public License version
	* 2 along with this work; if not, write to the Free Software Foundation,
	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
	*
	* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	* or visit www.oracle.com if you need additional information or have any
	* questions.
	*/
	package javax.swing.text;

	/**
	* <code>DocumentFilter</code>, as the name implies, is a filter for the
	* <code>Document</code> mutation methods. When a <code>Document</code>
	* containing a <code>DocumentFilter</code> is modified (either through
	* <code>insert</code> or <code>remove</code>), it forwards the appropriate
	* method invocation to the <code>DocumentFilter</code>. The
	* default implementation allows the modification to
	* occur. Subclasses can filter the modifications by conditionally invoking
	* methods on the superclass, or invoking the necessary methods on
	* the passed in <code>FilterBypass</code>. Subclasses should NOT call back
	* into the Document for the modification
	* instead call into the superclass or the <code>FilterBypass</code>.
	* <p>
	* When <code>remove</code> or <code>insertString</code> is invoked
	* on the <code>DocumentFilter</code>, the <code>DocumentFilter</code>
	* may callback into the
	* <code>FilterBypass</code> multiple times, or for different regions, but
	* it should not callback into the <code>FilterBypass</code> after returning
	* from the <code>remove</code> or <code>insertString</code> method.
	* <p>
	* By default, text related document mutation methods such as
	* <code>insertString</code>, <code>replace</code> and <code>remove</code>
	* in <code>AbstractDocument</code> use <code>DocumentFilter</code> when
	* available, and <code>Element</code> related mutation methods such as
	* <code>create</code>, <code>insert</code> and <code>removeElement</code> in
	* <code>DefaultStyledDocument</code> do not use <code>DocumentFilter</code>.
	* If a method doesn't follow these defaults, this must be explicitly stated
	* in the method documentation.
	*
	* @see javax.swing.text.Document
	* @see javax.swing.text.AbstractDocument
	* @see javax.swing.text.DefaultStyledDocument
	*
	* @since 1.4
	*/
	public class DocumentFilter {
	/**
	* Invoked prior to removal of the specified region in the
	* specified Document. Subclasses that want to conditionally allow
	* removal should override this and only call supers implementation as
	* necessary, or call directly into the <code>FilterBypass</code> as
	* necessary.
	*
	* @param fb FilterBypass that can be used to mutate Document
	* @param offset the offset from the beginning >= 0
	* @param length the number of characters to remove >= 0
	* @exception BadLocationException some portion of the removal range
	* was not a valid part of the document. The location in the exception
	* is the first bad position encountered.
	*/
	public void remove(FilterBypass fb, int offset, int length) throws
	BadLocationException {
	fb.remove(offset, length);
	}

	/**
	* Invoked prior to insertion of text into the
	* specified Document. Subclasses that want to conditionally allow
	* insertion should override this and only call supers implementation as
	* necessary, or call directly into the FilterBypass.
	*
	* @param fb FilterBypass that can be used to mutate Document
	* @param offset the offset into the document to insert the content >= 0.
	* All positions that track change at or after the given location
	* will move.
	* @param string the string to insert
	* @param attr the attributes to associate with the inserted
	* content. This may be null if there are no attributes.
	* @exception BadLocationException the given insert position is not a
	* valid position within the document
	*/
	public void insertString(FilterBypass fb, int offset, String string,
	AttributeSet attr) throws BadLocationException {
	fb.insertString(offset, string, attr);
	}

	/**
	* Invoked prior to replacing a region of text in the
	* specified Document. Subclasses that want to conditionally allow
	* replace should override this and only call supers implementation as
	* necessary, or call directly into the FilterBypass.
	*
	* @param fb FilterBypass that can be used to mutate Document
	* @param offset Location in Document
	* @param length Length of text to delete
	* @param text Text to insert, null indicates no text to insert
	* @param attrs AttributeSet indicating attributes of inserted text,
	* null is legal.
	* @exception BadLocationException the given insert position is not a
	* valid position within the document
	*/
	public void replace(FilterBypass fb, int offset, int length, String text,
	AttributeSet attrs) throws BadLocationException {
	fb.replace(offset, length, text, attrs);
	}


	/**
	* Used as a way to circumvent calling back into the Document to
	* change it. Document implementations that wish to support
	* a DocumentFilter must provide an implementation that will
	* not callback into the DocumentFilter when the following methods
	* are invoked from the DocumentFilter.
	* @since 1.4
	*/
	public static abstract class FilterBypass {
	/**
	* Returns the Document the mutation is occuring on.
	*
	* @return Document that remove/insertString will operate on
	*/
	public abstract Document getDocument();

	/**
	* Removes the specified region of text, bypassing the
	* DocumentFilter.
	*
	* @param offset the offset from the beginning >= 0
	* @param length the number of characters to remove >= 0
	* @exception BadLocationException some portion of the removal range
	* was not a valid part of the document. The location in the
	* exception is the first bad position encountered.
	*/
	public abstract void remove(int offset, int length) throws
	BadLocationException;

	/**
	* Inserts the specified text, bypassing the
	* DocumentFilter.
	* @param offset the offset into the document to insert the
	* content >= 0. All positions that track change at or after the
	* given location will move.
	* @param string the string to insert
	* @param attr the attributes to associate with the inserted
	* content. This may be null if there are no attributes.
	* @exception BadLocationException the given insert position is not a
	* valid position within the document
	*/
	public abstract void insertString(int offset, String string,
	AttributeSet attr) throws
	BadLocationException;

	/**
	* Deletes the region of text from <code>offset</code> to
	* <code>offset + length</code>, and replaces it with
	* <code>text</code>.
	*
	* @param offset Location in Document
	* @param length Length of text to delete
	* @param string Text to insert, null indicates no text to insert
	* @param attrs AttributeSet indicating attributes of inserted text,
	* null is legal.
	* @exception BadLocationException the given insert is not a
	* valid position within the document
	*/
	public abstract void replace(int offset, int length, String string,
	AttributeSet attrs) throws
	BadLocationException;
	}
	}