InputMethodRequests


1   /*
2    * @(#)InputMethodRequests.java 1.18 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.awt.im;
9   
10  import java.awt.Rectangle  ;
11  import java.awt.font.TextHitInfo  ;
12  import java.text.AttributedCharacterIterator  ;
13  import java.text.AttributedCharacterIterator.Attribute;
14  
15  /**
16   * InputMethodRequests defines the requests that a text editing component
17   * has to handle in order to work with input methods. The component
18   * can implement this interface itself or use a separate object that
19   * implements it. The object implementing this interface must be returned
20   * from the component's getInputMethodRequests method.
21   *
22   * <p>
23   * The text editing component also has to provide an input method event
24   * listener.
25   *
26   * <p>
27   * The interface is designed to support one of two input user interfaces:
28   * <ul>
29   * <li><em>on-the-spot</em> input, where the composed text is displayed as part
30   *     of the text component's text body.
31   * <li><em>below-the-spot</em> input, where the composed text is displayed in
32   *     a separate composition window just below the insertion point where
33   *     the text will be inserted when it is committed. Note that, if text is
34   *     selected within the component's text body, this text will be replaced by
35   *     the committed text upon commitment; therefore it is not considered part
36   *     of the context that the text is input into.
37   * </ul>
38   *
39   * @see java.awt.Component#getInputMethodRequests
40   * @see java.awt.event.InputMethodListener
41   *
42   * @version     1.18, 12/19/03
43   * @author JavaSoft Asia/Pacific
44   * @since 1.2
45   */
46  
47  public interface InputMethodRequests {
48  
49      /**
50       * Gets the location of a specified offset in the current composed text,
51       * or of the selection in committed text.
52       * This information is, for example, used to position the candidate window
53       * near the composed text, or a composition window near the location
54       * where committed text will be inserted.
55       *
56       * <p>
57       * If the component has composed text (because the most recent
58       * InputMethodEvent sent to it contained composed text), then the offset is
59       * relative to the composed text - offset 0 indicates the first character
60       * in the composed text. The location returned should be for this character.
61       *
62       * <p>
63       * If the component doesn't have composed text, the offset should be ignored,
64       * and the location returned should reflect the beginning (in line
65       * direction) of the highlight in the last line containing selected text.
66       * For example, for horizontal left-to-right text (such as English), the
67       * location to the left of the left-most character on the last line
68       * containing selected text is returned. For vertical top-to-bottom text,
69       * with lines proceding from right to left, the location to the top of the
70       * left-most line containing selected text is returned.
71       *
72       * <p>
73       * The location is represented as a 0-thickness caret, that is, it has 0
74       * width if the text is drawn horizontally, and 0 height if the text is
75       * drawn vertically. Other text orientations need to be mapped to
76       * horizontal or vertical orientation. The rectangle uses absolute screen
77       * coordinates.
78       *
79       * @param offset the offset within the composed text, if there is composed
80       * text; null otherwise
81       * @return a rectangle representing the screen location of the offset
82       */
83      Rectangle   getTextLocation(TextHitInfo   offset);
84  
85      /**
86       * Gets the offset within the composed text for the specified absolute x
87       * and y coordinates on the screen. This information is used, for example
88       * to handle mouse clicks and the mouse cursor. The offset is relative to
89       * the composed text, so offset 0 indicates the beginning of the composed
90       * text.
91       *
92       * <p>
93       * Return null if the location is outside the area occupied by the composed
94       * text.
95       *
96       * @param x the absolute x coordinate on screen
97       * @param y the absolute y coordinate on screen
98       * @return a text hit info describing the offset in the composed text.
99       */
100     TextHitInfo   getLocationOffset(int x, int y);
101 
102     /**
103      * Gets the offset of the insert position in the committed text contained
104      * in the text editing component. This is the offset at which characters
105      * entered through an input method are inserted. This information is used
106      * by an input method, for example, to examine the text surrounding the
107      * insert position.
108      * 
109      * @return the offset of the insert position
110      */
111     int getInsertPositionOffset();
112 
113     /**
114      * Gets an iterator providing access to the entire text and attributes
115      * contained in the text editing component except for uncommitted
116      * text. Uncommitted (composed) text should be ignored for index
117      * calculations and should not be made accessible through the iterator.
118      *
119      * <p>
120      * The input method may provide a list of attributes that it is
121      * interested in. In that case, information about other attributes that
122      * the implementor may have need not be made accessible through the
123      * iterator. If the list is null, all available attribute information
124      * should be made accessible.
125      *
126      * @param beginIndex the index of the first character
127      * @param endIndex the index of the character following the last character
128      * @param attributes a list of attributes that the input method is
129      * interested in
130      * @return an iterator providing access to the text and its attributes
131      */
132     AttributedCharacterIterator   getCommittedText(int beginIndex, int endIndex,
133                                                  Attribute[] attributes);
134 
135     /**
136      * Gets the length of the entire text contained in the text
137      * editing component except for uncommitted (composed) text.
138      *
139      * @return the length of the text except for uncommitted text
140      */
141     int getCommittedTextLength();
142 
143     /**
144      * Gets the latest committed text from the text editing component and
145      * removes it from the component's text body.
146      * This is used for the "Undo Commit" feature in some input methods, where
147      * the committed text reverts to its previous composed state. The composed
148      * text will be sent to the component using an InputMethodEvent.
149      *
150      * <p>
151      * Generally, this feature should only be supported immediately after the
152      * text was committed, not after the user performed other operations on the
153      * text. When the feature is not supported, return null.
154      *
155      * <p>
156      * The input method may provide a list of attributes that it is
157      * interested in. In that case, information about other attributes that
158      * the implementor may have need not be made accessible through the
159      * iterator. If the list is null, all available attribute information
160      * should be made accessible.
161      *
162      * @param attributes a list of attributes that the input method is
163      * interested in
164      * @return the latest committed text, or null when the "Undo Commit"
165      * feature is not supported
166      */
167     AttributedCharacterIterator   cancelLatestCommittedText(Attribute[] attributes);
168 
169     /**
170      * Gets the currently selected text from the text editing component.
171      * This may be used for a variety of purposes.
172      * One of them is the "Reconvert" feature in some input methods.
173      * In this case, the input method will typically send an input method event
174      * to replace the selected text with composed text. Depending on the input
175      * method's capabilities, this may be the original composed text for the
176      * selected text, the latest composed text entered anywhere in the text, or
177      * a version of the text that's converted back from the selected text.
178      *
179      * <p>
180      * The input method may provide a list of attributes that it is
181      * interested in. In that case, information about other attributes that
182      * the implementor may have need not be made accessible through the
183      * iterator. If the list is null, all available attribute information
184      * should be made accessible.
185      *
186      * @param attributes a list of attributes that the input method is
187      * interested in
188      * @return the currently selected text
189      */
190     AttributedCharacterIterator   getSelectedText(Attribute[] attributes);
191 }
192
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags