Caret


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