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