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

    1   /*
    2    * Copyright (c) 2000, 2006, 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   import java.awt.Shape;
   28   
   29   /**
   30    * <code>NavigationFilter</code> can be used to restrict where the cursor can
   31    * be positioned. When the default cursor positioning actions attempt to
   32    * reposition the cursor they will call into the
   33    * <code>NavigationFilter</code>, assuming
   34    * the <code>JTextComponent</code> has a non-null
   35    * <code>NavigationFilter</code> set. In this manner
   36    * the <code>NavigationFilter</code> can effectively restrict where the
   37    * cursor can be positioned. Similarly <code>DefaultCaret</code> will call
   38    * into the <code>NavigationFilter</code> when the user is changing the
   39    * selection to further restrict where the cursor can be positioned.
   40    * <p>
   41    * Subclasses can conditionally call into supers implementation to restrict
   42    * where the cursor can be placed, or call directly into the
   43    * <code>FilterBypass</code>.
   44    *
   45    * @see javax.swing.text.Caret
   46    * @see javax.swing.text.DefaultCaret
   47    * @see javax.swing.text.View
   48    *
   49    * @since 1.4
   50    */
   51   public class NavigationFilter {
   52       /**
   53        * Invoked prior to the Caret setting the dot. The default implementation
   54        * calls directly into the <code>FilterBypass</code> with the passed
   55        * in arguments. Subclasses may wish to conditionally
   56        * call super with a different location, or invoke the necessary method
   57        * on the <code>FilterBypass</code>
   58        *
   59        * @param fb FilterBypass that can be used to mutate caret position
   60        * @param dot the position >= 0
   61        * @param bias Bias to place the dot at
   62        */
   63       public void setDot(FilterBypass fb, int dot, Position.Bias bias) {
   64           fb.setDot(dot, bias);
   65       }
   66   
   67       /**
   68        * Invoked prior to the Caret moving the dot. The default implementation
   69        * calls directly into the <code>FilterBypass</code> with the passed
   70        * in arguments. Subclasses may wish to conditionally
   71        * call super with a different location, or invoke the necessary
   72        * methods on the <code>FilterBypass</code>.
   73        *
   74        * @param fb FilterBypass that can be used to mutate caret position
   75        * @param dot the position >= 0
   76        * @param bias Bias for new location
   77        */
   78       public void moveDot(FilterBypass fb, int dot, Position.Bias bias) {
   79           fb.moveDot(dot, bias);
   80       }
   81   
   82       /**
   83        * Returns the next visual position to place the caret at from an
   84        * existing position. The default implementation simply forwards the
   85        * method to the root View. Subclasses may wish to further restrict the
   86        * location based on additional criteria.
   87        *
   88        * @param text JTextComponent containing text
   89        * @param pos Position used in determining next position
   90        * @param bias Bias used in determining next position
   91        * @param direction the direction from the current position that can
   92        *  be thought of as the arrow keys typically found on a keyboard.
   93        *  This will be one of the following values:
   94        * <ul>
   95        * <li>SwingConstants.WEST
   96        * <li>SwingConstants.EAST
   97        * <li>SwingConstants.NORTH
   98        * <li>SwingConstants.SOUTH
   99        * </ul>
  100        * @param biasRet Used to return resulting Bias of next position
  101        * @return the location within the model that best represents the next
  102        *  location visual position
  103        * @exception BadLocationException
  104        * @exception IllegalArgumentException if <code>direction</code>
  105        *          doesn't have one of the legal values above
  106        */
  107       public int getNextVisualPositionFrom(JTextComponent text, int pos,
  108                                            Position.Bias bias, int direction,
  109                                            Position.Bias[] biasRet)
  110                                              throws BadLocationException {
  111           return text.getUI().getNextVisualPositionFrom(text, pos, bias,
  112                                                         direction, biasRet);
  113       }
  114   
  115   
  116       /**
  117        * Used as a way to circumvent calling back into the caret to
  118        * position the cursor. Caret implementations that wish to support
  119        * a NavigationFilter must provide an implementation that will
  120        * not callback into the NavigationFilter.
  121        * @since 1.4
  122        */
  123       public static abstract class FilterBypass {
  124           /**
  125            * Returns the Caret that is changing.
  126            *
  127            * @return Caret that is changing
  128            */
  129           public abstract Caret getCaret();
  130   
  131           /**
  132            * Sets the caret location, bypassing the NavigationFilter.
  133            *
  134            * @param dot the position >= 0
  135            * @param bias Bias to place the dot at
  136            */
  137           public abstract void setDot(int dot, Position.Bias bias);
  138   
  139           /**
  140            * Moves the caret location, bypassing the NavigationFilter.
  141            *
  142            * @param dot the position >= 0
  143            * @param bias Bias for new location
  144            */
  145           public abstract void moveDot(int dot, Position.Bias bias);
  146       }
  147   }

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