001 /*
002 * Copyright 1997-1998 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
026 /*
027 * (C) Copyright Taligent, Inc. 1996 - 1997, All Rights Reserved
028 * (C) Copyright IBM Corp. 1996 - 1998, All Rights Reserved
029 *
030 * The original version of this source code and documentation is
031 * copyrighted and owned by Taligent, Inc., a wholly-owned subsidiary
032 * of IBM. These materials are provided under terms of a License
033 * Agreement between Taligent and Sun. This technology is protected
034 * by multiple US and International patents.
035 *
036 * This notice and attribution to Taligent may not be removed.
037 * Taligent is a registered trademark of Taligent, Inc.
038 *
039 */
040
041 package java.awt.font;
042
043 import java.lang.String;
044
045 /**
046 * The <code>TextHitInfo</code> class represents a character position in a
047 * text model, and a <b>bias</b>, or "side," of the character. Biases are
048 * either <EM>leading</EM> (the left edge, for a left-to-right character)
049 * or <EM>trailing</EM> (the right edge, for a left-to-right character).
050 * Instances of <code>TextHitInfo</code> are used to specify caret and
051 * insertion positions within text.
052 * <p>
053 * For example, consider the text "abc". TextHitInfo.trailing(1)
054 * corresponds to the right side of the 'b' in the text.
055 * <p>
056 * <code>TextHitInfo</code> is used primarily by {@link TextLayout} and
057 * clients of <code>TextLayout</code>. Clients of <code>TextLayout</code>
058 * query <code>TextHitInfo</code> instances for an insertion offset, where
059 * new text is inserted into the text model. The insertion offset is equal
060 * to the character position in the <code>TextHitInfo</code> if the bias
061 * is leading, and one character after if the bias is trailing. The
062 * insertion offset for TextHitInfo.trailing(1) is 2.
063 * <p>
064 * Sometimes it is convenient to construct a <code>TextHitInfo</code> with
065 * the same insertion offset as an existing one, but on the opposite
066 * character. The <code>getOtherHit</code> method constructs a new
067 * <code>TextHitInfo</code> with the same insertion offset as an existing
068 * one, with a hit on the character on the other side of the insertion offset.
069 * Calling <code>getOtherHit</code> on trailing(1) would return leading(2).
070 * In general, <code>getOtherHit</code> for trailing(n) returns
071 * leading(n+1) and <code>getOtherHit</code> for leading(n)
072 * returns trailing(n-1).
073 * <p>
074 * <strong>Example</strong>:<p>
075 * Converting a graphical point to an insertion point within a text
076 * model
077 * <blockquote><pre>
078 * TextLayout layout = ...;
079 * Point2D.Float hitPoint = ...;
080 * TextHitInfo hitInfo = layout.hitTestChar(hitPoint.x, hitPoint.y);
081 * int insPoint = hitInfo.getInsertionIndex();
082 * // insPoint is relative to layout; may need to adjust for use
083 * // in a text model
084 * </pre></blockquote>
085 *
086 * @see TextLayout
087 */
088
089 public final class TextHitInfo {
090 private int charIndex;
091 private boolean isLeadingEdge;
092
093 /**
094 * Constructs a new <code>TextHitInfo</code>.
095 * @param charIndex the index of the character hit
096 * @param isLeadingEdge <code>true</code> if the leading edge of the
097 * character was hit
098 */
099 private TextHitInfo(int charIndex, boolean isLeadingEdge) {
100 this .charIndex = charIndex;
101 this .isLeadingEdge = isLeadingEdge;
102 }
103
104 /**
105 * Returns the index of the character hit.
106 * @return the index of the character hit.
107 */
108 public int getCharIndex() {
109 return charIndex;
110 }
111
112 /**
113 * Returns <code>true</code> if the leading edge of the character was
114 * hit.
115 * @return <code>true</code> if the leading edge of the character was
116 * hit; <code>false</code> otherwise.
117 */
118 public boolean isLeadingEdge() {
119 return isLeadingEdge;
120 }
121
122 /**
123 * Returns the insertion index. This is the character index if
124 * the leading edge of the character was hit, and one greater
125 * than the character index if the trailing edge was hit.
126 * @return the insertion index.
127 */
128 public int getInsertionIndex() {
129 return isLeadingEdge ? charIndex : charIndex + 1;
130 }
131
132 /**
133 * Returns the hash code.
134 * @return the hash code of this <code>TextHitInfo</code>, which is
135 * also the <code>charIndex</code> of this <code>TextHitInfo</code>.
136 */
137 public int hashCode() {
138 return charIndex;
139 }
140
141 /**
142 * Returns <code>true</code> if the specified <code>Object</code> is a
143 * <code>TextHitInfo</code> and equals this <code>TextHitInfo</code>.
144 * @param obj the <code>Object</code> to test for equality
145 * @return <code>true</code> if the specified <code>Object</code>
146 * equals this <code>TextHitInfo</code>; <code>false</code> otherwise.
147 */
148 public boolean equals(Object obj) {
149 return (obj instanceof TextHitInfo)
150 && equals((TextHitInfo) obj);
151 }
152
153 /**
154 * Returns <code>true</code> if the specified <code>TextHitInfo</code>
155 * has the same <code>charIndex</code> and <code>isLeadingEdge</code>
156 * as this <code>TextHitInfo</code>. This is not the same as having
157 * the same insertion offset.
158 * @param hitInfo a specified <code>TextHitInfo</code>
159 * @return <code>true</code> if the specified <code>TextHitInfo</code>
160 * has the same <code>charIndex</code> and <code>isLeadingEdge</code>
161 * as this <code>TextHitInfo</code>.
162 */
163 public boolean equals(TextHitInfo hitInfo) {
164 return hitInfo != null && charIndex == hitInfo.charIndex
165 && isLeadingEdge == hitInfo.isLeadingEdge;
166 }
167
168 /**
169 * Returns a <code>String</code> representing the hit for debugging
170 * use only.
171 * @return a <code>String</code> representing this
172 * <code>TextHitInfo</code>.
173 */
174 public String toString() {
175 return "TextHitInfo[" + charIndex + (isLeadingEdge ? "L" : "T")
176 + "]";
177 }
178
179 /**
180 * Creates a <code>TextHitInfo</code> on the leading edge of the
181 * character at the specified <code>charIndex</code>.
182 * @param charIndex the index of the character hit
183 * @return a <code>TextHitInfo</code> on the leading edge of the
184 * character at the specified <code>charIndex</code>.
185 */
186 public static TextHitInfo leading(int charIndex) {
187 return new TextHitInfo(charIndex, true);
188 }
189
190 /**
191 * Creates a hit on the trailing edge of the character at
192 * the specified <code>charIndex</code>.
193 * @param charIndex the index of the character hit
194 * @return a <code>TextHitInfo</code> on the trailing edge of the
195 * character at the specified <code>charIndex</code>.
196 */
197 public static TextHitInfo trailing(int charIndex) {
198 return new TextHitInfo(charIndex, false);
199 }
200
201 /**
202 * Creates a <code>TextHitInfo</code> at the specified offset,
203 * associated with the character before the offset.
204 * @param offset an offset associated with the character before
205 * the offset
206 * @return a <code>TextHitInfo</code> at the specified offset.
207 */
208 public static TextHitInfo beforeOffset(int offset) {
209 return new TextHitInfo(offset - 1, false);
210 }
211
212 /**
213 * Creates a <code>TextHitInfo</code> at the specified offset,
214 * associated with the character after the offset.
215 * @param offset an offset associated with the character after
216 * the offset
217 * @return a <code>TextHitInfo</code> at the specified offset.
218 */
219 public static TextHitInfo afterOffset(int offset) {
220 return new TextHitInfo(offset, true);
221 }
222
223 /**
224 * Creates a <code>TextHitInfo</code> on the other side of the
225 * insertion point. This <code>TextHitInfo</code> remains unchanged.
226 * @return a <code>TextHitInfo</code> on the other side of the
227 * insertion point.
228 */
229 public TextHitInfo getOtherHit() {
230 if (isLeadingEdge) {
231 return trailing(charIndex - 1);
232 } else {
233 return leading(charIndex + 1);
234 }
235 }
236
237 /**
238 * Creates a <code>TextHitInfo</code> whose character index is offset
239 * by <code>delta</code> from the <code>charIndex</code> of this
240 * <code>TextHitInfo</code>. This <code>TextHitInfo</code> remains
241 * unchanged.
242 * @param delta the value to offset this <code>charIndex</code>
243 * @return a <code>TextHitInfo</code> whose <code>charIndex</code> is
244 * offset by <code>delta</code> from the <code>charIndex</code> of
245 * this <code>TextHitInfo</code>.
246 */
247 public TextHitInfo getOffsetHit(int delta) {
248 return new TextHitInfo(charIndex + delta, isLeadingEdge);
249 }
250 }
|