| Frames | No Frames |
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 = recent.get(locale); 220: if (next != null) 221: for (int i = 0, limit = descriptors.size(); i < limit; i++) 222: { 223: InputMethodDescriptor d = descriptors.get(i); 224: Locale[] list; 225: try 226: { 227: list = d.getAvailableLocales(); 228: } 229: catch (AWTException ignored) 230: { 231: continue; 232: } 233: for (int j = list.length; --j >= 0; ) 234: if (locale.equals(list[j])) 235: { 236: try 237: { 238: next = d.createInputMethod(); 239: recent.put(locale, next); 240: } 241: catch (Exception ignored) 242: { 243: continue; 244: } 245: } 246: } 247: if (next == null) 248: return false; 249: // XXX I'm not sure if this does all the necessary steps in the switch. 250: if (im != null) 251: { 252: try 253: { 254: next.setCompositionEnabled(im.isCompositionEnabled()); 255: } 256: catch (UnsupportedOperationException ignored) 257: { 258: } 259: im.endComposition(); 260: im.deactivate(false); 261: im.hideWindows(); 262: } 263: im = next; 264: im.setLocale(locale); 265: im.setCharacterSubsets(subsets); 266: return true; 267: } 268: 269: /** 270: * Returns the current locale of the current input method or keyboard 271: * layout. Returns null if the input context does not have a current input 272: * method or keyboard layout or if the current input method's 273: * {@link InputMethod#getLocale()} method returns null. Not all host 274: * operating systems provide API to determine the locale of the currently 275: * selected native input method or keyboard layout. For host operating 276: * systems that don't provide such API, getLocale assumes that the current 277: * locale of all native input methods or keyboard layouts provided by the 278: * host operating system is the system's default locale. 279: * 280: * @return the locale of the current input method, or null 281: * @since 1.3 282: */ 283: public Locale getLocale() 284: { 285: return im == null ? null : im.getLocale(); 286: } 287: 288: /** 289: * Sets the subsets of Unicode characters allowed to be input by the current 290: * input method, as well as subsequent input methods. The value of null 291: * implies all characters are legal. Applications should not rely on this 292: * behavior, since native host input methods may not allow restrictions. 293: * If no current input method is available, this has no immediate effect. 294: * 295: * @param subsets the set of Unicode subsets to accept, or null 296: */ 297: public void setCharacterSubsets(Character.Subset[] subsets) 298: { 299: this.subsets = subsets; 300: if (im != null) 301: im.setCharacterSubsets(subsets); 302: } 303: 304: /** 305: * Changes the enabled status of the current input method. An input method 306: * that is enabled for composition interprets incoming events for both 307: * composition and control purposes, while a disabled input method only 308: * interprets control commands (including commands to enable itself). 309: * 310: * @param enable whether to enable the input method 311: * @throws UnsupportedOperationException if there is no current input method, 312: * or the input method does not support enabling 313: * @see #isCompositionEnabled() 314: * @since 1.3 315: */ 316: public void setCompositionEnabled(boolean enable) 317: { 318: if (im == null) 319: throw new UnsupportedOperationException(); 320: im.setCompositionEnabled(enable); 321: } 322: 323: /** 324: * Find out if the current input method is enabled. 325: * 326: * @return true if the current input method is enabled 327: * @throws UnsupportedOperationException if there is no current input method, 328: * or the input method does not support enabling 329: * @see #setCompositionEnabled(boolean) 330: * @since 1.3 331: */ 332: public boolean isCompositionEnabled() 333: { 334: if (im == null) 335: throw new UnsupportedOperationException(); 336: return im.isCompositionEnabled(); 337: } 338: 339: /** 340: * Starts a reconversion operation in the current input method. The input 341: * method gets the text to reconvert from the client component, using 342: * {@link InputMethodRequests#getSelectedText(Attribute[])}. Then the 343: * composed and committed text produced by the operation is sent back to 344: * the client using a sequence of InputMethodRequests. 345: * 346: * @throws UnsupportedOperationException if there is no current input method, 347: * or the input method does not support reconversion 348: * @since 1.3 349: */ 350: public void reconvert() 351: { 352: if (im == null) 353: throw new UnsupportedOperationException(); 354: im.reconvert(); 355: } 356: 357: /** 358: * Dispatches an event to the current input method. This is called 359: * automatically by AWT. If no input method is available, then the event 360: * will never be consumed. 361: * 362: * @param event the event to dispatch 363: * @throws NullPointerException if event is null 364: */ 365: public void dispatchEvent(AWTEvent event) 366: { 367: if (im != null) 368: im.dispatchEvent(event); 369: } 370: 371: /** 372: * Notifies the input context that a client component has been removed from 373: * its containment hierarchy, or that input method support has been disabled 374: * for the component. This method is usually called from the client 375: * component's {@link Component#removeNotify()} method. Potentially pending 376: * input from input methods for this component is discarded. If no input 377: * methods are available, then this method has no effect. 378: * 379: * @param client the client component 380: * @throws NullPointerException if client is null 381: */ 382: public void removeNotify(Component client) 383: { 384: // XXX What to do with client information? 385: if (im != null) 386: { 387: im.deactivate(false); 388: im.removeNotify(); 389: } 390: } 391: 392: /** 393: * Ends any input composition that may currently be going on in this 394: * context. Depending on the platform and possibly user preferences, this 395: * may commit or delete uncommitted text. Any changes to the text are 396: * communicated to the active component using an input method event. If no 397: * input methods are available, then this method has no effect. This may 398: * be called for a variety of reasons, such as when the user moves the 399: * insertion point in the client text outside the range of the composed text, 400: * or when text is saved to file. 401: */ 402: public void endComposition() 403: { 404: if (im != null) 405: im.endComposition(); 406: } 407: 408: /** 409: * Disposes of the input context and release the resources used by it. 410: * Called automatically by AWT for the default input context of each 411: * Window. If no input methods are available, then this method has no 412: * effect. 413: */ 414: public void dispose() 415: { 416: if (im != null) 417: { 418: im.deactivate(false); 419: im.dispose(); 420: } 421: } 422: 423: /** 424: * Returns a control object from the current input method, or null. A 425: * control object provides implementation-dependent methods that control 426: * the behavior of the input method or obtain information from the input 427: * method. Clients have to compare the result against known input method 428: * control object types. If no input methods are available or the current 429: * input method does not provide an input method control object, then null 430: * is returned. 431: * 432: * @return the control object, or null 433: */ 434: public Object getInputMethodControlObject() 435: { 436: return im == null ? null : im.getControlObject(); 437: } 438: } // class InputContext