GNU Classpath (0.20) | |
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: * @see Component#getInputContext() 80: * @see Component#enableInputMethods(boolean) 81: * @since 1.2 82: * @status updated to 1.4, but unverified 83: */ 84: public class InputContext 85: { 86: /** 87: * The list of installed input method descriptors. 88: */ 89: private static final ArrayList descriptors = new ArrayList(); 90: static 91: { 92: Enumeration e; 93: try 94: { 95: e = ClassLoader.getSystemResources 96: ("META_INF/services/java.awt.im.spi.InputMethodDescriptor"); 97: } 98: catch (IOException ex) 99: { 100: // XXX Should we do something else? 101: e = EmptyEnumeration.getInstance(); 102: } 103: while (e.hasMoreElements()) 104: { 105: URL url = (URL) e.nextElement(); 106: BufferedReader in; 107: String line; 108: try 109: { 110: in = new BufferedReader 111: (new InputStreamReader(url.openConnection().getInputStream(), 112: "UTF-8")); 113: line = in.readLine().trim(); 114: } 115: catch (IOException ignored) 116: { 117: continue; 118: } 119: outer: 120: while (line != null) 121: { 122: try 123: { 124: if (line.charAt(0) != '#') 125: { 126: Class c = Class.forName(line); 127: descriptors.add((InputMethodDescriptor) c.newInstance()); 128: } 129: line = in.readLine().trim(); 130: } 131: catch (IOException ex) 132: { 133: continue outer; 134: } 135: catch (Exception ignored) 136: { 137: } 138: } 139: } 140: } 141: 142: /** The current input method; null if no input methods are installed. */ 143: private InputMethod im; 144: 145: /** Map of locales to the most recently selected input method. */ 146: private final HashMap recent = new HashMap(); 147: 148: /** The list of acceptable character subsets. */ 149: private Character.Subset[] subsets; 150: 151: /** 152: * Construct an InputContext. This is protected, so clients must use 153: * {@link #getInstance()} instead. 154: */ 155: protected InputContext() 156: { 157: } 158: 159: /** 160: * Returns a new InputContext. 161: * 162: * @return a new instance, initialized to the default locale if available 163: */ 164: public static InputContext getInstance() 165: { 166: InputContext ic = new InputContext(); 167: ic.selectInputMethod(Locale.getDefault()); 168: return ic; 169: } 170: 171: /** 172: * Attempts to select an input method or keyboard layout which supports the 173: * given locale. This returns true if a locale is available and was selected. 174: * The following steps are taken in choosing an input method:<ul> 175: * <li>If the currently selected input method or keyboard layout supports 176: * the requested locale, it remains selected.</li> 177: * <li>If there is no input method or keyboard layout available that 178: * supports the requested locale, the current input method or keyboard 179: * layout remains selected.</li> 180: * <li>If the user has previously selected an input method or keyboard 181: * layout for the requested locale from the user interface, then the most 182: * recently selected such input method or keyboard layout is reselected.</li> 183: * <li>Otherwise, an input method or keyboard layout that supports the 184: * requested locale is selected in an implementation dependent way. This 185: * implementation chooses the first input method which supports the requested 186: * locale based on the InputMethodDescriptors loaded from the extensions 187: * installed on the CLASSPATH.</li> 188: * </ul> 189: * 190: * <p>Before switching away from an input method, any currently uncommitted 191: * text is committed. Not all host operating systems provide API to 192: * determine the locale of the currently selected native input method or 193: * keyboard layout, and to select a native input method or keyboard layout 194: * by locale. For host operating systems that don't provide such API, 195: * selectInputMethod assumes that native input methods or keyboard layouts 196: * provided by the host operating system support only the system's default 197: * locale. 198: * 199: * <p>An example of where this may be called is in a multi-language document, 200: * when moving the insertion point between sections of different locale, so 201: * that the user may use the input method appropriate to that section of the 202: * document. 203: * 204: * @param locale the desired new locale 205: * @return true if the new locale is active 206: * @throws NullPointerException if locale is null 207: */ 208: public boolean selectInputMethod(Locale locale) 209: { 210: if (im != null && im.setLocale(locale)) 211: { 212: recent.put(locale, im); 213: return true; 214: } 215: InputMethod next = (InputMethod) recent.get(locale); 216: outer: 217: if (next != null) 218: for (int i = 0, limit = descriptors.size(); i < limit; i++) 219: { 220: InputMethodDescriptor d = (InputMethodDescriptor) descriptors.get(i); 221: Locale[] list; 222: try 223: { 224: list = d.getAvailableLocales(); 225: } 226: catch (AWTException ignored) 227: { 228: continue; 229: } 230: for (int j = list.length; --j >= 0; ) 231: if (locale.equals(list[j])) 232: { 233: try 234: { 235: next = d.createInputMethod(); 236: recent.put(locale, next); 237: } 238: catch (Exception ignored) 239: { 240: continue; 241: } 242: } 243: } 244: if (next == null) 245: return false; 246: // XXX I'm not sure if this does all the necessary steps in the switch. 247: if (im != null) 248: { 249: try 250: { 251: next.setCompositionEnabled(im.isCompositionEnabled()); 252: } 253: catch (UnsupportedOperationException ignored) 254: { 255: } 256: im.endComposition(); 257: im.deactivate(false); 258: im.hideWindows(); 259: } 260: im = next; 261: im.setLocale(locale); 262: im.setCharacterSubsets(subsets); 263: return true; 264: } 265: 266: /** 267: * Returns the current locale of the current input method or keyboard 268: * layout. Returns null if the input context does not have a current input 269: * method or keyboard layout or if the current input method's 270: * {@link InputMethod#getLocale()} method returns null. Not all host 271: * operating systems provide API to determine the locale of the currently 272: * selected native input method or keyboard layout. For host operating 273: * systems that don't provide such API, getLocale assumes that the current 274: * locale of all native input methods or keyboard layouts provided by the 275: * host operating system is the system's default locale. 276: * 277: * @return the locale of the current input method, or null 278: * @since 1.3 279: */ 280: public Locale getLocale() 281: { 282: return im == null ? null : im.getLocale(); 283: } 284: 285: /** 286: * Sets the subsets of Unicode characters allowed to be input by the current 287: * input method, as well as subsequent input methods. The value of null 288: * implies all characters are legal. Applications should not rely on this 289: * behavior, since native host input methods may not allow restrictions. 290: * If no current input method is available, this has no immediate effect. 291: * 292: * @param subsets the set of Unicode subsets to accept, or null 293: */ 294: public void setCharacterSubsets(Character.Subset[] subsets) 295: { 296: this.subsets = subsets; 297: if (im != null) 298: im.setCharacterSubsets(subsets); 299: } 300: 301: /** 302: * Changes the enabled status of the current input method. An input method 303: * that is enabled for composition interprets incoming events for both 304: * composition and control purposes, while a disabled input method only 305: * interprets control commands (including commands to enable itself). 306: * 307: * @param enable whether to enable the input method 308: * @throws UnsupportedOperationException if there is no current input method, 309: * or the input method does not support enabling 310: * @see #isCompositionEnabled() 311: * @since 1.3 312: */ 313: public void setCompositionEnabled(boolean enable) 314: { 315: if (im == null) 316: throw new UnsupportedOperationException(); 317: im.setCompositionEnabled(enable); 318: } 319: 320: /** 321: * Find out if the current input method is enabled. 322: * 323: * @return true if the current input method is enabled 324: * @throws UnsupportedOperationException if there is no current input method, 325: * or the input method does not support enabling 326: * @see #setCompositionEnabled(boolean) 327: * @since 1.3 328: */ 329: public boolean isCompositionEnabled() 330: { 331: if (im == null) 332: throw new UnsupportedOperationException(); 333: return im.isCompositionEnabled(); 334: } 335: 336: /** 337: * Starts a reconversion operation in the current input method. The input 338: * method gets the text to reconvert from the client component, using 339: * {@link InputMethodRequests#getSelectedText(Attribute[])}. Then the 340: * composed and committed text produced by the operation is sent back to 341: * the client using a sequence of InputMethodRequests. 342: * 343: * @throws UnsupportedOperationException if there is no current input method, 344: * or the input method does not support reconversion 345: * @since 1.3 346: */ 347: public void reconvert() 348: { 349: if (im == null) 350: throw new UnsupportedOperationException(); 351: im.reconvert(); 352: } 353: 354: /** 355: * Dispatches an event to the current input method. This is called 356: * automatically by AWT. If no input method is available, then the event 357: * will never be consumed. 358: * 359: * @param event the event to dispatch 360: * @throws NullPointerException if event is null 361: */ 362: public void dispatchEvent(AWTEvent event) 363: { 364: if (im != null) 365: im.dispatchEvent(event); 366: } 367: 368: /** 369: * Notifies the input context that a client component has been removed from 370: * its containment hierarchy, or that input method support has been disabled 371: * for the component. This method is usually called from the client 372: * component's {@link Component#removeNotify()} method. Potentially pending 373: * input from input methods for this component is discarded. If no input 374: * methods are available, then this method has no effect. 375: * 376: * @param client the client component 377: * @throws NullPointerException if client is null 378: */ 379: public void removeNotify(Component client) 380: { 381: // XXX What to do with client information? 382: if (im != null) 383: { 384: im.deactivate(false); 385: im.removeNotify(); 386: } 387: } 388: 389: /** 390: * Ends any input composition that may currently be going on in this 391: * context. Depending on the platform and possibly user preferences, this 392: * may commit or delete uncommitted text. Any changes to the text are 393: * communicated to the active component using an input method event. If no 394: * input methods are available, then this method has no effect. This may 395: * be called for a variety of reasons, such as when the user moves the 396: * insertion point in the client text outside the range of the composed text, 397: * or when text is saved to file. 398: */ 399: public void endComposition() 400: { 401: if (im != null) 402: im.endComposition(); 403: } 404: 405: /** 406: * Disposes of the input context and release the resources used by it. 407: * Called automatically by AWT for the default input context of each 408: * Window. If no input methods are available, then this method has no 409: * effect. 410: */ 411: public void dispose() 412: { 413: if (im != null) 414: { 415: im.deactivate(false); 416: im.dispose(); 417: } 418: } 419: 420: /** 421: * Returns a control object from the current input method, or null. A 422: * control object provides implementation-dependent methods that control 423: * the behavior of the input method or obtain information from the input 424: * method. Clients have to compare the result against known input method 425: * control object types. If no input methods are available or the current 426: * input method does not provide an input method control object, then null 427: * is returned. 428: * 429: * @return the control object, or null 430: */ 431: public Object getInputMethodControlObject() 432: { 433: return im == null ? null : im.getControlObject(); 434: } 435: } // class InputContext
GNU Classpath (0.20) |