2
|
1 |
/*
|
5506
|
2 |
* Copyright (c) 1997, 1999, Oracle and/or its affiliates. All rights reserved.
|
2
|
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
|
5506
|
7 |
* published by the Free Software Foundation. Oracle designates this
|
2
|
8 |
* particular file as subject to the "Classpath" exception as provided
|
5506
|
9 |
* by Oracle in the LICENSE file that accompanied this code.
|
2
|
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 |
*
|
5506
|
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.
|
2
|
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,
|
21278
|
86 |
* with lines proceeding from right to left, the location to the top of the
|
2
|
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 |
}
|