View Javadoc
1   /*
2    * Copyright (c) 1997, 2013, 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 proceeding 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 }