1. /*
  2. * @(#)Caret.java 1.29 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.Graphics;
  9. import java.awt.Point;
  10. import javax.swing.Action;
  11. import javax.swing.event.ChangeListener;
  12. /**
  13. * A place within a document view that represents where
  14. * things can be inserted into the document model. A caret
  15. * has a position in the document referred to as a dot.
  16. * The dot is where the caret is currently located in the
  17. * model. There is
  18. * a second position maintained by the caret that represents
  19. * the other end of a selection called mark. If there is
  20. * no selection the dot and mark will be equal. If a selection
  21. * exists, the two values will be different.
  22. * <p>
  23. * The dot can be placed by either calling
  24. * <code>setDot</code> or <code>moveDot</code>. Setting
  25. * the dot has the effect of removing any selection that may
  26. * have previously existed. The dot and mark will be equal.
  27. * Moving the dot has the effect of creating a selection as
  28. * the mark is left at whatever position it previously had.
  29. *
  30. * @author Timothy Prinzing
  31. * @version 1.29 01/23/03
  32. */
  33. public interface Caret {
  34. /**
  35. * Called when the UI is being installed into the
  36. * interface of a JTextComponent. This can be used
  37. * to gain access to the model that is being navigated
  38. * by the implementation of this interface.
  39. *
  40. * @param c the JTextComponent
  41. */
  42. public void install(JTextComponent c);
  43. /**
  44. * Called when the UI is being removed from the
  45. * interface of a JTextComponent. This is used to
  46. * unregister any listeners that were attached.
  47. *
  48. * @param c the JTextComponent
  49. */
  50. public void deinstall(JTextComponent c);
  51. /**
  52. * Renders the caret.
  53. *
  54. * @param g the graphics context
  55. */
  56. public void paint(Graphics g);
  57. /**
  58. * Adds a listener to track whenever the caret position
  59. * has been changed.
  60. *
  61. * @param l the change listener
  62. */
  63. public void addChangeListener(ChangeListener l);
  64. /**
  65. * Removes a listener that was tracking caret position changes.
  66. *
  67. * @param l the change listener
  68. */
  69. public void removeChangeListener(ChangeListener l);
  70. /**
  71. * Determines if the caret is currently visible.
  72. *
  73. * @return true if the caret is visible else false
  74. */
  75. public boolean isVisible();
  76. /**
  77. * Sets the visibility of the caret.
  78. *
  79. * @param v true if the caret should be shown,
  80. * and false if the caret should be hidden
  81. */
  82. public void setVisible(boolean v);
  83. /**
  84. * Determines if the selection is currently visible.
  85. *
  86. * @return true if the caret is visible else false
  87. */
  88. public boolean isSelectionVisible();
  89. /**
  90. * Sets the visibility of the selection
  91. *
  92. * @param v true if the caret should be shown,
  93. * and false if the caret should be hidden
  94. */
  95. public void setSelectionVisible(boolean v);
  96. /**
  97. * Set the current caret visual location. This can be used when
  98. * moving between lines that have uneven end positions (such as
  99. * when caret up or down actions occur). If text flows
  100. * left-to-right or right-to-left the x-coordinate will indicate
  101. * the desired navigation location for vertical movement. If
  102. * the text flow is top-to-bottom, the y-coordinate will indicate
  103. * the desired navigation location for horizontal movement.
  104. *
  105. * @param p the Point to use for the saved position. This
  106. * can be null to indicate there is no visual location.
  107. */
  108. public void setMagicCaretPosition(Point p);
  109. /**
  110. * Gets the current caret visual location.
  111. *
  112. * @return the visual position.
  113. * @see #setMagicCaretPosition
  114. */
  115. public Point getMagicCaretPosition();
  116. /**
  117. * Sets the blink rate of the caret. This determines if
  118. * and how fast the caret blinks, commonly used as one
  119. * way to attract attention to the caret.
  120. *
  121. * @param rate the delay in milliseconds >= 0. If this is
  122. * zero the caret will not blink.
  123. */
  124. public void setBlinkRate(int rate);
  125. /**
  126. * Gets the blink rate of the caret. This determines if
  127. * and how fast the caret blinks, commonly used as one
  128. * way to attract attention to the caret.
  129. *
  130. * @return the delay in milliseconds >= 0. If this is
  131. * zero the caret will not blink.
  132. */
  133. public int getBlinkRate();
  134. /**
  135. * Fetches the current position of the caret.
  136. *
  137. * @return the position >= 0
  138. */
  139. public int getDot();
  140. /**
  141. * Fetches the current position of the mark. If there
  142. * is a selection, the mark will not be the same as
  143. * the dot.
  144. *
  145. * @return the position >= 0
  146. */
  147. public int getMark();
  148. /**
  149. * Sets the caret position to some position. This
  150. * causes the mark to become the same as the dot,
  151. * effectively setting the selection range to zero.
  152. *
  153. * @param dot the new position to set the caret to >= 0
  154. */
  155. public void setDot(int dot);
  156. /**
  157. * Moves the caret position (dot) to some other position,
  158. * leaving behind the mark. This is useful for
  159. * making selections.
  160. *
  161. * @param dot the new position to move the caret to >= 0
  162. */
  163. public void moveDot(int dot);
  164. };