1: /* InputContext.java -- provides the context for text input 2: Copyright (C) 2002, 2003, 2004, 2005 Free Software Foundation, Inc. 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: 39: package java.awt.im; 40: 41: import gnu.java.util.EmptyEnumeration; 42: 43: import java.awt.AWTEvent; 44: import java.awt.AWTException; 45: import java.awt.Component; 46: import java.awt.im.spi.InputMethod; 47: import java.awt.im.spi.InputMethodDescriptor; 48: import java.io.BufferedReader; 49: import java.io.IOException; 50: import java.io.InputStreamReader; 51: import java.net.URL; 52: import java.text.AttributedCharacterIterator.Attribute; 53: import java.util.ArrayList; 54: import java.util.Enumeration; 55: import java.util.HashMap; 56: import java.util.Locale; 57: 58: /** 59: * Provides a context for controlling input methods and keyboard layouts. 60: * This class provides the communication layer between the client component, 61: * and the various locale-dependent text entry input methods that can be used 62: * for the client. By default, there is one instance per Window, shared among 63: * all components, but this limits text entry to one component at a time. 64: * Thus, text components can create their own instance to allow text entry 65: * in multiple components at a time. 66: * 67: * <p>By using the interfaces of {@link java.awt.im.spi}, you can install 68: * extensions which allow additional input methods. Some of these may use 69: * platform native input methods, or keyboard layouts provided by the platform. 70: * Input methods are unavailable if none have been installed and the platform 71: * has no underlying native input methods. Extensions are installed as jar 72: * files, usually accessed in the default extension location or specified by 73: * the -extdir VM flag. The jar must contain a file named 74: * "META_INF/services/java.awt.im.spi.InputMethodDescriptor" which lists, 75: * one entry per line in UTF-8 encoding, each class in the jar that implements 76: * java.awt.im.spi.InputMethodDescriptor. 77: * 78: * @author Eric Blake (ebb9@email.byu.edu) 79: * @author Andrew John Hughes (gnu_andrew@member.fsf.org) 80: * @see Component#getInputContext() 81: * @see Component#enableInputMethods(boolean) 82: * @since 1.2 83: * @status updated to 1.4, but unverified 84: */ 85: public class InputContext 86: { 87: /** 88: * The list of installed input method descriptors. 89: */ 90: private static final ArrayList<InputMethodDescriptor> descriptors 91: = new ArrayList<InputMethodDescriptor>(); 92: 93: static 94: { 95: Enumeration e; 96: try 97: { 98: e = ClassLoader.getSystemResources 99: ("META_INF/services/java.awt.im.spi.InputMethodDescriptor"); 100: } 101: catch (IOException ex) 102: { 103: // XXX Should we do something else? 104: e = EmptyEnumeration.getInstance(); 105: } 106: while (e.hasMoreElements()) 107: { 108: URL url = (URL) e.nextElement(); 109: BufferedReader in; 110: String line; 111: try 112: { 113: in = new BufferedReader 114: (new InputStreamReader(url.openConnection().getInputStream(), 115: "UTF-8")); 116: line = in.readLine().trim(); 117: } 118: catch (IOException ignored) 119: { 120: continue; 121: } 122: outer: 123: while (line != null) 124: { 125: try 126: { 127: if (line.charAt(0) != '#') 128: { 129: Class<?> c = Class.forName(line); 130: descriptors.add((InputMethodDescriptor) c.newInstance()); 131: } 132: line = in.readLine().trim(); 133: } 134: catch (IOException ex) 135: { 136: continue outer; 137: } 138: catch (Exception ignored) 139: { 140: } 141: } 142: } 143: } 144: 145: /** The current input method; null if no input methods are installed. */ 146: private InputMethod im; 147: 148: /** Map of locales to the most recently selected input method. */ 149: private final HashMap<Locale,InputMethod> recent 150: = new HashMap<Locale,InputMethod>(); 151: 152: /** The list of acceptable character subsets. */ 153: private Character.Subset[] subsets; 154: 155: /** 156: * Construct an InputContext. This is protected, so clients must use 157: * {@link #getInstance()} instead. 158: */ 159: protected InputContext() 160: { 161: } 162: 163: /** 164: * Returns a new InputContext. 165: * 166: * @return a new instance, initialized to the default locale if available 167: */ 168: public static InputContext getInstance() 169: { 170: InputContext ic = new InputContext(); 171: ic.selectInputMethod(Locale.getDefault()); 172: return ic; 173: } 174: 175: /** 176: * Attempts to select an input method or keyboard layout which supports the 177: * given locale. This returns true if a locale is available and was selected. 178: * The following steps are taken in choosing an input method:<ul> 179: * <li>If the currently selected input method or keyboard layout supports 180: * the requested locale, it remains selected.</li> 181: * <li>If there is no input method or keyboard layout available that 182: * supports the requested locale, the current input method or keyboard 183: * layout remains selected.</li> 184: * <li>If the user has previously selected an input method or keyboard 185: * layout for the requested locale from the user interface, then the most 186: * recently selected such input method or keyboard layout is reselected.</li> 187: * <li>Otherwise, an input method or keyboard layout that supports the 188: * requested locale is selected in an implementation dependent way. This 189: * implementation chooses the first input method which supports the requested 190: * locale based on the InputMethodDescriptors loaded from the extensions 191: * installed on the CLASSPATH.</li> 192: * </ul> 193: * 194: * <p>Before switching away from an input method, any currently uncommitted 195: * text is committed. Not all host operating systems provide API to 196: * determine the locale of the currently selected native input method or 197: * keyboard layout, and to select a native input method or keyboard layout 198: * by locale. For host operating systems that don't provide such API, 199: * selectInputMethod assumes that native input methods or keyboard layouts 200: * provided by the host operating system support only the system's default 201: * locale. 202: * 203: * <p>An example of where this may be called is in a multi-language document, 204: * when moving the insertion point between sections of different locale, so 205: * that the user may use the input method appropriate to that section of the 206: * document. 207: * 208: * @param locale the desired new locale 209: * @return true if the new locale is active 210: * @throws NullPointerException if locale is null 211: */ 212: public boolean selectInputMethod(Locale locale) 213: { 214: if (im != null && im.setLocale(locale)) 215: { 216: recent.put(locale, im); 217: return true; 218: } 219: InputMethod next = (InputMethod) recent.get(locale); 220: outer: 221: if (next != null) 222: for (int i = 0, limit = descriptors.size(); i < limit; i++) 223: { 224: InputMethodDescriptor d = (InputMethodDescriptor) descriptors.get(i); 225: Locale[] list; 226: try 227: { 228: list = d.getAvailableLocales(); 229: } 230: catch (AWTException ignored) 231: { 232: continue; 233: } 234: for (int j = list.length; --j >= 0; ) 235: if (locale.equals(list[j])) 236: { 237: try 238: { 239: next = d.createInputMethod(); 240: recent.put(locale, next); 241: } 242: catch (Exception ignored) 243: { 244: continue; 245: } 246: } 247: } 248: if (next == null) 249: return false; 250: // XXX I'm not sure if this does all the necessary steps in the switch. 251: if (im != null) 252: { 253: try 254: { 255: next.setCompositionEnabled(im.isCompositionEnabled()); 256: } 257: catch (UnsupportedOperationException ignored) 258: { 259: } 260: im.endComposition(); 261: im.deactivate(false); 262: im.hideWindows(); 263: } 264: im = next; 265: im.setLocale(locale); 266: im.setCharacterSubsets(subsets); 267: return true; 268: } 269: 270: /** 271: * Returns the current locale of the current input method or keyboard 272: * layout. Returns null if the input context does not have a current input 273: * method or keyboard layout or if the current input method's 274: * {@link InputMethod#getLocale()} method returns null. Not all host 275: * operating systems provide API to determine the locale of the currently 276: * selected native input method or keyboard layout. For host operating 277: * systems that don't provide such API, getLocale assumes that the current 278: * locale of all native input methods or keyboard layouts provided by the 279: * host operating system is the system's default locale. 280: * 281: * @return the locale of the current input method, or null 282: * @since 1.3 283: */ 284: public Locale getLocale() 285: { 286: return im == null ? null : im.getLocale(); 287: } 288: 289: /** 290: * Sets the subsets of Unicode characters allowed to be input by the current 291: * input method, as well as subsequent input methods. The value of null 292: * implies all characters are legal. Applications should not rely on this 293: * behavior, since native host input methods may not allow restrictions. 294: * If no current input method is available, this has no immediate effect. 295: * 296: * @param subsets the set of Unicode subsets to accept, or null 297: */ 298: public void setCharacterSubsets(Character.Subset[] subsets) 299: { 300: this.subsets = subsets; 301: if (im != null) 302: im.setCharacterSubsets(subsets); 303: } 304: 305: /** 306: * Changes the enabled status of the current input method. An input method 307: * that is enabled for composition interprets incoming events for both 308: * composition and control purposes, while a disabled input method only 309: * interprets control commands (including commands to enable itself). 310: * 311: * @param enable whether to enable the input method 312: * @throws UnsupportedOperationException if there is no current input method, 313: * or the input method does not support enabling 314: * @see #isCompositionEnabled() 315: * @since 1.3 316: */ 317: public void setCompositionEnabled(boolean enable) 318: { 319: if (im == null) 320: throw new UnsupportedOperationException(); 321: im.setCompositionEnabled(enable); 322: } 323: 324: /** 325: * Find out if the current input method is enabled. 326: * 327: * @return true if the current input method is enabled 328: * @throws UnsupportedOperationException if there is no current input method, 329: * or the input method does not support enabling 330: * @see #setCompositionEnabled(boolean) 331: * @since 1.3 332: */ 333: public boolean isCompositionEnabled() 334: { 335: if (im == null) 336: throw new UnsupportedOperationException(); 337: return im.isCompositionEnabled(); 338: } 339: 340: /** 341: * Starts a reconversion operation in the current input method. The input 342: * method gets the text to reconvert from the client component, using 343: * {@link InputMethodRequests#getSelectedText(Attribute[])}. Then the 344: * composed and committed text produced by the operation is sent back to 345: * the client using a sequence of InputMethodRequests. 346: * 347: * @throws UnsupportedOperationException if there is no current input method, 348: * or the input method does not support reconversion 349: * @since 1.3 350: */ 351: public void reconvert() 352: { 353: if (im == null) 354: throw new UnsupportedOperationException(); 355: im.reconvert(); 356: } 357: 358: /** 359: * Dispatches an event to the current input method. This is called 360: * automatically by AWT. If no input method is available, then the event 361: * will never be consumed. 362: * 363: * @param event the event to dispatch 364: * @throws NullPointerException if event is null 365: */ 366: public void dispatchEvent(AWTEvent event) 367: { 368: if (im != null) 369: im.dispatchEvent(event); 370: } 371: 372: /** 373: * Notifies the input context that a client component has been removed from 374: * its containment hierarchy, or that input method support has been disabled 375: * for the component. This method is usually called from the client 376: * component's {@link Component#removeNotify()} method. Potentially pending 377: * input from input methods for this component is discarded. If no input 378: * methods are available, then this method has no effect. 379: * 380: * @param client the client component 381: * @throws NullPointerException if client is null 382: */ 383: public void removeNotify(Component client) 384: { 385: // XXX What to do with client information? 386: if (im != null) 387: { 388: im.deactivate(false); 389: im.removeNotify(); 390: } 391: } 392: 393: /** 394: * Ends any input composition that may currently be going on in this 395: * context. Depending on the platform and possibly user preferences, this 396: * may commit or delete uncommitted text. Any changes to the text are 397: * communicated to the active component using an input method event. If no 398: * input methods are available, then this method has no effect. This may 399: * be called for a variety of reasons, such as when the user moves the 400: * insertion point in the client text outside the range of the composed text, 401: * or when text is saved to file. 402: */ 403: public void endComposition() 404: { 405: if (im != null) 406: im.endComposition(); 407: } 408: 409: /** 410: * Disposes of the input context and release the resources used by it. 411: * Called automatically by AWT for the default input context of each 412: * Window. If no input methods are available, then this method has no 413: * effect. 414: */ 415: public void dispose() 416: { 417: if (im != null) 418: { 419: im.deactivate(false); 420: im.dispose(); 421: } 422: } 423: 424: /** 425: * Returns a control object from the current input method, or null. A 426: * control object provides implementation-dependent methods that control 427: * the behavior of the input method or obtain information from the input 428: * method. Clients have to compare the result against known input method 429: * control object types. If no input methods are available or the current 430: * input method does not provide an input method control object, then null 431: * is returned. 432: * 433: * @return the control object, or null 434: */ 435: public Object getInputMethodControlObject() 436: { 437: return im == null ? null : im.getControlObject(); 438: } 439: } // class InputContext