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