KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > awt > font > TextHitInfo


1 /*
2  * @(#)TextHitInfo.java 1.33 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
8 /*
9  * (C) Copyright Taligent, Inc. 1996 - 1997, All Rights Reserved
10  * (C) Copyright IBM Corp. 1996 - 1998, All Rights Reserved
11  *
12  * The original version of this source code and documentation is
13  * copyrighted and owned by Taligent, Inc., a wholly-owned subsidiary
14  * of IBM. These materials are provided under terms of a License
15  * Agreement between Taligent and Sun. This technology is protected
16  * by multiple US and International patents.
17  *
18  * This notice and attribution to Taligent may not be removed.
19  * Taligent is a registered trademark of Taligent, Inc.
20  *
21  */
22
23 package java.awt.font;
24 import java.lang.String JavaDoc;
25
26 /**
27  * The <code>TextHitInfo</code> class represents a character position in a
28  * text model, and a <b>bias</b>, or "side," of the character. Biases are
29  * either <EM>leading</EM> (the left edge, for a left-to-right character)
30  * or <EM>trailing</EM> (the right edge, for a left-to-right character).
31  * Instances of <code>TextHitInfo</code> are used to specify caret and
32  * insertion positions within text.
33  * <p>
34  * For example, consider the text "abc". TextHitInfo.trailing(1)
35  * corresponds to the right side of the 'b' in the text.
36  * <p>
37  * <code>TextHitInfo</code> is used primarily by {@link TextLayout} and
38  * clients of <code>TextLayout</code>. Clients of <code>TextLayout</code>
39  * query <code>TextHitInfo</code> instances for an insertion offset, where
40  * new text is inserted into the text model. The insertion offset is equal
41  * to the character position in the <code>TextHitInfo</code> if the bias
42  * is leading, and one character after if the bias is trailing. The
43  * insertion offset for TextHitInfo.trailing(1) is 2.
44  * <p>
45  * Sometimes it is convenient to construct a <code>TextHitInfo</code> with
46  * the same insertion offset as an existing one, but on the opposite
47  * character. The <code>getOtherHit</code> method constructs a new
48  * <code>TextHitInfo</code> with the same insertion offset as an existing
49  * one, with a hit on the character on the other side of the insertion offset.
50  * Calling <code>getOtherHit</code> on trailing(1) would return leading(2).
51  * In general, <code>getOtherHit</code> for trailing(n) returns
52  * leading(n+1) and <code>getOtherHit</code> for leading(n)
53  * returns trailing(n-1).
54  * <p>
55  * <strong>Example</strong>:<p>
56  * Converting a graphical point to an insertion point within a text
57  * model
58  * <blockquote><pre>
59  * TextLayout layout = ...;
60  * Point2D.Float hitPoint = ...;
61  * TextHitInfo hitInfo = layout.hitTestChar(hitPoint.x, hitPoint.y);
62  * int insPoint = hitInfo.getInsertionIndex();
63  * // insPoint is relative to layout; may need to adjust for use
64  * // in a text model
65  * </pre></blockquote>
66  *
67  * @see TextLayout
68  */
69
70 public final class TextHitInfo {
71     private int charIndex;
72     private boolean isLeadingEdge;
73
74     /**
75      * Constructs a new <code>TextHitInfo</code>.
76      * @param charIndex the index of the character hit
77      * @param isLeadingEdge <code>true</code> if the leading edge of the
78      * character was hit
79      */
80     private TextHitInfo(int charIndex, boolean isLeadingEdge) {
81         this.charIndex = charIndex;
82         this.isLeadingEdge = isLeadingEdge;
83     }
84     
85     /**
86      * Returns the index of the character hit.
87      * @return the index of the character hit.
88      */
89     public int getCharIndex() {
90         return charIndex;
91     }
92     
93     /**
94      * Returns <code>true</code> if the leading edge of the character was
95      * hit.
96      * @return <code>true</code> if the leading edge of the character was
97      * hit; <code>false</code> otherwise.
98      */
99     public boolean isLeadingEdge() {
100         return isLeadingEdge;
101     }
102
103     /**
104      * Returns the insertion index. This is the character index if
105      * the leading edge of the character was hit, and one greater
106      * than the character index if the trailing edge was hit.
107      * @return the insertion index.
108      */
109     public int getInsertionIndex() {
110         return isLeadingEdge ? charIndex : charIndex + 1;
111     }
112
113     /**
114      * Returns the hash code.
115      * @return the hash code of this <code>TextHitInfo</code>, which is
116      * also the <code>charIndex</code> of this <code>TextHitInfo</code>.
117      */
118     public int hashCode() {
119         return charIndex;
120     }
121
122     /**
123      * Returns <code>true</code> if the specified <code>Object</code> is a
124      * <code>TextHitInfo</code> and equals this <code>TextHitInfo</code>.
125      * @param obj the <code>Object</code> to test for equality
126      * @return <code>true</code> if the specified <code>Object</code>
127      * equals this <code>TextHitInfo</code>; <code>false</code> otherwise.
128      */
129     public boolean equals(Object JavaDoc obj) {
130         return (obj instanceof TextHitInfo JavaDoc) && equals((TextHitInfo JavaDoc)obj);
131     }
132
133     /**
134      * Returns <code>true</code> if the specified <code>TextHitInfo</code>
135      * has the same <code>charIndex</code> and <code>isLeadingEdge</code>
136      * as this <code>TextHitInfo</code>. This is not the same as having
137      * the same insertion offset.
138      * @param hitInfo a specified <code>TextHitInfo</code>
139      * @return <code>true</code> if the specified <code>TextHitInfo</code>
140      * has the same <code>charIndex</code> and <code>isLeadingEdge</code>
141      * as this <code>TextHitInfo</code>.
142      */
143     public boolean equals(TextHitInfo JavaDoc hitInfo) {
144         return hitInfo != null && charIndex == hitInfo.charIndex &&
145             isLeadingEdge == hitInfo.isLeadingEdge;
146     }
147
148     /**
149      * Returns a <code>String</code> representing the hit for debugging
150      * use only.
151      * @return a <code>String</code> representing this
152      * <code>TextHitInfo</code>.
153      */
154     public String JavaDoc toString() {
155         return "TextHitInfo[" + charIndex + (isLeadingEdge ? "L" : "T")+"]";
156     }
157     
158     /**
159      * Creates a <code>TextHitInfo</code> on the leading edge of the
160      * character at the specified <code>charIndex</code>.
161      * @param charIndex the index of the character hit
162      * @return a <code>TextHitInfo</code> on the leading edge of the
163      * character at the specified <code>charIndex</code>.
164      */
165     public static TextHitInfo JavaDoc leading(int charIndex) {
166         return new TextHitInfo JavaDoc(charIndex, true);
167     }
168
169     /**
170      * Creates a hit on the trailing edge of the character at
171      * the specified <code>charIndex</code>.
172      * @param charIndex the index of the character hit
173      * @return a <code>TextHitInfo</code> on the trailing edge of the
174      * character at the specified <code>charIndex</code>.
175      */
176     public static TextHitInfo JavaDoc trailing(int charIndex) {
177         return new TextHitInfo JavaDoc(charIndex, false);
178     }
179
180     /**
181      * Creates a <code>TextHitInfo</code> at the specified offset,
182      * associated with the character before the offset.
183      * @param offset an offset associated with the character before
184      * the offset
185      * @return a <code>TextHitInfo</code> at the specified offset.
186      */
187     public static TextHitInfo JavaDoc beforeOffset(int offset) {
188         return new TextHitInfo JavaDoc(offset-1, false);
189     }
190
191     /**
192      * Creates a <code>TextHitInfo</code> at the specified offset,
193      * associated with the character after the offset.
194      * @param offset an offset associated with the character after
195      * the offset
196      * @return a <code>TextHitInfo</code> at the specified offset.
197      */
198     public static TextHitInfo JavaDoc afterOffset(int offset) {
199         return new TextHitInfo JavaDoc(offset, true);
200     }
201
202     /**
203      * Creates a <code>TextHitInfo</code> on the other side of the
204      * insertion point. This <code>TextHitInfo</code> remains unchanged.
205      * @return a <code>TextHitInfo</code> on the other side of the
206      * insertion point.
207      */
208     public TextHitInfo JavaDoc getOtherHit() {
209         if (isLeadingEdge) {
210             return trailing(charIndex - 1);
211         } else {
212             return leading(charIndex + 1);
213         }
214     }
215
216     /**
217      * Creates a <code>TextHitInfo</code> whose character index is offset
218      * by <code>delta</code> from the <code>charIndex</code> of this
219      * <code>TextHitInfo</code>. This <code>TextHitInfo</code> remains
220      * unchanged.
221      * @param delta the value to offset this <code>charIndex</code>
222      * @return a <code>TextHitInfo</code> whose <code>charIndex</code> is
223      * offset by <code>delta</code> from the <code>charIndex</code> of
224      * this <code>TextHitInfo</code>.
225      */
226     public TextHitInfo JavaDoc getOffsetHit(int delta) {
227         return new TextHitInfo JavaDoc(charIndex + delta, isLeadingEdge);
228     }
229 }
230
Popular Tags