001 /*
002 * Copyright 1998-2003 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.awt.im.spi;
027
028 import java.awt.HeadlessException;
029 import java.awt.Window;
030 import java.awt.font.TextHitInfo;
031 import java.awt.im.InputMethodRequests;
032 import java.text.AttributedCharacterIterator;
033 import javax.swing.JFrame;
034
035 /**
036 * Provides methods that input methods
037 * can use to communicate with their client components or to request
038 * other services. This interface is implemented by the input method
039 * framework, and input methods call its methods on the instance they
040 * receive through
041 * {@link java.awt.im.spi.InputMethod#setInputMethodContext}.
042 * There should be no other implementors or callers.
043 *
044 * @since 1.3
045 *
046 * @version 1.23, 05/05/07
047 * @author JavaSoft International
048 */
049
050 public interface InputMethodContext extends InputMethodRequests {
051
052 /**
053 * Creates an input method event from the arguments given
054 * and dispatches it to the client component. For arguments,
055 * see {@link java.awt.event.InputMethodEvent#InputMethodEvent}.
056 */
057 public void dispatchInputMethodEvent(int id,
058 AttributedCharacterIterator text,
059 int committedCharacterCount, TextHitInfo caret,
060 TextHitInfo visiblePosition);
061
062 /**
063 * Creates a top-level window for use by the input method.
064 * The intended behavior of this window is:
065 * <ul>
066 * <li>it floats above all document windows and dialogs
067 * <li>it and all components that it contains do not receive the focus
068 * <li>it has lightweight decorations, such as a reduced drag region without title
069 * </ul>
070 * However, the actual behavior with respect to these three items is platform dependent.
071 * <p>
072 * The title may or may not be displayed, depending on the actual type of window created.
073 * <p>
074 * If attachToInputContext is true, the new window will share the input context that
075 * corresponds to this input method context, so that events for components in the window
076 * are automatically dispatched to the input method.
077 * Also, when the window is opened using setVisible(true), the input context will prevent
078 * deactivate and activate calls to the input method that might otherwise be caused.
079 * <p>
080 * Input methods must call {@link java.awt.Window#dispose() Window.dispose} on the
081 * returned input method window when it is no longer needed.
082 * <p>
083 * @param title the title to be displayed in the window's title bar,
084 * if there is such a title bar.
085 * A <code>null</code> value is treated as an empty string, "".
086 * @param attachToInputContext whether this window should share the input context
087 * that corresponds to this input method context
088 * @return a window with special characteristics for use by input methods
089 * @exception HeadlessException if <code>GraphicsEnvironment.isHeadless
090 * </code> returns <code>true</code>
091 */
092 public Window createInputMethodWindow(String title,
093 boolean attachToInputContext);
094
095 /**
096 * Creates a top-level Swing JFrame for use by the input method.
097 * The intended behavior of this window is:
098 * <ul>
099 * <li>it floats above all document windows and dialogs
100 * <li>it and all components that it contains do not receive the focus
101 * <li>it has lightweight decorations, such as a reduced drag region without title
102 * </ul>
103 * However, the actual behavior with respect to these three items is platform dependent.
104 * <p>
105 * The title may or may not be displayed, depending on the actual type of window created.
106 * <p>
107 * If attachToInputContext is true, the new window will share the input context that
108 * corresponds to this input method context, so that events for components in the window
109 * are automatically dispatched to the input method.
110 * Also, when the window is opened using setVisible(true), the input context will prevent
111 * deactivate and activate calls to the input method that might otherwise be caused.
112 * <p>
113 * Input methods must call {@link java.awt.Window#dispose() Window.dispose} on the
114 * returned input method window when it is no longer needed.
115 * <p>
116 * @param title the title to be displayed in the window's title bar,
117 * if there is such a title bar.
118 * A <code>null</code> value is treated as an empty string, "".
119 * @param attachToInputContext whether this window should share the input context
120 * that corresponds to this input method context
121 * @return a JFrame with special characteristics for use by input methods
122 * @exception HeadlessException if <code>GraphicsEnvironment.isHeadless
123 * </code> returns <code>true</code>
124 *
125 * @since 1.4
126 */
127 public JFrame createInputMethodJFrame(String title,
128 boolean attachToInputContext);
129
130 /**
131 * Enables or disables notification of the current client window's
132 * location and state for the specified input method. When
133 * notification is enabled, the input method's {@link
134 * java.awt.im.spi.InputMethod#notifyClientWindowChange
135 * notifyClientWindowChange} method is called as described in that
136 * method's specification. Notification is automatically disabled
137 * when the input method is disposed.
138 *
139 * @param inputMethod the input method for which notifications are
140 * enabled or disabled
141 * @param enable true to enable, false to disable
142 */
143 public void enableClientWindowNotification(InputMethod inputMethod,
144 boolean enable);
145 }
|