NavigationFilter


1   /*
2    * @(#)NavigationFilter.java    1.4 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   package javax.swing.text;
8   
9   import java.awt.Shape  ;
10  
11  /**
12   * <code>NavigationFilter</code> can be used to restrict where the cursor can
13   * be positioned. When the default cursor positioning actions attempt to
14   * reposition the cursor they will call into the
15   * <code>NavigationFilter</code>, assuming
16   * the <code>JTextComponent</code> has a non-null
17   * <code>NavigationFilter</code> set. In this manner
18   * the <code>NavigationFilter</code> can effectively restrict where the
19   * cursor can be positioned. Similarly <code>DefaultCaret</code> will call
20   * into the <code>NavigationFilter</code> when the user is changing the
21   * selection to further restrict where the cursor can be positioned.
22   * <p>
23   * Subclasses can conditionally call into supers implementation to restrict
24   * where the cursor can be placed, or call directly into the
25   * <code>FilterBypass</code>.
26   *
27   * @see javax.swing.text.Caret
28   * @see javax.swing.text.DefaultCaret
29   * @see javax.swing.text.View
30   *
31   * @version 1.4 12/19/03
32   * @since 1.4
33   */
34  public class NavigationFilter {
35      /**
36       * Invoked prior to the Caret setting the dot. The default implementation
37       * calls directly into the <code>FilterBypass</code> with the passed
38       * in arguments. Subclasses may wish to conditionally
39       * call super with a different location, or invoke the necessary method
40       * on the <code>FilterBypass</code>
41       *
42       * @param fb FilterBypass that can be used to mutate caret position
43       * @param dot the position >= 0
44       * @param bias Bias to place the dot at
45       */
46      public void setDot(FilterBypass fb, int dot, Position.Bias   bias) {
47          fb.setDot(dot, bias);
48      }
49  
50      /**
51       * Invoked prior to the Caret moving the dot. The default implementation
52       * calls directly into the <code>FilterBypass</code> with the passed
53       * in arguments. Subclasses may wish to conditionally
54       * call super with a different location, or invoke the necessary
55       * methods on the <code>FilterBypass</code>.
56       *
57       * @param fb FilterBypass that can be used to mutate caret position
58       * @param dot the position >= 0
59       * @param bias Bias for new location
60       */
61      public void moveDot(FilterBypass fb, int dot, Position.Bias   bias) {
62          fb.moveDot(dot, bias);
63      }
64  
65      /**
66       * Returns the next visual position to place the caret at from an
67       * existing position. The default implementation simply forwards the
68       * method to the root View. Subclasses may wish to further restrict the
69       * location based on additional criteria.
70       *
71       * @param text JTextComponent containing text
72       * @param pos Position used in determining next position
73       * @param bias Bias used in determining next position
74       * @param direction the direction from the current position that can
75       *  be thought of as the arrow keys typically found on a keyboard.
76       *  This will be one of the following values:
77       * <ul>
78       * <li>SwingConstants.WEST
79       * <li>SwingConstants.EAST
80       * <li>SwingConstants.NORTH
81       * <li>SwingConstants.SOUTH
82       * </ul>
83       * @param biasRet Used to return resulting Bias of next position
84       * @return the location within the model that best represents the next
85       *  location visual position
86       * @exception BadLocationException
87       * @exception IllegalArgumentException if <code>direction</code>
88       *      doesn't have one of the legal values above
89       */
90      public int getNextVisualPositionFrom(JTextComponent   text, int pos,
91                                           Position.Bias   bias, int direction,
92                                           Position.Bias  [] biasRet)
93                                             throws BadLocationException   {
94          return text.getUI().getNextVisualPositionFrom(text, pos, bias,
95                                                        direction, biasRet);
96      }
97  
98  
99      /**
100      * Used as a way to circumvent calling back into the caret to
101      * position the cursor. Caret implementations that wish to support
102      * a NavigationFilter must provide an implementation that will
103      * not callback into the NavigationFilter.
104      */
105     public static abstract class FilterBypass {
106         /**
107          * Returns the Caret that is changing.
108          *
109          * @return Caret that is changing
110          */
111         public abstract Caret   getCaret();
112 
113         /**
114          * Sets the caret location, bypassing the NavigationFilter.
115          *
116          * @param dot the position >= 0
117          * @param bias Bias to place the dot at
118          */
119         public abstract void setDot(int dot, Position.Bias   bias);
120 
121         /**
122          * Moves the caret location, bypassing the NavigationFilter.
123          *
124          * @param dot the position >= 0
125          * @param bias Bias for new location
126          */
127         public abstract void moveDot(int dot, Position.Bias   bias);
128     }
129 }
130
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags