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