Home » openjdk-7 » java » awt » im » [javadoc | source]

    1   /*
    2    * Copyright (c) 1997, 1999, Oracle and/or its affiliates. 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.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   22    * or visit www.oracle.com if you need additional information or have any
   23    * questions.
   24    */
   25   
   26   package java.awt.im;
   27   
   28   import java.awt.Rectangle;
   29   import java.awt.font.TextHitInfo;
   30   import java.text.AttributedCharacterIterator;
   31   import java.text.AttributedCharacterIterator.Attribute;
   32   
   33   /**
   34    * InputMethodRequests defines the requests that a text editing component
   35    * has to handle in order to work with input methods. The component
   36    * can implement this interface itself or use a separate object that
   37    * implements it. The object implementing this interface must be returned
   38    * from the component's getInputMethodRequests method.
   39    *
   40    * <p>
   41    * The text editing component also has to provide an input method event
   42    * listener.
   43    *
   44    * <p>
   45    * The interface is designed to support one of two input user interfaces:
   46    * <ul>
   47    * <li><em>on-the-spot</em> input, where the composed text is displayed as part
   48    *     of the text component's text body.
   49    * <li><em>below-the-spot</em> input, where the composed text is displayed in
   50    *     a separate composition window just below the insertion point where
   51    *     the text will be inserted when it is committed. Note that, if text is
   52    *     selected within the component's text body, this text will be replaced by
   53    *     the committed text upon commitment; therefore it is not considered part
   54    *     of the context that the text is input into.
   55    * </ul>
   56    *
   57    * @see java.awt.Component#getInputMethodRequests
   58    * @see java.awt.event.InputMethodListener
   59    *
   60    * @author JavaSoft Asia/Pacific
   61    * @since 1.2
   62    */
   63   
   64   public interface InputMethodRequests {
   65   
   66       /**
   67        * Gets the location of a specified offset in the current composed text,
   68        * or of the selection in committed text.
   69        * This information is, for example, used to position the candidate window
   70        * near the composed text, or a composition window near the location
   71        * where committed text will be inserted.
   72        *
   73        * <p>
   74        * If the component has composed text (because the most recent
   75        * InputMethodEvent sent to it contained composed text), then the offset is
   76        * relative to the composed text - offset 0 indicates the first character
   77        * in the composed text. The location returned should be for this character.
   78        *
   79        * <p>
   80        * If the component doesn't have composed text, the offset should be ignored,
   81        * and the location returned should reflect the beginning (in line
   82        * direction) of the highlight in the last line containing selected text.
   83        * For example, for horizontal left-to-right text (such as English), the
   84        * location to the left of the left-most character on the last line
   85        * containing selected text is returned. For vertical top-to-bottom text,
   86        * with lines proceding from right to left, the location to the top of the
   87        * left-most line containing selected text is returned.
   88        *
   89        * <p>
   90        * The location is represented as a 0-thickness caret, that is, it has 0
   91        * width if the text is drawn horizontally, and 0 height if the text is
   92        * drawn vertically. Other text orientations need to be mapped to
   93        * horizontal or vertical orientation. The rectangle uses absolute screen
   94        * coordinates.
   95        *
   96        * @param offset the offset within the composed text, if there is composed
   97        * text; null otherwise
   98        * @return a rectangle representing the screen location of the offset
   99        */
  100       Rectangle getTextLocation(TextHitInfo offset);
  101   
  102       /**
  103        * Gets the offset within the composed text for the specified absolute x
  104        * and y coordinates on the screen. This information is used, for example
  105        * to handle mouse clicks and the mouse cursor. The offset is relative to
  106        * the composed text, so offset 0 indicates the beginning of the composed
  107        * text.
  108        *
  109        * <p>
  110        * Return null if the location is outside the area occupied by the composed
  111        * text.
  112        *
  113        * @param x the absolute x coordinate on screen
  114        * @param y the absolute y coordinate on screen
  115        * @return a text hit info describing the offset in the composed text.
  116        */
  117       TextHitInfo getLocationOffset(int x, int y);
  118   
  119       /**
  120        * Gets the offset of the insert position in the committed text contained
  121        * in the text editing component. This is the offset at which characters
  122        * entered through an input method are inserted. This information is used
  123        * by an input method, for example, to examine the text surrounding the
  124        * insert position.
  125        *
  126        * @return the offset of the insert position
  127        */
  128       int getInsertPositionOffset();
  129   
  130       /**
  131        * Gets an iterator providing access to the entire text and attributes
  132        * contained in the text editing component except for uncommitted
  133        * text. Uncommitted (composed) text should be ignored for index
  134        * calculations and should not be made accessible through the iterator.
  135        *
  136        * <p>
  137        * The input method may provide a list of attributes that it is
  138        * interested in. In that case, information about other attributes that
  139        * the implementor may have need not be made accessible through the
  140        * iterator. If the list is null, all available attribute information
  141        * should be made accessible.
  142        *
  143        * @param beginIndex the index of the first character
  144        * @param endIndex the index of the character following the last character
  145        * @param attributes a list of attributes that the input method is
  146        * interested in
  147        * @return an iterator providing access to the text and its attributes
  148        */
  149       AttributedCharacterIterator getCommittedText(int beginIndex, int endIndex,
  150                                                    Attribute[] attributes);
  151   
  152       /**
  153        * Gets the length of the entire text contained in the text
  154        * editing component except for uncommitted (composed) text.
  155        *
  156        * @return the length of the text except for uncommitted text
  157        */
  158       int getCommittedTextLength();
  159   
  160       /**
  161        * Gets the latest committed text from the text editing component and
  162        * removes it from the component's text body.
  163        * This is used for the "Undo Commit" feature in some input methods, where
  164        * the committed text reverts to its previous composed state. The composed
  165        * text will be sent to the component using an InputMethodEvent.
  166        *
  167        * <p>
  168        * Generally, this feature should only be supported immediately after the
  169        * text was committed, not after the user performed other operations on the
  170        * text. When the feature is not supported, return null.
  171        *
  172        * <p>
  173        * The input method may provide a list of attributes that it is
  174        * interested in. In that case, information about other attributes that
  175        * the implementor may have need not be made accessible through the
  176        * iterator. If the list is null, all available attribute information
  177        * should be made accessible.
  178        *
  179        * @param attributes a list of attributes that the input method is
  180        * interested in
  181        * @return the latest committed text, or null when the "Undo Commit"
  182        * feature is not supported
  183        */
  184       AttributedCharacterIterator cancelLatestCommittedText(Attribute[] attributes);
  185   
  186       /**
  187        * Gets the currently selected text from the text editing component.
  188        * This may be used for a variety of purposes.
  189        * One of them is the "Reconvert" feature in some input methods.
  190        * In this case, the input method will typically send an input method event
  191        * to replace the selected text with composed text. Depending on the input
  192        * method's capabilities, this may be the original composed text for the
  193        * selected text, the latest composed text entered anywhere in the text, or
  194        * a version of the text that's converted back from the selected text.
  195        *
  196        * <p>
  197        * The input method may provide a list of attributes that it is
  198        * interested in. In that case, information about other attributes that
  199        * the implementor may have need not be made accessible through the
  200        * iterator. If the list is null, all available attribute information
  201        * should be made accessible.
  202        *
  203        * @param attributes a list of attributes that the input method is
  204        * interested in
  205        * @return the currently selected text
  206        */
  207       AttributedCharacterIterator getSelectedText(Attribute[] attributes);
  208   }

Home » openjdk-7 » java » awt » im » [javadoc | source]