1 /* 2 * Copyright (c) 1997, 2014, Oracle and/or its affiliates. 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. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * 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.beans.Transient; 32 import java.lang.Character.Subset; 33 import sun.awt.im.InputMethodContext; 34 35 /** 36 * Provides methods to control text input facilities such as input 37 * methods and keyboard layouts. 38 * Two methods handle both input methods and keyboard layouts: selectInputMethod 39 * lets a client component select an input method or keyboard layout by locale, 40 * getLocale lets a client component obtain the locale of the current input method 41 * or keyboard layout. 42 * The other methods more specifically support interaction with input methods: 43 * They let client components control the behavior of input methods, and 44 * dispatch events from the client component to the input method. 45 * 46 * <p> 47 * By default, one InputContext instance is created per Window instance, 48 * and this input context is shared by all components within the window's 49 * container hierarchy. However, this means that only one text input 50 * operation is possible at any one time within a window, and that the 51 * text needs to be committed when moving the focus from one text component 52 * to another. If this is not desired, text components can create their 53 * own input context instances. 54 * 55 * <p> 56 * The Java Platform supports input methods that have been developed in the Java 57 * programming language, using the interfaces in the {@link java.awt.im.spi} package, 58 * and installed into a Java SE Runtime Environment as extensions. Implementations 59 * may also support using the native input methods of the platforms they run on; 60 * however, not all platforms and locales provide input methods. Keyboard layouts 61 * are provided by the host platform. 62 * 63 * <p> 64 * Input methods are <em>unavailable</em> if (a) no input method written 65 * in the Java programming language has been installed and (b) the Java Platform implementation 66 * or the underlying platform does not support native input methods. In this case, 67 * input contexts can still be created and used; their behavior is specified with 68 * the individual methods below. 69 * 70 * @see java.awt.Component#getInputContext 71 * @see java.awt.Component#enableInputMethods 72 * @author JavaSoft Asia/Pacific 73 * @since 1.2 74 */ 75 76 public class InputContext { 77 78 /** 79 * Constructs an InputContext. 80 * This method is protected so clients cannot instantiate 81 * InputContext directly. Input contexts are obtained by 82 * calling {@link #getInstance}. 83 */ 84 protected InputContext() { 85 // real implementation is in sun.awt.im.InputContext 86 } 87 88 /** 89 * Returns a new InputContext instance. 90 * @return a new InputContext instance 91 */ 92 public static InputContext getInstance() { 93 return new sun.awt.im.InputMethodContext(); 94 } 95 96 /** 97 * Attempts to select an input method or keyboard layout that 98 * supports the given locale, and returns a value indicating whether such 99 * an input method or keyboard layout has been successfully selected. The 100 * following steps are taken until an input method has been selected: 101 * 102 * <ul> 103 * <li> 104 * If the currently selected input method or keyboard layout supports the 105 * requested locale, it remains selected.</li> 106 * 107 * <li> 108 * If there is no input method or keyboard layout available that supports 109 * the requested locale, the current input method or keyboard layout remains 110 * selected.</li> 111 * 112 * <li> 113 * If the user has previously selected an input method or keyboard layout 114 * for the requested locale from the user interface, then the most recently 115 * selected such input method or keyboard layout is reselected.</li> 116 * 117 * <li> 118 * Otherwise, an input method or keyboard layout that supports the requested 119 * locale is selected in an implementation dependent way.</li> 120 * 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 @Transient 235 public boolean isCompositionEnabled() { 236 // real implementation is in sun.awt.im.InputContext 237 return false; 238 } 239 240 /** 241 * Asks the current input method to reconvert text from the 242 * current client component. The input method obtains the text to 243 * be reconverted from the client component using the 244 * {@link InputMethodRequests#getSelectedText InputMethodRequests.getSelectedText} 245 * method. The other <code>InputMethodRequests</code> methods 246 * must be prepared to deal with further information requests by 247 * the input method. The composed and/or committed text will be 248 * sent to the client component as a sequence of 249 * <code>InputMethodEvent</code>s. If the input method cannot 250 * reconvert the given text, the text is returned as committed 251 * text in an <code>InputMethodEvent</code>. 252 * 253 * @throws UnsupportedOperationException if there is no current input 254 * method available or the current input method does not support 255 * the reconversion operation. 256 * 257 * @since 1.3 258 */ 259 public void reconvert() { 260 // real implementation is in sun.awt.im.InputContext 261 } 262 263 /** 264 * Dispatches an event to the active input method. Called by AWT. 265 * If no input method is available, then the event will never be consumed. 266 * 267 * @param event The event 268 * @exception NullPointerException if <code>event</code> is null 269 */ 270 public void dispatchEvent(AWTEvent event) { 271 // real implementation is in sun.awt.im.InputContext 272 } 273 274 /** 275 * Notifies the input context that a client component has been 276 * removed from its containment hierarchy, or that input method 277 * support has been disabled for the component. This method is 278 * usually called from the client component's 279 * {@link java.awt.Component#removeNotify() Component.removeNotify} 280 * method. Potentially pending input from input methods 281 * for this component is discarded. 282 * If no input methods are available, then this method has no effect. 283 * 284 * @param client Client component 285 * @exception NullPointerException if <code>client</code> is null 286 */ 287 public void removeNotify(Component client) { 288 // real implementation is in sun.awt.im.InputContext 289 } 290 291 /** 292 * Ends any input composition that may currently be going on in this 293 * context. Depending on the platform and possibly user preferences, 294 * this may commit or delete uncommitted text. Any changes to the text 295 * are communicated to the active component using an input method event. 296 * If no input methods are available, then this method has no effect. 297 * 298 * <p> 299 * A text editing component may call this in a variety of situations, 300 * for example, when the user moves the insertion point within the text 301 * (but outside the composed text), or when the component's text is 302 * saved to a file or copied to the clipboard. 303 * 304 */ 305 public void endComposition() { 306 // real implementation is in sun.awt.im.InputContext 307 } 308 309 /** 310 * Releases the resources used by this input context. 311 * Called by AWT for the default input context of each Window. 312 * If no input methods are available, then this method 313 * has no effect. 314 */ 315 public void dispose() { 316 // real implementation is in sun.awt.im.InputContext 317 } 318 319 /** 320 * Returns a control object from the current input method, or null. A 321 * control object provides methods that control the behavior of the 322 * input method or obtain information from the input method. The type 323 * of the object is an input method specific class. Clients have to 324 * compare the result against known input method control object 325 * classes and cast to the appropriate class to invoke the methods 326 * provided. 327 * <p> 328 * If no input methods are available or the current input method does 329 * not provide an input method control object, then null is returned. 330 * 331 * @return A control object from the current input method, or null. 332 */ 333 public Object getInputMethodControlObject() { 334 // real implementation is in sun.awt.im.InputContext 335 return null; 336 } 337 338 }