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