001: /*
002: *
003: * @(#)TextHitInfo.java 1.6 06/10/03
004: *
005: * Portions Copyright 2000-2006 Sun Microsystems, Inc. All Rights
006: * Reserved. Use is subject to license terms.
007: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
008: *
009: * This program is free software; you can redistribute it and/or
010: * modify it under the terms of the GNU General Public License version
011: * 2 only, as published by the Free Software Foundation.
012: *
013: * This program is distributed in the hope that it will be useful, but
014: * WITHOUT ANY WARRANTY; without even the implied warranty of
015: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
016: * General Public License version 2 for more details (a copy is
017: * included at /legal/license.txt).
018: *
019: * You should have received a copy of the GNU General Public License
020: * version 2 along with this work; if not, write to the Free Software
021: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
022: * 02110-1301 USA
023: *
024: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
025: * Clara, CA 95054 or visit www.sun.com if you need additional
026: * information or have any questions.
027: */
028:
029: /*
030: * (C) Copyright Taligent, Inc. 1996 - 1997, All Rights Reserved
031: * (C) Copyright IBM Corp. 1996 - 1998, All Rights Reserved
032: *
033: * The original version of this source code and documentation is
034: * copyrighted and owned by Taligent, Inc., a wholly-owned subsidiary
035: * of IBM. These materials are provided under terms of a License
036: * Agreement between Taligent and Sun. This technology is protected
037: * by multiple US and International patents.
038: *
039: * This notice and attribution to Taligent may not be removed.
040: * Taligent is a registered trademark of Taligent, Inc.
041: *
042: */
043:
044: package java.awt.font;
045:
046: import java.lang.String;
047:
048: /**
049: * The <code>TextHitInfo</code> class represents a character position in a
050: * text model, and a <b>bias</b>, or "side," of the character. Biases are
051: * either <EM>leading</EM> (the left edge, for a left-to-right character)
052: * or <EM>trailing</EM> (the right edge, for a left-to-right character).
053: * Instances of <code>TextHitInfo</code> are used to specify caret and
054: * insertion positions within text.
055: * <p>
056: * For example, consider the text "abc". TextHitInfo.trailing(1)
057: * corresponds to the right side of the 'b' in the text.
058: * <p>
059: * <code>TextHitInfo</code> is used primarily by {@link TextLayout} and
060: * clients of <code>TextLayout</code>. Clients of <code>TextLayout</code>
061: * query <code>TextHitInfo</code> instances for an insertion offset, where
062: * new text is inserted into the text model. The insertion offset is equal
063: * to the character position in the <code>TextHitInfo</code> if the bias
064: * is leading, and one character after if the bias is trailing. The
065: * insertion offset for TextHitInfo.trailing(1) is 2.
066: * <p>
067: * Sometimes it is convenient to construct a <code>TextHitInfo</code> with
068: * the same insertion offset as an existing one, but on the opposite
069: * character. The <code>getOtherHit</code> method constructs a new
070: * <code>TextHitInfo</code> with the same insertion offset as an existing
071: * one, with a hit on the character on the other side of the insertion offset.
072: * Calling <code>getOtherHit</code> on trailing(1) would return leading(2).
073: * In general, <code>getOtherHit</code> for trailing(n) returns
074: * leading(n+1) and <code>getOtherHit</code> for leading(n)
075: * returns trailing(n-1).
076: * <p>
077: * <strong>Example</strong>:<p>
078: * Converting a graphical point to an insertion point within a text
079: * model
080: * <blockquote><pre>
081: * TextLayout layout = ...;
082: * Point2D.Float hitPoint = ...;
083: * TextHitInfo hitInfo = layout.hitTestChar(hitPoint.x, hitPoint.y);
084: * int insPoint = hitInfo.getInsertionIndex();
085: * // insPoint is relative to layout; may need to adjust for use
086: * // in a text model
087: * </pre></blockquote>
088: *
089: * @see TextLayout
090: */
091:
092: public final class TextHitInfo {
093: private int charIndex;
094: private boolean isLeadingEdge;
095:
096: /**
097: * Constructs a new <code>TextHitInfo</code>.
098: * @param charIndex the index of the character hit
099: * @param isLeadingEdge <code>true</code> if the leading edge of the
100: * character was hit
101: */
102: private TextHitInfo(int charIndex, boolean isLeadingEdge) {
103: this .charIndex = charIndex;
104: this .isLeadingEdge = isLeadingEdge;
105: }
106:
107: /**
108: * Returns the index of the character hit.
109: * @return the index of the character hit.
110: */
111: public int getCharIndex() {
112: return charIndex;
113: }
114:
115: /**
116: * Returns <code>true</code> if the leading edge of the character was
117: * hit.
118: * @return <code>true</code> if the leading edge of the character was
119: * hit; <code>false</code> otherwise.
120: */
121: public boolean isLeadingEdge() {
122: return isLeadingEdge;
123: }
124:
125: /**
126: * Returns the insertion index. This is the character index if
127: * the leading edge of the character was hit, and one greater
128: * than the character index if the trailing edge was hit.
129: * @return the insertion index.
130: */
131: public int getInsertionIndex() {
132: return isLeadingEdge ? charIndex : charIndex + 1;
133: }
134:
135: /**
136: * Returns the hash code.
137: * @return the hash code of this <code>TextHitInfo</code>, which is
138: * also the <code>charIndex</code> of this <code>TextHitInfo</code>.
139: */
140: public int hashCode() {
141: return charIndex;
142: }
143:
144: /**
145: * Returns <code>true</code> if the specified <code>Object</code> is a
146: * <code>TextHitInfo</code> and equals this <code>TextHitInfo</code>.
147: * @param obj the <code>Object</code> to test for equality
148: * @return <code>true</code> if the specified <code>Object</code>
149: * equals this <code>TextHitInfo</code>; <code>false</code> otherwise.
150: */
151: public boolean equals(Object obj) {
152: if (!(obj instanceof TextHitInfo))
153: return false;
154: TextHitInfo hitInfo = (TextHitInfo) obj;
155: return hitInfo != null && charIndex == hitInfo.charIndex
156: && isLeadingEdge == hitInfo.isLeadingEdge;
157: }
158:
159: /**
160: * Returns <code>true</code> if the specified <code>TextHitInfo</code>
161: * has the same <code>charIndex</code> and <code>isLeadingEdge</code>
162: * as this <code>TextHitInfo</code>. This is not the same as having
163: * the same insertion offset.
164: * @param hitInfo a specified <code>TextHitInfo</code>
165: * @return <code>true</code> if the specified <code>TextHitInfo</code>
166: * has the same <code>charIndex</code> and <code>isLeadingEdge</code>
167: * as this <code>TextHitInfo</code>.
168: */
169: /**
170: public boolean equals(TextHitInfo hitInfo) {
171: return hitInfo != null && charIndex == hitInfo.charIndex &&
172: isLeadingEdge == hitInfo.isLeadingEdge;
173: }
174: **/
175:
176: /**
177: * Returns a <code>String</code> representing the hit for debugging
178: * use only.
179: * @return a <code>String</code> representing this
180: * <code>TextHitInfo</code>.
181: */
182: public String toString() {
183: return "TextHitInfo[" + charIndex + (isLeadingEdge ? "L" : "T")
184: + "]";
185: }
186:
187: /**
188: * Creates a <code>TextHitInfo</code> on the leading edge of the
189: * character at the specified <code>charIndex</code>.
190: * @param charIndex the index of the character hit
191: * @return a <code>TextHitInfo</code> on the leading edge of the
192: * character at the specified <code>charIndex</code>.
193: */
194: public static TextHitInfo leading(int charIndex) {
195: return new TextHitInfo(charIndex, true);
196: }
197:
198: /**
199: * Creates a hit on the trailing edge of the character at
200: * the specified <code>charIndex</code>.
201: * @param charIndex the index of the character hit
202: * @return a <code>TextHitInfo</code> on the trailing edge of the
203: * character at the specified <code>charIndex</code>.
204: */
205: public static TextHitInfo trailing(int charIndex) {
206: return new TextHitInfo(charIndex, false);
207: }
208:
209: /**
210: * Creates a <code>TextHitInfo</code> at the specified offset,
211: * associated with the character before the offset.
212: * @param offset an offset associated with the character before
213: * the offset
214: * @return a <code>TextHitInfo</code> at the specified offset.
215: */
216: public static TextHitInfo beforeOffset(int offset) {
217: return new TextHitInfo(offset - 1, false);
218: }
219:
220: /**
221: * Creates a <code>TextHitInfo</code> at the specified offset,
222: * associated with the character after the offset.
223: * @param offset an offset associated with the character after
224: * the offset
225: * @return a <code>TextHitInfo</code> at the specified offset.
226: */
227: public static TextHitInfo afterOffset(int offset) {
228: return new TextHitInfo(offset, true);
229: }
230:
231: /**
232: * Creates a <code>TextHitInfo</code> on the other side of the
233: * insertion point. This <code>TextHitInfo</code> remains unchanged.
234: * @return a <code>TextHitInfo</code> on the other side of the
235: * insertion point.
236: */
237: public TextHitInfo getOtherHit() {
238: if (isLeadingEdge) {
239: return trailing(charIndex - 1);
240: } else {
241: return leading(charIndex + 1);
242: }
243: }
244:
245: /**
246: * Creates a <code>TextHitInfo</code> whose character index is offset
247: * by <code>delta</code> from the <code>charIndex</code> of this
248: * <code>TextHitInfo</code>. This <code>TextHitInfo</code> remains
249: * unchanged.
250: * @param delta the value to offset this <code>charIndex</code>
251: * @return a <code>TextHitInfo</code> whose <code>charIndex</code> is
252: * offset by <code>delta</code> from the <code>charIndex</code> of
253: * this <code>TextHitInfo</code>.
254: */
255: public TextHitInfo getOffsetHit(int delta) {
256: return new TextHitInfo(charIndex + delta, isLeadingEdge);
257: }
258: }
|