001 /*
002 * Copyright 1997-1999 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.awt.im;
027
028 import java.awt.Rectangle;
029 import java.awt.font.TextHitInfo;
030 import java.text.AttributedCharacterIterator;
031 import java.text.AttributedCharacterIterator.Attribute;
032
033 /**
034 * InputMethodRequests defines the requests that a text editing component
035 * has to handle in order to work with input methods. The component
036 * can implement this interface itself or use a separate object that
037 * implements it. The object implementing this interface must be returned
038 * from the component's getInputMethodRequests method.
039 *
040 * <p>
041 * The text editing component also has to provide an input method event
042 * listener.
043 *
044 * <p>
045 * The interface is designed to support one of two input user interfaces:
046 * <ul>
047 * <li><em>on-the-spot</em> input, where the composed text is displayed as part
048 * of the text component's text body.
049 * <li><em>below-the-spot</em> input, where the composed text is displayed in
050 * a separate composition window just below the insertion point where
051 * the text will be inserted when it is committed. Note that, if text is
052 * selected within the component's text body, this text will be replaced by
053 * the committed text upon commitment; therefore it is not considered part
054 * of the context that the text is input into.
055 * </ul>
056 *
057 * @see java.awt.Component#getInputMethodRequests
058 * @see java.awt.event.InputMethodListener
059 *
060 * @version 1.25, 05/05/07
061 * @author JavaSoft Asia/Pacific
062 * @since 1.2
063 */
064
065 public interface InputMethodRequests {
066
067 /**
068 * Gets the location of a specified offset in the current composed text,
069 * or of the selection in committed text.
070 * This information is, for example, used to position the candidate window
071 * near the composed text, or a composition window near the location
072 * where committed text will be inserted.
073 *
074 * <p>
075 * If the component has composed text (because the most recent
076 * InputMethodEvent sent to it contained composed text), then the offset is
077 * relative to the composed text - offset 0 indicates the first character
078 * in the composed text. The location returned should be for this character.
079 *
080 * <p>
081 * If the component doesn't have composed text, the offset should be ignored,
082 * and the location returned should reflect the beginning (in line
083 * direction) of the highlight in the last line containing selected text.
084 * For example, for horizontal left-to-right text (such as English), the
085 * location to the left of the left-most character on the last line
086 * containing selected text is returned. For vertical top-to-bottom text,
087 * with lines proceding from right to left, the location to the top of the
088 * left-most line containing selected text is returned.
089 *
090 * <p>
091 * The location is represented as a 0-thickness caret, that is, it has 0
092 * width if the text is drawn horizontally, and 0 height if the text is
093 * drawn vertically. Other text orientations need to be mapped to
094 * horizontal or vertical orientation. The rectangle uses absolute screen
095 * coordinates.
096 *
097 * @param offset the offset within the composed text, if there is composed
098 * text; null otherwise
099 * @return a rectangle representing the screen location of the offset
100 */
101 Rectangle getTextLocation(TextHitInfo offset);
102
103 /**
104 * Gets the offset within the composed text for the specified absolute x
105 * and y coordinates on the screen. This information is used, for example
106 * to handle mouse clicks and the mouse cursor. The offset is relative to
107 * the composed text, so offset 0 indicates the beginning of the composed
108 * text.
109 *
110 * <p>
111 * Return null if the location is outside the area occupied by the composed
112 * text.
113 *
114 * @param x the absolute x coordinate on screen
115 * @param y the absolute y coordinate on screen
116 * @return a text hit info describing the offset in the composed text.
117 */
118 TextHitInfo getLocationOffset(int x, int y);
119
120 /**
121 * Gets the offset of the insert position in the committed text contained
122 * in the text editing component. This is the offset at which characters
123 * entered through an input method are inserted. This information is used
124 * by an input method, for example, to examine the text surrounding the
125 * insert position.
126 *
127 * @return the offset of the insert position
128 */
129 int getInsertPositionOffset();
130
131 /**
132 * Gets an iterator providing access to the entire text and attributes
133 * contained in the text editing component except for uncommitted
134 * text. Uncommitted (composed) text should be ignored for index
135 * calculations and should not be made accessible through the iterator.
136 *
137 * <p>
138 * The input method may provide a list of attributes that it is
139 * interested in. In that case, information about other attributes that
140 * the implementor may have need not be made accessible through the
141 * iterator. If the list is null, all available attribute information
142 * should be made accessible.
143 *
144 * @param beginIndex the index of the first character
145 * @param endIndex the index of the character following the last character
146 * @param attributes a list of attributes that the input method is
147 * interested in
148 * @return an iterator providing access to the text and its attributes
149 */
150 AttributedCharacterIterator getCommittedText(int beginIndex,
151 int endIndex, Attribute[] attributes);
152
153 /**
154 * Gets the length of the entire text contained in the text
155 * editing component except for uncommitted (composed) text.
156 *
157 * @return the length of the text except for uncommitted text
158 */
159 int getCommittedTextLength();
160
161 /**
162 * Gets the latest committed text from the text editing component and
163 * removes it from the component's text body.
164 * This is used for the "Undo Commit" feature in some input methods, where
165 * the committed text reverts to its previous composed state. The composed
166 * text will be sent to the component using an InputMethodEvent.
167 *
168 * <p>
169 * Generally, this feature should only be supported immediately after the
170 * text was committed, not after the user performed other operations on the
171 * text. When the feature is not supported, return null.
172 *
173 * <p>
174 * The input method may provide a list of attributes that it is
175 * interested in. In that case, information about other attributes that
176 * the implementor may have need not be made accessible through the
177 * iterator. If the list is null, all available attribute information
178 * should be made accessible.
179 *
180 * @param attributes a list of attributes that the input method is
181 * interested in
182 * @return the latest committed text, or null when the "Undo Commit"
183 * feature is not supported
184 */
185 AttributedCharacterIterator cancelLatestCommittedText(
186 Attribute[] attributes);
187
188 /**
189 * Gets the currently selected text from the text editing component.
190 * This may be used for a variety of purposes.
191 * One of them is the "Reconvert" feature in some input methods.
192 * In this case, the input method will typically send an input method event
193 * to replace the selected text with composed text. Depending on the input
194 * method's capabilities, this may be the original composed text for the
195 * selected text, the latest composed text entered anywhere in the text, or
196 * a version of the text that's converted back from the selected text.
197 *
198 * <p>
199 * The input method may provide a list of attributes that it is
200 * interested in. In that case, information about other attributes that
201 * the implementor may have need not be made accessible through the
202 * iterator. If the list is null, all available attribute information
203 * should be made accessible.
204 *
205 * @param attributes a list of attributes that the input method is
206 * interested in
207 * @return the currently selected text
208 */
209 AttributedCharacterIterator getSelectedText(Attribute[] attributes);
210 }
|