1 /* 2 * Copyright (c) 1997, 2004, 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.spi; 27 28 import java.util.Locale; 29 import java.awt.AWTEvent; 30 import java.awt.Rectangle; 31 import java.lang.Character.Subset; 32 33 34 /** 35 * Defines the interface for an input method that supports complex text input. 36 * Input methods traditionally support text input for languages that have 37 * more characters than can be represented on a standard-size keyboard, 38 * such as Chinese, Japanese, and Korean. However, they may also be used to 39 * support phonetic text input for English or character reordering for Thai. 40 * <p> 41 * Subclasses of InputMethod can be loaded by the input method framework; they 42 * can then be selected either through the API 43 * ({@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod}) 44 * or the user interface (the input method selection menu). 45 * 46 * @since 1.3 47 * 48 * @author JavaSoft International 49 */ 50 51 public interface InputMethod { 52 53 /** 54 * Sets the input method context, which is used to dispatch input method 55 * events to the client component and to request information from 56 * the client component. 57 * <p> 58 * This method is called once immediately after instantiating this input 59 * method. 60 * 61 * @param context the input method context for this input method 62 * @exception NullPointerException if <code>context</code> is null 63 */ 64 public void setInputMethodContext(InputMethodContext context); 65 66 /** 67 * Attempts to set the input locale. If the input method supports the 68 * desired locale, it changes its behavior to support input for the locale 69 * and returns true. 70 * Otherwise, it returns false and does not change its behavior. 71 * <p> 72 * This method is called 73 * <ul> 74 * <li>by {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod}, 75 * <li>when switching to this input method through the user interface if the user 76 * specified a locale or if the previously selected input method's 77 * {@link java.awt.im.spi.InputMethod#getLocale getLocale} method 78 * returns a non-null value. 79 * </ul> 80 * 81 * @param locale locale to input 82 * @return whether the specified locale is supported 83 * @exception NullPointerException if <code>locale</code> is null 84 */ 85 public boolean setLocale(Locale locale); 86 87 /** 88 * Returns the current input locale. Might return null in exceptional cases. 89 * <p> 90 * This method is called 91 * <ul> 92 * <li>by {@link java.awt.im.InputContext#getLocale InputContext.getLocale} and 93 * <li>when switching from this input method to a different one through the 94 * user interface. 95 * </ul> 96 * 97 * @return the current input locale, or null 98 */ 99 public Locale getLocale(); 100 101 /** 102 * Sets the subsets of the Unicode character set that this input method 103 * is allowed to input. Null may be passed in to indicate that all 104 * characters are allowed. 105 * <p> 106 * This method is called 107 * <ul> 108 * <li>immediately after instantiating this input method, 109 * <li>when switching to this input method from a different one, and 110 * <li>by {@link java.awt.im.InputContext#setCharacterSubsets InputContext.setCharacterSubsets}. 111 * </ul> 112 * 113 * @param subsets the subsets of the Unicode character set from which 114 * characters may be input 115 */ 116 public void setCharacterSubsets(Subset[] subsets); 117 118 /** 119 * Enables or disables this input method for composition, 120 * depending on the value of the parameter <code>enable</code>. 121 * <p> 122 * An input method that is enabled for composition interprets incoming 123 * events for both composition and control purposes, while a 124 * disabled input method does not interpret events for composition. 125 * Note however that events are passed on to the input method regardless 126 * whether it is enabled or not, and that an input method that is disabled 127 * for composition may still interpret events for control purposes, 128 * including to enable or disable itself for composition. 129 * <p> 130 * For input methods provided by host operating systems, it is not always possible to 131 * determine whether this operation is supported. For example, an input method may enable 132 * composition only for some locales, and do nothing for other locales. For such input 133 * methods, it is possible that this method does not throw 134 * {@link java.lang.UnsupportedOperationException UnsupportedOperationException}, 135 * but also does not affect whether composition is enabled. 136 * <p> 137 * This method is called 138 * <ul> 139 * <li>by {@link java.awt.im.InputContext#setCompositionEnabled InputContext.setCompositionEnabled}, 140 * <li>when switching to this input method from a different one using the 141 * user interface or 142 * {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod}, 143 * if the previously selected input method's 144 * {@link java.awt.im.spi.InputMethod#isCompositionEnabled isCompositionEnabled} 145 * method returns without throwing an exception. 146 * </ul> 147 * 148 * @param enable whether to enable the input method for composition 149 * @throws UnsupportedOperationException if this input method does not 150 * support the enabling/disabling operation 151 * @see #isCompositionEnabled 152 */ 153 public void setCompositionEnabled(boolean enable); 154 155 /** 156 * Determines whether this input method is enabled. 157 * An input method that is enabled for composition interprets incoming 158 * events for both composition and control purposes, while a 159 * disabled input method does not interpret events for composition. 160 * <p> 161 * This method is called 162 * <ul> 163 * <li>by {@link java.awt.im.InputContext#isCompositionEnabled InputContext.isCompositionEnabled} and 164 * <li>when switching from this input method to a different one using the 165 * user interface or 166 * {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod}. 167 * </ul> 168 * 169 * @return <code>true</code> if this input method is enabled for 170 * composition; <code>false</code> otherwise. 171 * @throws UnsupportedOperationException if this input method does not 172 * support checking whether it is enabled for composition 173 * @see #setCompositionEnabled 174 */ 175 public boolean isCompositionEnabled(); 176 177 /** 178 * Starts the reconversion operation. The input method obtains the 179 * text to be reconverted from the current client component using the 180 * {@link java.awt.im.InputMethodRequests#getSelectedText InputMethodRequests.getSelectedText} 181 * method. It can use other <code>InputMethodRequests</code> 182 * methods to request additional information required for the 183 * reconversion operation. The composed and committed text 184 * produced by the operation is sent to the client component as a 185 * sequence of <code>InputMethodEvent</code>s. If the given text 186 * cannot be reconverted, the same text should be sent to the 187 * client component as committed text. 188 * <p> 189 * This method is called by 190 * {@link java.awt.im.InputContext#reconvert() InputContext.reconvert}. 191 * 192 * @throws UnsupportedOperationException if the input method does not 193 * support the reconversion operation. 194 */ 195 public void reconvert(); 196 197 /** 198 * Dispatches the event to the input method. If input method support is 199 * enabled for the focused component, incoming events of certain types 200 * are dispatched to the current input method for this component before 201 * they are dispatched to the component's methods or event listeners. 202 * The input method decides whether it needs to handle the event. If it 203 * does, it also calls the event's <code>consume</code> method; this 204 * causes the event to not get dispatched to the component's event 205 * processing methods or event listeners. 206 * <p> 207 * Events are dispatched if they are instances of InputEvent or its 208 * subclasses. 209 * This includes instances of the AWT classes KeyEvent and MouseEvent. 210 * <p> 211 * This method is called by {@link java.awt.im.InputContext#dispatchEvent InputContext.dispatchEvent}. 212 * 213 * @param event the event being dispatched to the input method 214 * @exception NullPointerException if <code>event</code> is null 215 */ 216 public void dispatchEvent(AWTEvent event); 217 218 /** 219 * Notifies this input method of changes in the client window 220 * location or state. This method is called while this input 221 * method is the current input method of its input context and 222 * notifications for it are enabled (see {@link 223 * InputMethodContext#enableClientWindowNotification 224 * InputMethodContext.enableClientWindowNotification}). Calls 225 * to this method are temporarily suspended if the input context's 226 * {@link java.awt.im.InputContext#removeNotify removeNotify} 227 * method is called, and resume when the input method is activated 228 * for a new client component. It is called in the following 229 * situations: 230 * <ul> 231 * <li> 232 * when the window containing the current client component changes 233 * in location, size, visibility, iconification state, or when the 234 * window is closed.</li> 235 * <li> 236 * from <code> enableClientWindowNotification(inputMethod, 237 * true)</code> if the current client component exists,</li> 238 * <li> 239 * when activating the input method for the first time after it 240 * called 241 * <code>enableClientWindowNotification(inputMethod, 242 * true)</code> if during the call no current client component was 243 * available,</li> 244 * <li> 245 * when activating the input method for a new client component 246 * after the input context's removeNotify method has been 247 * called.</li> 248 * </ul> 249 * @param bounds client window's {@link 250 * java.awt.Component#getBounds bounds} on the screen; or null if 251 * the client window is iconified or invisible 252 */ 253 public void notifyClientWindowChange(Rectangle bounds); 254 255 /** 256 * Activates the input method for immediate input processing. 257 * <p> 258 * If an input method provides its own windows, it should make sure 259 * at this point that all necessary windows are open and visible. 260 * <p> 261 * This method is called 262 * <ul> 263 * <li>by {@link java.awt.im.InputContext#dispatchEvent InputContext.dispatchEvent} 264 * when a client component receives a FOCUS_GAINED event, 265 * <li>when switching to this input method from a different one using the 266 * user interface or 267 * {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod}. 268 * </ul> 269 * The method is only called when the input method is inactive. 270 * A newly instantiated input method is assumed to be inactive. 271 */ 272 public void activate(); 273 274 /** 275 * Deactivates the input method. 276 * The isTemporary argument has the same meaning as in 277 * {@link java.awt.event.FocusEvent#isTemporary FocusEvent.isTemporary}. 278 * <p> 279 * If an input method provides its own windows, only windows that relate 280 * to the current composition (such as a lookup choice window) should be 281 * closed at this point. 282 * It is possible that the input method will be immediately activated again 283 * for a different client component, and closing and reopening more 284 * persistent windows (such as a control panel) would create unnecessary 285 * screen flicker. 286 * Before an instance of a different input method class is activated, 287 * {@link #hideWindows} is called on the current input method. 288 * <p> 289 * This method is called 290 * <ul> 291 * <li>by {@link java.awt.im.InputContext#dispatchEvent InputContext.dispatchEvent} 292 * when a client component receives a FOCUS_LOST event, 293 * <li>when switching from this input method to a different one using the 294 * user interface or 295 * {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod}, 296 * <li>before {@link #removeNotify removeNotify} if the current client component is 297 * removed. 298 * </ul> 299 * The method is only called when the input method is active. 300 * 301 * @param isTemporary whether the focus change is temporary 302 */ 303 public void deactivate(boolean isTemporary); 304 305 /** 306 * Closes or hides all windows opened by this input method instance or 307 * its class. 308 * <p> 309 * This method is called 310 * <ul> 311 * <li>before calling {@link #activate activate} on an instance of a different input 312 * method class, 313 * <li>before calling {@link #dispose dispose} on this input method. 314 * </ul> 315 * The method is only called when the input method is inactive. 316 */ 317 public void hideWindows(); 318 319 /** 320 * Notifies the input method that a client component has been 321 * removed from its containment hierarchy, or that input method 322 * support has been disabled for the component. 323 * <p> 324 * This method is called by {@link java.awt.im.InputContext#removeNotify InputContext.removeNotify}. 325 * <p> 326 * The method is only called when the input method is inactive. 327 */ 328 public void removeNotify(); 329 330 /** 331 * Ends any input composition that may currently be going on in this 332 * context. Depending on the platform and possibly user preferences, 333 * this may commit or delete uncommitted text. Any changes to the text 334 * are communicated to the active component using an input method event. 335 * 336 * <p> 337 * A text editing component may call this in a variety of situations, 338 * for example, when the user moves the insertion point within the text 339 * (but outside the composed text), or when the component's text is 340 * saved to a file or copied to the clipboard. 341 * <p> 342 * This method is called 343 * <ul> 344 * <li>by {@link java.awt.im.InputContext#endComposition InputContext.endComposition}, 345 * <li>by {@link java.awt.im.InputContext#dispatchEvent InputContext.dispatchEvent} 346 * when switching to a different client component 347 * <li>when switching from this input method to a different one using the 348 * user interface or 349 * {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod}. 350 * </ul> 351 */ 352 public void endComposition(); 353 354 /** 355 * Releases the resources used by this input method. 356 * In particular, the input method should dispose windows and close files that are no 357 * longer needed. 358 * <p> 359 * This method is called by {@link java.awt.im.InputContext#dispose InputContext.dispose}. 360 * <p> 361 * The method is only called when the input method is inactive. 362 * No method of this interface is called on this instance after dispose. 363 */ 364 public void dispose(); 365 366 /** 367 * Returns a control object from this input method, or null. A 368 * control object provides methods that control the behavior of the 369 * input method or obtain information from the input method. The type 370 * of the object is an input method specific class. Clients have to 371 * compare the result against known input method control object 372 * classes and cast to the appropriate class to invoke the methods 373 * provided. 374 * <p> 375 * This method is called by 376 * {@link java.awt.im.InputContext#getInputMethodControlObject InputContext.getInputMethodControlObject}. 377 * 378 * @return a control object from this input method, or null 379 */ 380 public Object getControlObject(); 381 382 }