001 /*
002 * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025 package javax.swing.text;
026
027 import java.awt.Graphics;
028 import java.awt.Point;
029 import javax.swing.Action;
030 import javax.swing.event.ChangeListener;
031
032 /**
033 * A place within a document view that represents where
034 * things can be inserted into the document model. A caret
035 * has a position in the document referred to as a dot.
036 * The dot is where the caret is currently located in the
037 * model. There is
038 * a second position maintained by the caret that represents
039 * the other end of a selection called mark. If there is
040 * no selection the dot and mark will be equal. If a selection
041 * exists, the two values will be different.
042 * <p>
043 * The dot can be placed by either calling
044 * <code>setDot</code> or <code>moveDot</code>. Setting
045 * the dot has the effect of removing any selection that may
046 * have previously existed. The dot and mark will be equal.
047 * Moving the dot has the effect of creating a selection as
048 * the mark is left at whatever position it previously had.
049 *
050 * @author Timothy Prinzing
051 * @version 1.38 05/05/07
052 */
053 public interface Caret {
054
055 /**
056 * Called when the UI is being installed into the
057 * interface of a JTextComponent. This can be used
058 * to gain access to the model that is being navigated
059 * by the implementation of this interface.
060 *
061 * @param c the JTextComponent
062 */
063 public void install(JTextComponent c);
064
065 /**
066 * Called when the UI is being removed from the
067 * interface of a JTextComponent. This is used to
068 * unregister any listeners that were attached.
069 *
070 * @param c the JTextComponent
071 */
072 public void deinstall(JTextComponent c);
073
074 /**
075 * Renders the caret. This method is called by UI classes.
076 *
077 * @param g the graphics context
078 */
079 public void paint(Graphics g);
080
081 /**
082 * Adds a listener to track whenever the caret position
083 * has been changed.
084 *
085 * @param l the change listener
086 */
087 public void addChangeListener(ChangeListener l);
088
089 /**
090 * Removes a listener that was tracking caret position changes.
091 *
092 * @param l the change listener
093 */
094 public void removeChangeListener(ChangeListener l);
095
096 /**
097 * Determines if the caret is currently visible.
098 *
099 * @return true if the caret is visible else false
100 */
101 public boolean isVisible();
102
103 /**
104 * Sets the visibility of the caret.
105 *
106 * @param v true if the caret should be shown,
107 * and false if the caret should be hidden
108 */
109 public void setVisible(boolean v);
110
111 /**
112 * Determines if the selection is currently visible.
113 *
114 * @return true if the caret is visible else false
115 */
116 public boolean isSelectionVisible();
117
118 /**
119 * Sets the visibility of the selection
120 *
121 * @param v true if the caret should be shown,
122 * and false if the caret should be hidden
123 */
124 public void setSelectionVisible(boolean v);
125
126 /**
127 * Set the current caret visual location. This can be used when
128 * moving between lines that have uneven end positions (such as
129 * when caret up or down actions occur). If text flows
130 * left-to-right or right-to-left the x-coordinate will indicate
131 * the desired navigation location for vertical movement. If
132 * the text flow is top-to-bottom, the y-coordinate will indicate
133 * the desired navigation location for horizontal movement.
134 *
135 * @param p the Point to use for the saved position. This
136 * can be null to indicate there is no visual location.
137 */
138 public void setMagicCaretPosition(Point p);
139
140 /**
141 * Gets the current caret visual location.
142 *
143 * @return the visual position.
144 * @see #setMagicCaretPosition
145 */
146 public Point getMagicCaretPosition();
147
148 /**
149 * Sets the blink rate of the caret. This determines if
150 * and how fast the caret blinks, commonly used as one
151 * way to attract attention to the caret.
152 *
153 * @param rate the delay in milliseconds >= 0. If this is
154 * zero the caret will not blink.
155 */
156 public void setBlinkRate(int rate);
157
158 /**
159 * Gets the blink rate of the caret. This determines if
160 * and how fast the caret blinks, commonly used as one
161 * way to attract attention to the caret.
162 *
163 * @return the delay in milliseconds >= 0. If this is
164 * zero the caret will not blink.
165 */
166 public int getBlinkRate();
167
168 /**
169 * Fetches the current position of the caret.
170 *
171 * @return the position >= 0
172 */
173 public int getDot();
174
175 /**
176 * Fetches the current position of the mark. If there
177 * is a selection, the mark will not be the same as
178 * the dot.
179 *
180 * @return the position >= 0
181 */
182 public int getMark();
183
184 /**
185 * Sets the caret position to some position. This
186 * causes the mark to become the same as the dot,
187 * effectively setting the selection range to zero.
188 * <p>
189 * If the parameter is negative or beyond the length of the document,
190 * the caret is placed at the beginning or at the end, respectively.
191 *
192 * @param dot the new position to set the caret to
193 */
194 public void setDot(int dot);
195
196 /**
197 * Moves the caret position (dot) to some other position,
198 * leaving behind the mark. This is useful for
199 * making selections.
200 *
201 * @param dot the new position to move the caret to >= 0
202 */
203 public void moveDot(int dot);
204
205 };
|