InputContext


1   /*
2    * @(#)InputContext.java    1.34 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.Component  ;
11  import java.util.Locale  ;
12  import java.awt.AWTEvent  ;
13  import java.lang.Character.Subset;
14  import sun.awt.im.InputMethodContext;
15  
16  /**
17   * Provides methods to control text input facilities such as input
18   * methods and keyboard layouts.
19   * Two methods handle both input methods and keyboard layouts: selectInputMethod
20   * lets a client component select an input method or keyboard layout by locale,
21   * getLocale lets a client component obtain the locale of the current input method
22   * or keyboard layout.
23   * The other methods more specifically support interaction with input methods:
24   * They let client components control the behavior of input methods, and
25   * dispatch events from the client component to the input method.
26   *
27   * <p>
28   * By default, one InputContext instance is created per Window instance,
29   * and this input context is shared by all components within the window's
30   * container hierarchy. However, this means that only one text input
31   * operation is possible at any one time within a window, and that the
32   * text needs to be committed when moving the focus from one text component
33   * to another. If this is not desired, text components can create their
34   * own input context instances.
35   *
36   * <p>
37   * The Java 2 platform supports input methods that have been developed in the Java
38   * programming language, using the interfaces in the {@link java.awt.im.spi} package,
39   * and installed into a Java 2 runtime environment as extensions. Implementations
40   * may also support using the native input methods of the platforms they run on;
41   * however, not all platforms and locales provide input methods. Keyboard layouts
42   * are provided by the host platform.
43   *
44   * <p>
45   * Input methods are <em>unavailable</em> if (a) no input method written
46   * in the Java programming language has been installed and (b) the Java 2 implementation
47   * or the underlying platform does not support native input methods. In this case,
48   * input contexts can still be created and used; their behavior is specified with
49   * the individual methods below.
50   *
51   * @see java.awt.Component#getInputContext
52   * @see java.awt.Component#enableInputMethods
53   * @version     1.34, 12/19/03
54   * @author JavaSoft Asia/Pacific
55   * @since 1.2
56   */
57  
58  public class InputContext {
59  
60      /**
61       * Constructs an InputContext.
62       * This method is protected so clients cannot instantiate
63       * InputContext directly. Input contexts are obtained by
64       * calling {@link #getInstance}.
65       */
66      protected InputContext() {
67          // real implementation is in sun.awt.im.InputContext
68      }
69  
70      /**
71       * Returns a new InputContext instance.
72       */
73      public static InputContext   getInstance() {
74      return new sun.awt.im.InputMethodContext();
75      }
76  
77      /**
78       * Attempts to select an input method or keyboard layout that
79       * supports the given locale, and returns a value indicating whether such
80       * an input method or keyboard layout has been successfully selected. The
81       * following steps are taken until an input method has been selected:
82       *
83       * <p>
84       * <ul>
85       * <li>
86       * If the currently selected input method or keyboard layout supports the
87       * requested locale, it remains selected.</li>
88       *
89       * <li>
90       * If there is no input method or keyboard layout available that supports
91       * the requested locale, the current input method or keyboard layout remains
92       * selected.</li>
93       *
94       * <li>
95       * If the user has previously selected an input method or keyboard layout
96       * for the requested locale from the user interface, then the most recently
97       * selected such input method or keyboard layout is reselected.</li>
98       *
99       * <li>
100      * Otherwise, an input method or keyboard layout that supports the requested
101      * locale is selected in an implementation dependent way.</li>
102      *
103      * <p>
104      * </ul>
105      * Before switching away from an input method, any currently uncommitted text
106      * is committed. If no input method or keyboard layout supporting the requested
107      * locale is available, then false is returned.
108      *
109      * <p>
110      * Not all host operating systems provide API to determine the locale of
111      * the currently selected native input method or keyboard layout, and to
112      * select a native input method or keyboard layout by locale.
113      * For host operating systems that don't provide such API,
114      * <code>selectInputMethod</code> assumes that native input methods or
115      * keyboard layouts provided by the host operating system support only the
116      * system's default locale.
117      *
118      * <p>
119      * A text editing component may call this method, for example, when
120      * the user changes the insertion point, so that the user can
121      * immediately continue typing in the language of the surrounding text.
122      *
123      * @param locale The desired new locale.
124      * @return true if the input method or keyboard layout that's active after
125      *         this call supports the desired locale.
126      * @exception NullPointerException if <code>locale</code> is null
127      */
128     public boolean selectInputMethod(Locale   locale) {
129         // real implementation is in sun.awt.im.InputContext
130         return false;
131     }
132 
133     /**
134      * Returns the current locale of the current input method or keyboard
135      * layout.
136      * Returns null if the input context does not have a current input method
137      * or keyboard layout or if the current input method's
138      * {@link java.awt.im.spi.InputMethod#getLocale()} method returns null.
139      *
140      * <p>
141      * Not all host operating systems provide API to determine the locale of
142      * the currently selected native input method or keyboard layout.
143      * For host operating systems that don't provide such API,
144      * <code>getLocale</code> assumes that the current locale of all native
145      * input methods or keyboard layouts provided by the host operating system
146      * is the system's default locale.
147      *
148      * @return the current locale of the current input method or keyboard layout
149      * @since 1.3
150      */
151     public Locale   getLocale() {
152         // real implementation is in sun.awt.im.InputContext
153         return null;
154     }
155     
156     /**
157      * Sets the subsets of the Unicode character set that input methods of this input
158      * context should be allowed to input. Null may be passed in to
159      * indicate that all characters are allowed. The initial value
160      * is null. The setting applies to the current input method as well
161      * as input methods selected after this call is made. However,
162      * applications cannot rely on this call having the desired effect,
163      * since this setting cannot be passed on to all host input methods -
164      * applications still need to apply their own character validation.
165      * If no input methods are available, then this method has no effect.
166      *
167      * @param subsets The subsets of the Unicode character set from which characters may be input
168      */
169     public void setCharacterSubsets(Subset[] subsets) {
170         // real implementation is in sun.awt.im.InputContext
171     }
172 
173     /**
174      * Enables or disables the current input method for composition,
175      * depending on the value of the parameter <code>enable</code>.
176      * <p>
177      * An input method that is enabled for composition interprets incoming
178      * events for both composition and control purposes, while a
179      * disabled input method does not interpret events for composition.
180      * Note however that events are passed on to the input method regardless
181      * whether it is enabled or not, and that an input method that is disabled
182      * for composition may still interpret events for control purposes,
183      * including to enable or disable itself for composition.
184      * <p>
185      * For input methods provided by host operating systems, it is not always possible to 
186      * determine whether this operation is supported. For example, an input method may enable
187      * composition only for some locales, and do nothing for other locales. For such input 
188      * methods, it is possible that this method does not throw 
189      * {@link java.lang.UnsupportedOperationException UnsupportedOperationException},
190      * but also does not affect whether composition is enabled.
191      *
192      * @param enable whether to enable the current input method for composition
193      * @throws UnsupportedOperationException if there is no current input
194      * method available or the current input method does not support
195      * the enabling/disabling operation
196      * @see #isCompositionEnabled
197      * @since 1.3
198      */
199     public void setCompositionEnabled(boolean enable) {
200     // real implementation is in sun.awt.im.InputContext
201     }
202 
203     /**
204      * Determines whether the current input method is enabled for composition.
205      * An input method that is enabled for composition interprets incoming
206      * events for both composition and control purposes, while a
207      * disabled input method does not interpret events for composition.
208      *
209      * @return <code>true</code> if the current input method is enabled for
210      * composition; <code>false</code> otherwise
211      * @throws UnsupportedOperationException if there is no current input
212      * method available or the current input method does not support
213      * checking whether it is enabled for composition
214      * @see #setCompositionEnabled
215      * @since 1.3
216      */
217     public boolean isCompositionEnabled() {
218     // real implementation is in sun.awt.im.InputContext
219     return false;
220     }
221 
222     /**
223      * Asks the current input method to reconvert text from the
224      * current client component. The input method obtains the text to
225      * be reconverted from the client component using the
226      * {@link InputMethodRequests#getSelectedText InputMethodRequests.getSelectedText}
227      * method. The other <code>InputMethodRequests</code> methods
228      * must be prepared to deal with further information requests by
229      * the input method. The composed and/or committed text will be
230      * sent to the client component as a sequence of
231      * <code>InputMethodEvent</code>s. If the input method cannot
232      * reconvert the given text, the text is returned as committed
233      * text in an <code>InputMethodEvent</code>.
234      *
235      * @throws UnsupportedOperationException if there is no current input
236      * method available or the current input method does not support
237      * the reconversion operation.
238      *
239      * @since 1.3
240      */
241     public void reconvert() {
242     // real implementation is in sun.awt.im.InputContext
243     }
244 
245     /**
246      * Dispatches an event to the active input method. Called by AWT.
247      * If no input method is available, then the event will never be consumed.
248      *
249      * @param event The event
250      * @exception NullPointerException if <code>event</code> is null
251      */
252     public void dispatchEvent(AWTEvent   event) {
253         // real implementation is in sun.awt.im.InputContext
254     }
255 
256     /**
257      * Notifies the input context that a client component has been
258      * removed from its containment hierarchy, or that input method
259      * support has been disabled for the component. This method is
260      * usually called from the client component's
261      * {@link java.awt.Component#removeNotify() Component.removeNotify}
262      * method. Potentially pending input from input methods
263      * for this component is discarded.
264      * If no input methods are available, then this method has no effect.
265      *
266      * @param client Client component
267      * @exception NullPointerException if <code>client</code> is null
268      */
269     public void removeNotify(Component   client) {
270     // real implementation is in sun.awt.im.InputContext
271     }
272 
273     /**
274      * Ends any input composition that may currently be going on in this
275      * context. Depending on the platform and possibly user preferences,
276      * this may commit or delete uncommitted text. Any changes to the text
277      * are communicated to the active component using an input method event.
278      * If no input methods are available, then this method has no effect.
279      *
280      * <p>
281      * A text editing component may call this in a variety of situations,
282      * for example, when the user moves the insertion point within the text
283      * (but outside the composed text), or when the component's text is
284      * saved to a file or copied to the clipboard.
285      *
286      */
287     public void endComposition() {
288         // real implementation is in sun.awt.im.InputContext
289     }
290 
291     /**
292      * Disposes of the input context and release the resources used by it.
293      * Called by AWT for the default input context of each Window.
294      * If no input methods are available, then this method
295      * has no effect.
296      */
297     public void dispose() {
298         // real implementation is in sun.awt.im.InputContext
299     }
300 
301     /**
302      * Returns a control object from the current input method, or null. A
303      * control object provides methods that control the behavior of the
304      * input method or obtain information from the input method. The type
305      * of the object is an input method specific class. Clients have to
306      * compare the result against known input method control object
307      * classes and cast to the appropriate class to invoke the methods
308      * provided.
309      * <p>
310      * If no input methods are available or the current input method does
311      * not provide an input method control object, then null is returned.
312      *
313      * @return A control object from the current input method, or null.
314      */
315     public Object   getInputMethodControlObject() {
316         // real implementation is in sun.awt.im.InputContext
317         return null;
318     }
319 
320 }
321
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags