J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 1 | /* |
| 2 | * Copyright 1997-2006 Sun Microsystems, Inc. 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. Sun designates this |
| 8 | * particular file as subject to the "Classpath" exception as provided |
| 9 | * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
| 22 | * CA 95054 USA or visit www.sun.com if you need additional information or |
| 23 | * have any questions. |
| 24 | */ |
| 25 | package javax.swing.text; |
| 26 | |
| 27 | import java.awt.Graphics; |
| 28 | import java.awt.Point; |
| 29 | import javax.swing.Action; |
| 30 | import 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 | */ |
| 52 | public 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 | }; |