42 * can then be selected either through the API 43 * ({@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod}) 44 * or the user interface (the input method selection menu). 45 * 46 * @since 1.3 47 * 48 * @author JavaSoft International 49 */ 50 51 public interface InputMethod { 52 53 /** 54 * Sets the input method context, which is used to dispatch input method 55 * events to the client component and to request information from 56 * the client component. 57 * <p> 58 * This method is called once immediately after instantiating this input 59 * method. 60 * 61 * @param context the input method context for this input method 62 * @exception NullPointerException if <code>context</code> is null 63 */ 64 public void setInputMethodContext(InputMethodContext context); 65 66 /** 67 * Attempts to set the input locale. If the input method supports the 68 * desired locale, it changes its behavior to support input for the locale 69 * and returns true. 70 * Otherwise, it returns false and does not change its behavior. 71 * <p> 72 * This method is called 73 * <ul> 74 * <li>by {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod}, 75 * <li>when switching to this input method through the user interface if the user 76 * specified a locale or if the previously selected input method's 77 * {@link java.awt.im.spi.InputMethod#getLocale getLocale} method 78 * returns a non-null value. 79 * </ul> 80 * 81 * @param locale locale to input 82 * @return whether the specified locale is supported 83 * @exception NullPointerException if <code>locale</code> is null 84 */ 85 public boolean setLocale(Locale locale); 86 87 /** 88 * Returns the current input locale. Might return null in exceptional cases. 89 * <p> 90 * This method is called 91 * <ul> 92 * <li>by {@link java.awt.im.InputContext#getLocale InputContext.getLocale} and 93 * <li>when switching from this input method to a different one through the 94 * user interface. 95 * </ul> 96 * 97 * @return the current input locale, or null 98 */ 99 public Locale getLocale(); 100 101 /** 102 * Sets the subsets of the Unicode character set that this input method 103 * is allowed to input. Null may be passed in to indicate that all 104 * characters are allowed. 105 * <p> 106 * This method is called 107 * <ul> 108 * <li>immediately after instantiating this input method, 109 * <li>when switching to this input method from a different one, and 110 * <li>by {@link java.awt.im.InputContext#setCharacterSubsets InputContext.setCharacterSubsets}. 111 * </ul> 112 * 113 * @param subsets the subsets of the Unicode character set from which 114 * characters may be input 115 */ 116 public void setCharacterSubsets(Subset[] subsets); 117 118 /** 119 * Enables or disables this input method for composition, 120 * depending on the value of the parameter <code>enable</code>. 121 * <p> 122 * An input method that is enabled for composition interprets incoming 123 * events for both composition and control purposes, while a 124 * disabled input method does not interpret events for composition. 125 * Note however that events are passed on to the input method regardless 126 * whether it is enabled or not, and that an input method that is disabled 127 * for composition may still interpret events for control purposes, 128 * including to enable or disable itself for composition. 129 * <p> 130 * For input methods provided by host operating systems, it is not always possible to 131 * determine whether this operation is supported. For example, an input method may enable 132 * composition only for some locales, and do nothing for other locales. For such input 133 * methods, it is possible that this method does not throw 134 * {@link java.lang.UnsupportedOperationException UnsupportedOperationException}, 135 * but also does not affect whether composition is enabled. 136 * <p> 137 * This method is called 138 * <ul> 139 * <li>by {@link java.awt.im.InputContext#setCompositionEnabled InputContext.setCompositionEnabled}, 140 * <li>when switching to this input method from a different one using the 149 * @throws UnsupportedOperationException if this input method does not 150 * support the enabling/disabling operation 151 * @see #isCompositionEnabled 152 */ 153 public void setCompositionEnabled(boolean enable); 154 155 /** 156 * Determines whether this input method is enabled. 157 * An input method that is enabled for composition interprets incoming 158 * events for both composition and control purposes, while a 159 * disabled input method does not interpret events for composition. 160 * <p> 161 * This method is called 162 * <ul> 163 * <li>by {@link java.awt.im.InputContext#isCompositionEnabled InputContext.isCompositionEnabled} and 164 * <li>when switching from this input method to a different one using the 165 * user interface or 166 * {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod}. 167 * </ul> 168 * 169 * @return <code>true</code> if this input method is enabled for 170 * composition; <code>false</code> otherwise. 171 * @throws UnsupportedOperationException if this input method does not 172 * support checking whether it is enabled for composition 173 * @see #setCompositionEnabled 174 */ 175 public boolean isCompositionEnabled(); 176 177 /** 178 * Starts the reconversion operation. The input method obtains the 179 * text to be reconverted from the current client component using the 180 * {@link java.awt.im.InputMethodRequests#getSelectedText InputMethodRequests.getSelectedText} 181 * method. It can use other <code>InputMethodRequests</code> 182 * methods to request additional information required for the 183 * reconversion operation. The composed and committed text 184 * produced by the operation is sent to the client component as a 185 * sequence of <code>InputMethodEvent</code>s. If the given text 186 * cannot be reconverted, the same text should be sent to the 187 * client component as committed text. 188 * <p> 189 * This method is called by 190 * {@link java.awt.im.InputContext#reconvert() InputContext.reconvert}. 191 * 192 * @throws UnsupportedOperationException if the input method does not 193 * support the reconversion operation. 194 */ 195 public void reconvert(); 196 197 /** 198 * Dispatches the event to the input method. If input method support is 199 * enabled for the focused component, incoming events of certain types 200 * are dispatched to the current input method for this component before 201 * they are dispatched to the component's methods or event listeners. 202 * The input method decides whether it needs to handle the event. If it 203 * does, it also calls the event's <code>consume</code> method; this 204 * causes the event to not get dispatched to the component's event 205 * processing methods or event listeners. 206 * <p> 207 * Events are dispatched if they are instances of InputEvent or its 208 * subclasses. 209 * This includes instances of the AWT classes KeyEvent and MouseEvent. 210 * <p> 211 * This method is called by {@link java.awt.im.InputContext#dispatchEvent InputContext.dispatchEvent}. 212 * 213 * @param event the event being dispatched to the input method 214 * @exception NullPointerException if <code>event</code> is null 215 */ 216 public void dispatchEvent(AWTEvent event); 217 218 /** 219 * Notifies this input method of changes in the client window 220 * location or state. This method is called while this input 221 * method is the current input method of its input context and 222 * notifications for it are enabled (see {@link 223 * InputMethodContext#enableClientWindowNotification 224 * InputMethodContext.enableClientWindowNotification}). Calls 225 * to this method are temporarily suspended if the input context's 226 * {@link java.awt.im.InputContext#removeNotify removeNotify} 227 * method is called, and resume when the input method is activated 228 * for a new client component. It is called in the following 229 * situations: 230 * <ul> 231 * <li> 232 * when the window containing the current client component changes 233 * in location, size, visibility, iconification state, or when the 234 * window is closed.</li> 235 * <li> 236 * from <code> enableClientWindowNotification(inputMethod, 237 * true)</code> if the current client component exists,</li> 238 * <li> 239 * when activating the input method for the first time after it 240 * called 241 * <code>enableClientWindowNotification(inputMethod, 242 * true)</code> if during the call no current client component was 243 * available,</li> 244 * <li> 245 * when activating the input method for a new client component 246 * after the input context's removeNotify method has been 247 * called.</li> 248 * </ul> 249 * @param bounds client window's {@link 250 * java.awt.Component#getBounds bounds} on the screen; or null if 251 * the client window is iconified or invisible 252 */ 253 public void notifyClientWindowChange(Rectangle bounds); 254 255 /** 256 * Activates the input method for immediate input processing. 257 * <p> 258 * If an input method provides its own windows, it should make sure 259 * at this point that all necessary windows are open and visible. 260 * <p> 261 * This method is called 262 * <ul> | 42 * can then be selected either through the API 43 * ({@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod}) 44 * or the user interface (the input method selection menu). 45 * 46 * @since 1.3 47 * 48 * @author JavaSoft International 49 */ 50 51 public interface InputMethod { 52 53 /** 54 * Sets the input method context, which is used to dispatch input method 55 * events to the client component and to request information from 56 * the client component. 57 * <p> 58 * This method is called once immediately after instantiating this input 59 * method. 60 * 61 * @param context the input method context for this input method 62 * @exception NullPointerException if {@code context} is null 63 */ 64 public void setInputMethodContext(InputMethodContext context); 65 66 /** 67 * Attempts to set the input locale. If the input method supports the 68 * desired locale, it changes its behavior to support input for the locale 69 * and returns true. 70 * Otherwise, it returns false and does not change its behavior. 71 * <p> 72 * This method is called 73 * <ul> 74 * <li>by {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod}, 75 * <li>when switching to this input method through the user interface if the user 76 * specified a locale or if the previously selected input method's 77 * {@link java.awt.im.spi.InputMethod#getLocale getLocale} method 78 * returns a non-null value. 79 * </ul> 80 * 81 * @param locale locale to input 82 * @return whether the specified locale is supported 83 * @exception NullPointerException if {@code locale} is null 84 */ 85 public boolean setLocale(Locale locale); 86 87 /** 88 * Returns the current input locale. Might return null in exceptional cases. 89 * <p> 90 * This method is called 91 * <ul> 92 * <li>by {@link java.awt.im.InputContext#getLocale InputContext.getLocale} and 93 * <li>when switching from this input method to a different one through the 94 * user interface. 95 * </ul> 96 * 97 * @return the current input locale, or null 98 */ 99 public Locale getLocale(); 100 101 /** 102 * Sets the subsets of the Unicode character set that this input method 103 * is allowed to input. Null may be passed in to indicate that all 104 * characters are allowed. 105 * <p> 106 * This method is called 107 * <ul> 108 * <li>immediately after instantiating this input method, 109 * <li>when switching to this input method from a different one, and 110 * <li>by {@link java.awt.im.InputContext#setCharacterSubsets InputContext.setCharacterSubsets}. 111 * </ul> 112 * 113 * @param subsets the subsets of the Unicode character set from which 114 * characters may be input 115 */ 116 public void setCharacterSubsets(Subset[] subsets); 117 118 /** 119 * Enables or disables this input method for composition, 120 * depending on the value of the parameter {@code enable}. 121 * <p> 122 * An input method that is enabled for composition interprets incoming 123 * events for both composition and control purposes, while a 124 * disabled input method does not interpret events for composition. 125 * Note however that events are passed on to the input method regardless 126 * whether it is enabled or not, and that an input method that is disabled 127 * for composition may still interpret events for control purposes, 128 * including to enable or disable itself for composition. 129 * <p> 130 * For input methods provided by host operating systems, it is not always possible to 131 * determine whether this operation is supported. For example, an input method may enable 132 * composition only for some locales, and do nothing for other locales. For such input 133 * methods, it is possible that this method does not throw 134 * {@link java.lang.UnsupportedOperationException UnsupportedOperationException}, 135 * but also does not affect whether composition is enabled. 136 * <p> 137 * This method is called 138 * <ul> 139 * <li>by {@link java.awt.im.InputContext#setCompositionEnabled InputContext.setCompositionEnabled}, 140 * <li>when switching to this input method from a different one using the 149 * @throws UnsupportedOperationException if this input method does not 150 * support the enabling/disabling operation 151 * @see #isCompositionEnabled 152 */ 153 public void setCompositionEnabled(boolean enable); 154 155 /** 156 * Determines whether this input method is enabled. 157 * An input method that is enabled for composition interprets incoming 158 * events for both composition and control purposes, while a 159 * disabled input method does not interpret events for composition. 160 * <p> 161 * This method is called 162 * <ul> 163 * <li>by {@link java.awt.im.InputContext#isCompositionEnabled InputContext.isCompositionEnabled} and 164 * <li>when switching from this input method to a different one using the 165 * user interface or 166 * {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod}. 167 * </ul> 168 * 169 * @return {@code true} if this input method is enabled for 170 * composition; {@code false} otherwise. 171 * @throws UnsupportedOperationException if this input method does not 172 * support checking whether it is enabled for composition 173 * @see #setCompositionEnabled 174 */ 175 public boolean isCompositionEnabled(); 176 177 /** 178 * Starts the reconversion operation. The input method obtains the 179 * text to be reconverted from the current client component using the 180 * {@link java.awt.im.InputMethodRequests#getSelectedText InputMethodRequests.getSelectedText} 181 * method. It can use other {@code InputMethodRequests} 182 * methods to request additional information required for the 183 * reconversion operation. The composed and committed text 184 * produced by the operation is sent to the client component as a 185 * sequence of {@code InputMethodEvent}s. If the given text 186 * cannot be reconverted, the same text should be sent to the 187 * client component as committed text. 188 * <p> 189 * This method is called by 190 * {@link java.awt.im.InputContext#reconvert() InputContext.reconvert}. 191 * 192 * @throws UnsupportedOperationException if the input method does not 193 * support the reconversion operation. 194 */ 195 public void reconvert(); 196 197 /** 198 * Dispatches the event to the input method. If input method support is 199 * enabled for the focused component, incoming events of certain types 200 * are dispatched to the current input method for this component before 201 * they are dispatched to the component's methods or event listeners. 202 * The input method decides whether it needs to handle the event. If it 203 * does, it also calls the event's {@code consume} method; this 204 * causes the event to not get dispatched to the component's event 205 * processing methods or event listeners. 206 * <p> 207 * Events are dispatched if they are instances of InputEvent or its 208 * subclasses. 209 * This includes instances of the AWT classes KeyEvent and MouseEvent. 210 * <p> 211 * This method is called by {@link java.awt.im.InputContext#dispatchEvent InputContext.dispatchEvent}. 212 * 213 * @param event the event being dispatched to the input method 214 * @exception NullPointerException if {@code event} is null 215 */ 216 public void dispatchEvent(AWTEvent event); 217 218 /** 219 * Notifies this input method of changes in the client window 220 * location or state. This method is called while this input 221 * method is the current input method of its input context and 222 * notifications for it are enabled (see {@link 223 * InputMethodContext#enableClientWindowNotification 224 * InputMethodContext.enableClientWindowNotification}). Calls 225 * to this method are temporarily suspended if the input context's 226 * {@link java.awt.im.InputContext#removeNotify removeNotify} 227 * method is called, and resume when the input method is activated 228 * for a new client component. It is called in the following 229 * situations: 230 * <ul> 231 * <li> 232 * when the window containing the current client component changes 233 * in location, size, visibility, iconification state, or when the 234 * window is closed.</li> 235 * <li> 236 * from {@code enableClientWindowNotification(inputMethod, true)} 237 * if the current client component exists,</li> 238 * <li> 239 * when activating the input method for the first time after it 240 * called 241 * {@code enableClientWindowNotification(inputMethod, true)} 242 * if during the call no current client component was 243 * available,</li> 244 * <li> 245 * when activating the input method for a new client component 246 * after the input context's removeNotify method has been 247 * called.</li> 248 * </ul> 249 * @param bounds client window's {@link 250 * java.awt.Component#getBounds bounds} on the screen; or null if 251 * the client window is iconified or invisible 252 */ 253 public void notifyClientWindowChange(Rectangle bounds); 254 255 /** 256 * Activates the input method for immediate input processing. 257 * <p> 258 * If an input method provides its own windows, it should make sure 259 * at this point that all necessary windows are open and visible. 260 * <p> 261 * This method is called 262 * <ul> |