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 }