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