GNU Classpath (0.17) | ||
Frames | No Frames |
1: /* InputMethod.java -- defines an interface for complex text input 2: Copyright (C) 2002, 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: package java.awt.im.spi; 39: 40: import java.awt.AWTEvent; 41: import java.awt.Rectangle; 42: import java.util.Locale; 43: 44: /** 45: * This interface supports complex text input, often for situations where 46: * the text is more complex than a keyboard will accomodate. For example, 47: * this can be used for Chinese, Japanese, and Korean, where multiple 48: * keystrokes are necessary to compose text. This could also support things 49: * like phonetic English, or reordering Thai. 50: * 51: * <p>These contexts can be loaded by the input method framework, using 52: * {@link InputContext#selectInputMethod(Locale)}. 53: * 54: * @author Eric Blake (ebb9@email.byu.edu) 55: * @since 1.3 56: * @status updated to 1.4 57: */ 58: public interface InputMethod 59: { 60: /** 61: * Set the input method context, which ties the input method to a client 62: * component. This is called once automatically when creating the input 63: * method. 64: * 65: * @param context the context for this input method 66: * @throws NullPointerException if context is null 67: */ 68: void setInputMethodContext(InputMethodContext context); 69: 70: /** 71: * Sets the input locale. If the input method supports that locale, it 72: * changes its behavior to be consistent with the locale and returns true. 73: * Otherwise, it returns false. This is called by 74: * {@link InputContext#selectInputMethod(Locale)} when the user specifies 75: * a locale, or when the previously selected input method had a locale. 76: * 77: * @param locale the locale to use for input 78: * @return true if the change is successful 79: * @throws NullPointerException if locale is null 80: */ 81: boolean setLocale(Locale locale); 82: 83: /** 84: * Returns the current input locale, or null if none is defined. This is 85: * called by {@link InputContext#getLocale()}, or before switching input 86: * methods. 87: * 88: * @return the current input locale, or null 89: */ 90: Locale getLocale(); 91: 92: /** 93: * Sets the allowed Unicode subsets that this input method can use. Null 94: * indicates that all characters are allowed. This is called after creation, 95: * or when switching to this input method, by 96: * {@link InputContext#setCharacterSubsets(Character.Subset[])}. 97: * 98: * @param subsets the accepted subsets for this input method, or null for all 99: */ 100: void setCharacterSubsets(Character.Subset[] subsets); 101: 102: /** 103: * Changes the enabled status of this input method. An enabled input method 104: * accepts incoming events for composition and control purposes, while a 105: * disabled input method ignores events (except for control purposes). This 106: * is called by {@link InputContext#setCompositionEnabled(boolean)} or when 107: * switching from an input method if the previous input method returned 108: * without exception on {@link #isCompositionEnabled()}. 109: * 110: * @param enable whether to enable this input method 111: * @throws UnsupportedOperationException if enabling/disabling is unsupported 112: * @see #isCompositionEnabled() 113: */ 114: void setCompositionEnabled(boolean enable); 115: 116: /** 117: * Find out if this input method is enabled. This is called by 118: * {@link InputContext#isCompositionEnabled()}, or when switching input 119: * methods via {@link InputContext#selectInputMethod(Locale)}. 120: * 121: * @return true if this input method is enabled 122: * @throws UnsupportedOperationException if enabling/disabling is unsupported 123: * @see #setCompositionEnabled(boolean) 124: */ 125: boolean isCompositionEnabled(); 126: 127: /** 128: * Starts a reconversion operation. The input method gets its text from the 129: * client, using {@link InputMethodRequests#getSelectedText(Attribute[])}. 130: * Then the composed and committed text produced by the operation is sent 131: * back to the client using a sequence of InputMethodEvents. This is called 132: * by {@link InputContext#reconvert()}. 133: * 134: * @throws UnsupportedOperationException if reconversion is unsupported 135: */ 136: void reconvert(); 137: 138: /** 139: * Dispatch an event to the input method. If input method support is enabled, 140: * certain events are dispatched to the input method before the client 141: * component or event listeners. The input method must either consume the 142: * event or pass it on to the component. Instances of InputEvent, including 143: * KeyEvent and MouseEvent, are given to this input method. This method is 144: * called by {@link InputContext#dispatchEvent(AWTEvent)}. 145: * 146: * @param event the event to dispatch 147: * @throws NullPointerException if event is null 148: */ 149: void dispatchEvent(AWTEvent event); 150: 151: /** 152: * Notify this input method of changes in the client window. This is called 153: * when notifications are enabled (see {@link 154: * InputMethodContext#enableClientWindowNotification(InputMethod, boolean)}, 155: * if {@link #removeNotify(Component)} has not been called. The following 156: * situations trigger a notification:<ul> 157: * <li>The client window changes in location, size, visibility, 158: * iconification, or is closed.</li> 159: * <li>When enabling client notification (or on the first activation after 160: * enabling if no client existed at the time).</li> 161: * <li>When activating a new client after <code>removeNotify</code> was 162: * called on a previous client.</li> 163: * </ul> 164: * 165: * @param bounds the client window's current bounds, or null 166: */ 167: void notifyClientWindowChange(Rectangle bounds); 168: 169: /** 170: * Activate this input method for input processing. If the input method 171: * provides its own windows, it should make them open and visible at this 172: * time. This method is called when a client component receives a 173: * FOCUS_GAINED event, or when switching to this input method from another 174: * one. It is only called when the input method is inactive, assuming that 175: * new instances begin in an inactive state. 176: */ 177: void activate(); 178: 179: /** 180: * Deactivate this input method, either temporarily or permanently for the 181: * given client. If the input method provides its own windows, it should 182: * only close those related to the current composition (such as a lookup 183: * choice panel), while leaving more persistant windows (like a control 184: * panel) open to avoid screen flicker. Before control is given to another 185: * input method, {@link #hideWindows()} will be called on this instance. 186: * This method is called when a client component receives a 187: * FOCUS_LOST event, when switching to another input method, or before 188: * {@link #removeNotify()} when the client is removed. 189: * 190: * @param isTemporary true if the focus change is temporary 191: */ 192: void deactivate(boolean isTemporary); 193: 194: /** 195: * Close or hide all windows opened by this input method. This is called 196: * before activating a different input method, and before calling 197: * {@link #dispose()} on this instance. It is only called when the input 198: * method is inactive. 199: */ 200: void hideWindows(); 201: 202: /** 203: * Notify the input method that a client component has been removed from its 204: * hierarchy, or that input method support has been disabled. This is 205: * called by {@link InputContext#removeNotify()}, and only when the input 206: * method is inactive. 207: */ 208: void removeNotify(); 209: 210: /** 211: * End any input composition currently taking place. Depending on the 212: * platform and user preferences, this may commit or delete uncommitted text, 213: * using input method events. This may be called for a variety of reasons, 214: * such as when the user moves the insertion point in the client text outside 215: * the range of the composed text, or when text is saved to file. This is 216: * called by {@link InputContext#endComposition()}, when switching to a 217: * new input method, or by {@link InputContext#selectInputMethod(Locale)}. 218: */ 219: void endComposition(); 220: 221: /** 222: * Disposes the input method and release any resources it is using. In 223: * particular, the input method should dispose windows and close files. This 224: * is called by {@link InputContext#dispose()}, when the input method is 225: * inactive; and nothing will be called on this instance afterwards. 226: */ 227: void dispose(); 228: 229: /** 230: * Returns a control object from this input method, or null. A control object 231: * provides method to control the behavior of this input method, as well as 232: * query information about it. The object is implementation dependent, so 233: * clients must compare the result against known input method control 234: * object types. This is called by 235: * {@link InputContext#getInputMethodControlObject()}. 236: * 237: * @return the control object, or null 238: */ 239: Object getControlObject(); 240: } // interface InputMethod
GNU Classpath (0.17) |