home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / awt / font / TextHitInfo.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  6.3 KB  |  200 lines
  1. /*
  2.  * @(#)TextHitInfo.java    1.21 98/03/18
  3.  *
  4.  * Copyright 1997, 1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. /*
  16.  * (C) Copyright Taligent, Inc. 1996 - 1997, All Rights Reserved
  17.  * (C) Copyright IBM Corp. 1996 - 1998, All Rights Reserved
  18.  *
  19.  * The original version of this source code and documentation is
  20.  * copyrighted and owned by Taligent, Inc., a wholly-owned subsidiary
  21.  * of IBM. These materials are provided under terms of a License
  22.  * Agreement between Taligent and Sun. This technology is protected
  23.  * by multiple US and International patents.
  24.  *
  25.  * This notice and attribution to Taligent may not be removed.
  26.  * Taligent is a registered trademark of Taligent, Inc.
  27.  *
  28.  */
  29.  
  30. package java.awt.font;
  31. import java.lang.String;
  32.  
  33. /**
  34.  * TextHitInfo represents a character position in a text model, and a
  35.  * <b>bias</b>, or "side," of the character.  Biases are either LEADING
  36.  * (the left edge, for a left-to-right character) or TRAILING (the 
  37.  * right edge, for a left-to-right character).  Instances of 
  38.  * TextHitInfo are used to specify caret and insertion positions within
  39.  * text.
  40.  * <p>
  41.  * For example, consider the text "abc".  The TextHitInfo (1, TRAILING)
  42.  * corresponds to the right side of the 'b' in the text.
  43.  * <p>
  44.  * TextHitInfo is used primarily by TextLayout and clients of 
  45.  * TextLayout.  Clients of TextLayout will query TextHitInfo instances 
  46.  * for an insertion offset, where new text will be inserted into the 
  47.  * text model.  The insertion offset is equals to the character 
  48.  * position in the TextHitInfo if the bias is LEADING, and one 
  49.  * character after if the bias is TRAILING.  The insertion offset for
  50.  * TextHitInfo (1, TRAILING) is 2.
  51.  * <p>
  52.  * Sometimes it is convenient to construct a TextHitInfo with the same
  53.  * insertion offset as an existing one, but on the opposite character.
  54.  * <code>getOtherHit</code> will construct a new TextHitInfo with the 
  55.  * same insertion offset as an existing one, with a hit on the 
  56.  * character on the other side of the insertion offset.  Calling 
  57.  * <code>getOtherHit</code> on (1, TRAILING) would return (2, LEADING).
  58.  * In general, <code>getOtherHit</code> for (n, TRAILING) returns 
  59.  * (n+1, LEADING) and <code>getOtherHit</code> for (n, LEADING) 
  60.  * returns (n-1, TRAILING).
  61.  * <p>
  62.  * <strong>Example</strong>:<p>
  63.  * Converting a graphical point to an insertion point within a text 
  64.  * model
  65.  * <blockquote><pre>
  66.  * TextLayout layout = ...;
  67.  * Point2D hitPoint = ...;
  68.  * TextHitInfo hitInfo = layout.hitTestChar(hitPoint.x, hitPoint.y);
  69.  * int insPoint = hitInfo.getInsertionOffset();
  70.  * // insPoint is relative to layout;  may need to adjust for use 
  71.  * // in a text model
  72.  * </pre></blockquote>
  73.  *
  74.  * @see TextLayout
  75.  */
  76.  
  77. public final class TextHitInfo {
  78.     private int charIndex;
  79.     private boolean isLeadingEdge;
  80.  
  81.     public static boolean LEADING = true;
  82.     public static boolean TRAILING = false;
  83.  
  84.     /**
  85.      * Constructor for TextHitInfo.
  86.      * @param charIndex the index of the character hit.
  87.      * @param isLeadingEdge true if the leading edge of the 
  88.      * character was hit.
  89.      */
  90.     private TextHitInfo(int charIndex, boolean isLeadingEdge) {
  91.         this.charIndex = charIndex;
  92.         this.isLeadingEdge = isLeadingEdge;
  93.     }
  94.     
  95.     /** 
  96.      * Returns the index of the character hit.
  97.      */
  98.     public int getCharIndex() {
  99.         return charIndex;
  100.     }
  101.     
  102.     /** 
  103.      * Returns true if the leading edge of the character was hit.
  104.      */
  105.     public boolean isLeadingEdge() {
  106.         return isLeadingEdge;
  107.     }
  108.  
  109.     /**
  110.      * Returns the insertion index.  This is the character index if 
  111.      * the leading edge of the character was hit, and one greater 
  112.      * than the character index if the trailing edge was hit.
  113.      */
  114.     public int getInsertionIndex() {
  115.         return isLeadingEdge ? charIndex : charIndex + 1;
  116.     }
  117.  
  118.     /**
  119.      * Returns the hash code.
  120.      */
  121.     public int hashCode() {
  122.         return charIndex;
  123.     }
  124.  
  125.     /**
  126.      * Return true if the object is a TextHitInfo and this TextHitInfo 
  127.      * is equal to it.
  128.      */
  129.     public boolean equals(Object obj) {
  130.         return (obj instanceof TextHitInfo) && equals((TextHitInfo)obj);
  131.     }
  132.  
  133.     /**
  134.      * Return true if the hit's character index and edge are the same.
  135.      *
  136.      * This is not the same as having the same insertion offset.
  137.      */
  138.     public boolean equals(TextHitInfo hitInfo) {
  139.         return hitInfo != null && charIndex == hitInfo.charIndex &&
  140.             isLeadingEdge == hitInfo.isLeadingEdge;
  141.     }
  142.  
  143.     /**
  144.      * Return a string representing the hit, for debugging use only.
  145.      */
  146.     public String toString() {
  147.         return "TextHitInfo[" + charIndex + (isLeadingEdge ? "L" : "T")+"]";
  148.     }
  149.     
  150.     /**
  151.      * Create a hit on the leading edge of the character at charIndex.
  152.      */
  153.     public static TextHitInfo leading(int charIndex) {
  154.         return new TextHitInfo(charIndex, true);
  155.     }
  156.  
  157.     /**
  158.      * Create a hit on the trailing edge of the character at charIndex.
  159.      */
  160.     public static TextHitInfo trailing(int charIndex) {
  161.         return new TextHitInfo(charIndex, false);
  162.     }
  163.  
  164.     /**
  165.      * Create a hit at offset, associated with the character before
  166.      * the offset.
  167.      */
  168.     public static TextHitInfo beforeOffset(int offset) {
  169.         return new TextHitInfo(offset-1, false);
  170.     }
  171.  
  172.     /**
  173.      * Create a hit at offset, associated with the character after
  174.      * the offset.
  175.      */
  176.     public static TextHitInfo afterOffset(int offset) {
  177.         return new TextHitInfo(offset, true);
  178.     }
  179.  
  180.     /**
  181.      * Creates a hit on the other side of the insertion point.  
  182.      * This hit remains unchanged.
  183.      */
  184.     public TextHitInfo getOtherHit() {
  185.         if (isLeadingEdge) {
  186.             return trailing(charIndex - 1);
  187.         } else {
  188.             return leading(charIndex + 1);
  189.         }
  190.     }
  191.  
  192.     /**
  193.      * Creates a hit whose character index is offset by delta from this
  194.      * hit.  This hit remains unchanged.
  195.      */
  196.     public TextHitInfo getOffsetHit(int delta) {
  197.         return new TextHitInfo(charIndex + delta, isLeadingEdge);
  198.     }
  199. }
  200.