/* * Copyright (c) 1997, 2006, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation.  Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */package javax.swing.text; import java.awt.Graphics;import java.awt.Point;import javax.swing.Action;import javax.swing.event.ChangeListener; /** * A place within a document view that represents where * things can be inserted into the document model.  A caret * has a position in the document referred to as a dot. * The dot is where the caret is currently located in the * model.  There is * a second position maintained by the caret that represents * the other end of a selection called mark.  If there is * no selection the dot and mark will be equal.  If a selection * exists, the two values will be different. * <p> * The dot can be placed by either calling * <code>setDot</code> or <code>moveDot</code>.  Setting * the dot has the effect of removing any selection that may * have previously existed.  The dot and mark will be equal. * Moving the dot has the effect of creating a selection as * the mark is left at whatever position it previously had. * * @author  Timothy Prinzing */public interface Caret {     /**     * Called when the UI is being installed into the     * interface of a JTextComponent.  This can be used     * to gain access to the model that is being navigated     * by the implementation of this interface.     *     * @param c the JTextComponent     */    public void install(JTextComponent c);     /**     * Called when the UI is being removed from the     * interface of a JTextComponent.  This is used to     * unregister any listeners that were attached.     *     * @param c the JTextComponent     */    public void deinstall(JTextComponent c);     /**     * Renders the caret. This method is called by UI classes.     *     * @param g the graphics context     */    public void paint(Graphics g);     /**     * Adds a listener to track whenever the caret position     * has been changed.     *     * @param l the change listener     */    public void addChangeListener(ChangeListener l);     /**     * Removes a listener that was tracking caret position changes.     *     * @param l the change listener     */    public void removeChangeListener(ChangeListener l);     /**     * Determines if the caret is currently visible.     *     * @return true if the caret is visible else false     */    public boolean isVisible();     /**     * Sets the visibility of the caret.     *     * @param v  true if the caret should be shown,     *  and false if the caret should be hidden     */    public void setVisible(boolean v);     /**     * Determines if the selection is currently visible.     *     * @return true if the caret is visible else false     */    public boolean isSelectionVisible();     /**     * Sets the visibility of the selection     *     * @param v  true if the caret should be shown,     *  and false if the caret should be hidden     */    public void setSelectionVisible(boolean v);     /**     * Set the current caret visual location.  This can be used when     * moving between lines that have uneven end positions (such as     * when caret up or down actions occur).  If text flows     * left-to-right or right-to-left the x-coordinate will indicate     * the desired navigation location for vertical movement.  If     * the text flow is top-to-bottom, the y-coordinate will indicate     * the desired navigation location for horizontal movement.     *     * @param p  the Point to use for the saved position.  This     *   can be null to indicate there is no visual location.     */    public void setMagicCaretPosition(Point p);     /**     * Gets the current caret visual location.     *     * @return the visual position.     * @see #setMagicCaretPosition     */    public Point getMagicCaretPosition();     /**     * Sets the blink rate of the caret.  This determines if     * and how fast the caret blinks, commonly used as one     * way to attract attention to the caret.     *     * @param rate  the delay in milliseconds >= 0.  If this is     *  zero the caret will not blink.     */    public void setBlinkRate(int rate);     /**     * Gets the blink rate of the caret.  This determines if     * and how fast the caret blinks, commonly used as one     * way to attract attention to the caret.     *     * @return the delay in milliseconds >= 0.  If this is     *  zero the caret will not blink.     */    public int getBlinkRate();     /**     * Fetches the current position of the caret.     *     * @return the position >= 0     */    public int getDot();     /**     * Fetches the current position of the mark.  If there     * is a selection, the mark will not be the same as     * the dot.     *     * @return the position >= 0     */    public int getMark();     /**     * Sets the caret position to some position.  This     * causes the mark to become the same as the dot,     * effectively setting the selection range to zero.     * <p>     * If the parameter is negative or beyond the length of the document,     * the caret is placed at the beginning or at the end, respectively.     *     * @param dot  the new position to set the caret to     */    public void setDot(int dot);     /**     * Moves the caret position (dot) to some other position,     * leaving behind the mark.  This is useful for     * making selections.     *     * @param dot  the new position to move the caret to >= 0     */    public void moveDot(int dot); };