1 /*

     2  * Copyright 1997-1998 Sun Microsystems, Inc.  All Rights Reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any questions.

    24  */

    25 

    26 /*

    27  * (C) Copyright Taligent, Inc. 1996 - 1997, All Rights Reserved

    28  * (C) Copyright IBM Corp. 1996 - 1998, All Rights Reserved

    29  *

    30  * The original version of this source code and documentation is

    31  * copyrighted and owned by Taligent, Inc., a wholly-owned subsidiary

    32  * of IBM. These materials are provided under terms of a License

    33  * Agreement between Taligent and Sun. This technology is protected

    34  * by multiple US and International patents.

    35  *

    36  * This notice and attribution to Taligent may not be removed.

    37  * Taligent is a registered trademark of Taligent, Inc.

    38  *

    39  */

    40 

    41 package java.awt.font;

    42 import java.lang.String;

    43 

    44 /**

    45  * The <code>TextHitInfo</code> class represents a character position in a

    46  * text model, and a <b>bias</b>, or "side," of the character.  Biases are

    47  * either <EM>leading</EM> (the left edge, for a left-to-right character)

    48  * or <EM>trailing</EM> (the right edge, for a left-to-right character).

    49  * Instances of <code>TextHitInfo</code> are used to specify caret and

    50  * insertion positions within text.

    51  * <p>

    52  * For example, consider the text "abc".  TextHitInfo.trailing(1)

    53  * corresponds to the right side of the 'b' in the text.

    54  * <p>

    55  * <code>TextHitInfo</code> is used primarily by {@link TextLayout} and

    56  * clients of <code>TextLayout</code>.  Clients of <code>TextLayout</code>

    57  * query <code>TextHitInfo</code> instances for an insertion offset, where

    58  * new text is inserted into the text model.  The insertion offset is equal

    59  * to the character position in the <code>TextHitInfo</code> if the bias

    60  * is leading, and one character after if the bias is trailing.  The

    61  * insertion offset for TextHitInfo.trailing(1) is 2.

    62  * <p>

    63  * Sometimes it is convenient to construct a <code>TextHitInfo</code> with

    64  * the same insertion offset as an existing one, but on the opposite

    65  * character.  The <code>getOtherHit</code> method constructs a new

    66  * <code>TextHitInfo</code> with the same insertion offset as an existing

    67  * one, with a hit on the character on the other side of the insertion offset.

    68  * Calling <code>getOtherHit</code> on trailing(1) would return leading(2).

    69  * In general, <code>getOtherHit</code> for trailing(n) returns

    70  * leading(n+1) and <code>getOtherHit</code> for leading(n)

    71  * returns trailing(n-1).

    72  * <p>

    73  * <strong>Example</strong>:<p>

    74  * Converting a graphical point to an insertion point within a text

    75  * model

    76  * <blockquote><pre>

    77  * TextLayout layout = ...;

    78  * Point2D.Float hitPoint = ...;

    79  * TextHitInfo hitInfo = layout.hitTestChar(hitPoint.x, hitPoint.y);

    80  * int insPoint = hitInfo.getInsertionIndex();

    81  * // insPoint is relative to layout;  may need to adjust for use

    82  * // in a text model

    83  * </pre></blockquote>

    84  *

    85  * @see TextLayout

    86  */

    87 

    88 public final class TextHitInfo {

    89     private int charIndex;

    90     private boolean isLeadingEdge;

    91 

    92     /**

    93      * Constructs a new <code>TextHitInfo</code>.

    94      * @param charIndex the index of the character hit

    95      * @param isLeadingEdge <code>true</code> if the leading edge of the

    96      * character was hit

    97      */

    98     private TextHitInfo(int charIndex, boolean isLeadingEdge) {

    99         this.charIndex = charIndex;

   100         this.isLeadingEdge = isLeadingEdge;

   101     }

   102 

   103     /**

   104      * Returns the index of the character hit.

   105      * @return the index of the character hit.

   106      */

   107     public int getCharIndex() {

   108         return charIndex;

   109     }

   110 

   111     /**

   112      * Returns <code>true</code> if the leading edge of the character was

   113      * hit.

   114      * @return <code>true</code> if the leading edge of the character was

   115      * hit; <code>false</code> otherwise.

   116      */

   117     public boolean isLeadingEdge() {

   118         return isLeadingEdge;

   119     }

   120 

   121     /**

   122      * Returns the insertion index.  This is the character index if

   123      * the leading edge of the character was hit, and one greater

   124      * than the character index if the trailing edge was hit.

   125      * @return the insertion index.

   126      */

   127     public int getInsertionIndex() {

   128         return isLeadingEdge ? charIndex : charIndex + 1;

   129     }

   130 

   131     /**

   132      * Returns the hash code.

   133      * @return the hash code of this <code>TextHitInfo</code>, which is

   134      * also the <code>charIndex</code> of this <code>TextHitInfo</code>.

   135      */

   136     public int hashCode() {

   137         return charIndex;

   138     }

   139 

   140     /**

   141      * Returns <code>true</code> if the specified <code>Object</code> is a

   142      * <code>TextHitInfo</code> and equals this <code>TextHitInfo</code>.

   143      * @param obj the <code>Object</code> to test for equality

   144      * @return <code>true</code> if the specified <code>Object</code>

   145      * equals this <code>TextHitInfo</code>; <code>false</code> otherwise.

   146      */

   147     public boolean equals(Object obj) {

   148         return (obj instanceof TextHitInfo) && equals((TextHitInfo)obj);

   149     }

   150 

   151     /**

   152      * Returns <code>true</code> if the specified <code>TextHitInfo</code>

   153      * has the same <code>charIndex</code> and <code>isLeadingEdge</code>

   154      * as this <code>TextHitInfo</code>.  This is not the same as having

   155      * the same insertion offset.

   156      * @param hitInfo a specified <code>TextHitInfo</code>

   157      * @return <code>true</code> if the specified <code>TextHitInfo</code>

   158      * has the same <code>charIndex</code> and <code>isLeadingEdge</code>

   159      * as this <code>TextHitInfo</code>.

   160      */

   161     public boolean equals(TextHitInfo hitInfo) {

   162         return hitInfo != null && charIndex == hitInfo.charIndex &&

   163             isLeadingEdge == hitInfo.isLeadingEdge;

   164     }

   165 

   166     /**

   167      * Returns a <code>String</code> representing the hit for debugging

   168      * use only.

   169      * @return a <code>String</code> representing this

   170      * <code>TextHitInfo</code>.

   171      */

   172     public String toString() {

   173         return "TextHitInfo[" + charIndex + (isLeadingEdge ? "L" : "T")+"]";

   174     }

   175 

   176     /**

   177      * Creates a <code>TextHitInfo</code> on the leading edge of the

   178      * character at the specified <code>charIndex</code>.

   179      * @param charIndex the index of the character hit

   180      * @return a <code>TextHitInfo</code> on the leading edge of the

   181      * character at the specified <code>charIndex</code>.

   182      */

   183     public static TextHitInfo leading(int charIndex) {

   184         return new TextHitInfo(charIndex, true);

   185     }

   186 

   187     /**

   188      * Creates a hit on the trailing edge of the character at

   189      * the specified <code>charIndex</code>.

   190      * @param charIndex the index of the character hit

   191      * @return a <code>TextHitInfo</code> on the trailing edge of the

   192      * character at the specified <code>charIndex</code>.

   193      */

   194     public static TextHitInfo trailing(int charIndex) {

   195         return new TextHitInfo(charIndex, false);

   196     }

   197 

   198     /**

   199      * Creates a <code>TextHitInfo</code> at the specified offset,

   200      * associated with the character before the offset.

   201      * @param offset an offset associated with the character before

   202      * the offset

   203      * @return a <code>TextHitInfo</code> at the specified offset.

   204      */

   205     public static TextHitInfo beforeOffset(int offset) {

   206         return new TextHitInfo(offset-1, false);

   207     }

   208 

   209     /**

   210      * Creates a <code>TextHitInfo</code> at the specified offset,

   211      * associated with the character after the offset.

   212      * @param offset an offset associated with the character after

   213      * the offset

   214      * @return a <code>TextHitInfo</code> at the specified offset.

   215      */

   216     public static TextHitInfo afterOffset(int offset) {

   217         return new TextHitInfo(offset, true);

   218     }

   219 

   220     /**

   221      * Creates a <code>TextHitInfo</code> on the other side of the

   222      * insertion point.  This <code>TextHitInfo</code> remains unchanged.

   223      * @return a <code>TextHitInfo</code> on the other side of the

   224      * insertion point.

   225      */

   226     public TextHitInfo getOtherHit() {

   227         if (isLeadingEdge) {

   228             return trailing(charIndex - 1);

   229         } else {

   230             return leading(charIndex + 1);

   231         }

   232     }

   233 

   234     /**

   235      * Creates a <code>TextHitInfo</code> whose character index is offset

   236      * by <code>delta</code> from the <code>charIndex</code> of this

   237      * <code>TextHitInfo</code>. This <code>TextHitInfo</code> remains

   238      * unchanged.

   239      * @param delta the value to offset this <code>charIndex</code>

   240      * @return a <code>TextHitInfo</code> whose <code>charIndex</code> is

   241      * offset by <code>delta</code> from the <code>charIndex</code> of

   242      * this <code>TextHitInfo</code>.

   243      */

   244     public TextHitInfo getOffsetHit(int delta) {

   245         return new TextHitInfo(charIndex + delta, isLeadingEdge);

   246     }

   247 }