001/* InputMethod.java -- defines an interface for complex text input 002 Copyright (C) 2002, 2005 Free Software Foundation, Inc. 003 004This file is part of GNU Classpath. 005 006GNU Classpath is free software; you can redistribute it and/or modify 007it under the terms of the GNU General Public License as published by 008the Free Software Foundation; either version 2, or (at your option) 009any later version. 010 011GNU Classpath is distributed in the hope that it will be useful, but 012WITHOUT ANY WARRANTY; without even the implied warranty of 013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014General Public License for more details. 015 016You should have received a copy of the GNU General Public License 017along with GNU Classpath; see the file COPYING. If not, write to the 018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 01902110-1301 USA. 020 021Linking this library statically or dynamically with other modules is 022making a combined work based on this library. Thus, the terms and 023conditions of the GNU General Public License cover the whole 024combination. 025 026As a special exception, the copyright holders of this library give you 027permission to link this library with independent modules to produce an 028executable, regardless of the license terms of these independent 029modules, and to copy and distribute the resulting executable under 030terms of your choice, provided that you also meet, for each linked 031independent module, the terms and conditions of the license of that 032module. An independent module is a module which is not derived from 033or based on this library. If you modify this library, you may extend 034this exception to your version of the library, but you are not 035obligated to do so. If you do not wish to do so, delete this 036exception statement from your version. */ 037 038package java.awt.im.spi; 039 040import java.awt.AWTEvent; 041import java.awt.Component; 042import java.awt.Rectangle; 043import java.awt.im.InputContext; 044import java.awt.im.InputMethodRequests; 045import java.text.AttributedCharacterIterator.Attribute; 046import java.util.Locale; 047 048/** 049 * This interface supports complex text input, often for situations where 050 * the text is more complex than a keyboard will accomodate. For example, 051 * this can be used for Chinese, Japanese, and Korean, where multiple 052 * keystrokes are necessary to compose text. This could also support things 053 * like phonetic English, or reordering Thai. 054 * 055 * <p>These contexts can be loaded by the input method framework, using 056 * {@link InputContext#selectInputMethod(Locale)}. 057 * 058 * @author Eric Blake (ebb9@email.byu.edu) 059 * @since 1.3 060 * @status updated to 1.4 061 */ 062public interface InputMethod 063{ 064 /** 065 * Set the input method context, which ties the input method to a client 066 * component. This is called once automatically when creating the input 067 * method. 068 * 069 * @param context the context for this input method 070 * @throws NullPointerException if context is null 071 */ 072 void setInputMethodContext(InputMethodContext context); 073 074 /** 075 * Sets the input locale. If the input method supports that locale, it 076 * changes its behavior to be consistent with the locale and returns true. 077 * Otherwise, it returns false. This is called by 078 * {@link InputContext#selectInputMethod(Locale)} when the user specifies 079 * a locale, or when the previously selected input method had a locale. 080 * 081 * @param locale the locale to use for input 082 * @return true if the change is successful 083 * @throws NullPointerException if locale is null 084 */ 085 boolean setLocale(Locale locale); 086 087 /** 088 * Returns the current input locale, or null if none is defined. This is 089 * called by {@link InputContext#getLocale()}, or before switching input 090 * methods. 091 * 092 * @return the current input locale, or null 093 */ 094 Locale getLocale(); 095 096 /** 097 * Sets the allowed Unicode subsets that this input method can use. Null 098 * indicates that all characters are allowed. This is called after creation, 099 * or when switching to this input method, by 100 * {@link InputContext#setCharacterSubsets(Character.Subset[])}. 101 * 102 * @param subsets the accepted subsets for this input method, or null for all 103 */ 104 void setCharacterSubsets(Character.Subset[] subsets); 105 106 /** 107 * Changes the enabled status of this input method. An enabled input method 108 * accepts incoming events for composition and control purposes, while a 109 * disabled input method ignores events (except for control purposes). This 110 * is called by {@link InputContext#setCompositionEnabled(boolean)} or when 111 * switching from an input method if the previous input method returned 112 * without exception on {@link #isCompositionEnabled()}. 113 * 114 * @param enable whether to enable this input method 115 * @throws UnsupportedOperationException if enabling/disabling is unsupported 116 * @see #isCompositionEnabled() 117 */ 118 void setCompositionEnabled(boolean enable); 119 120 /** 121 * Find out if this input method is enabled. This is called by 122 * {@link InputContext#isCompositionEnabled()}, or when switching input 123 * methods via {@link InputContext#selectInputMethod(Locale)}. 124 * 125 * @return true if this input method is enabled 126 * @throws UnsupportedOperationException if enabling/disabling is unsupported 127 * @see #setCompositionEnabled(boolean) 128 */ 129 boolean isCompositionEnabled(); 130 131 /** 132 * Starts a reconversion operation. The input method gets its text from the 133 * client, using {@link InputMethodRequests#getSelectedText(Attribute[])}. 134 * Then the composed and committed text produced by the operation is sent 135 * back to the client using a sequence of InputMethodEvents. This is called 136 * by {@link InputContext#reconvert()}. 137 * 138 * @throws UnsupportedOperationException if reconversion is unsupported 139 */ 140 void reconvert(); 141 142 /** 143 * Dispatch an event to the input method. If input method support is enabled, 144 * certain events are dispatched to the input method before the client 145 * component or event listeners. The input method must either consume the 146 * event or pass it on to the component. Instances of InputEvent, including 147 * KeyEvent and MouseEvent, are given to this input method. This method is 148 * called by {@link InputContext#dispatchEvent(AWTEvent)}. 149 * 150 * @param event the event to dispatch 151 * @throws NullPointerException if event is null 152 */ 153 void dispatchEvent(AWTEvent event); 154 155 /** 156 * Notify this input method of changes in the client window. This is called 157 * when notifications are enabled (see {@link 158 * InputMethodContext#enableClientWindowNotification(InputMethod, boolean)}, 159 * if {@link InputContext#removeNotify(Component)} has not been called. 160 * The following situations trigger a notification:<ul> 161 * <li>The client window changes in location, size, visibility, 162 * iconification, or is closed.</li> 163 * <li>When enabling client notification (or on the first activation after 164 * enabling if no client existed at the time).</li> 165 * <li>When activating a new client after <code>removeNotify</code> was 166 * called on a previous client.</li> 167 * </ul> 168 * 169 * @param bounds the client window's current bounds, or null 170 */ 171 void notifyClientWindowChange(Rectangle bounds); 172 173 /** 174 * Activate this input method for input processing. If the input method 175 * provides its own windows, it should make them open and visible at this 176 * time. This method is called when a client component receives a 177 * FOCUS_GAINED event, or when switching to this input method from another 178 * one. It is only called when the input method is inactive, assuming that 179 * new instances begin in an inactive state. 180 */ 181 void activate(); 182 183 /** 184 * Deactivate this input method, either temporarily or permanently for the 185 * given client. If the input method provides its own windows, it should 186 * only close those related to the current composition (such as a lookup 187 * choice panel), while leaving more persistant windows (like a control 188 * panel) open to avoid screen flicker. Before control is given to another 189 * input method, {@link #hideWindows()} will be called on this instance. 190 * This method is called when a client component receives a 191 * FOCUS_LOST event, when switching to another input method, or before 192 * {@link #removeNotify()} when the client is removed. 193 * 194 * @param isTemporary true if the focus change is temporary 195 */ 196 void deactivate(boolean isTemporary); 197 198 /** 199 * Close or hide all windows opened by this input method. This is called 200 * before activating a different input method, and before calling 201 * {@link #dispose()} on this instance. It is only called when the input 202 * method is inactive. 203 */ 204 void hideWindows(); 205 206 /** 207 * Notify the input method that a client component has been removed from its 208 * hierarchy, or that input method support has been disabled. This is 209 * called by {@link InputContext#removeNotify(Component)}, and only when the input 210 * method is inactive. 211 */ 212 void removeNotify(); 213 214 /** 215 * End any input composition currently taking place. Depending on the 216 * platform and user preferences, this may commit or delete uncommitted text, 217 * using input method events. This may be called for a variety of reasons, 218 * such as when the user moves the insertion point in the client text outside 219 * the range of the composed text, or when text is saved to file. This is 220 * called by {@link InputContext#endComposition()}, when switching to a 221 * new input method, or by {@link InputContext#selectInputMethod(Locale)}. 222 */ 223 void endComposition(); 224 225 /** 226 * Disposes the input method and release any resources it is using. In 227 * particular, the input method should dispose windows and close files. This 228 * is called by {@link InputContext#dispose()}, when the input method is 229 * inactive; and nothing will be called on this instance afterwards. 230 */ 231 void dispose(); 232 233 /** 234 * Returns a control object from this input method, or null. A control object 235 * provides method to control the behavior of this input method, as well as 236 * query information about it. The object is implementation dependent, so 237 * clients must compare the result against known input method control 238 * object types. This is called by 239 * {@link InputContext#getInputMethodControlObject()}. 240 * 241 * @return the control object, or null 242 */ 243 Object getControlObject(); 244} // interface InputMethod