/* * 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. *
* The dot can be placed by either calling
* setDot
or moveDot
. 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.
*
* 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); };