1 /*
2 * Copyright (c) 1998, 2003, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.awt.im.spi;
27
28 import java.awt.HeadlessException;
29 import java.awt.Window;
30 import java.awt.font.TextHitInfo;
31 import java.awt.im.InputMethodRequests;
32 import java.text.AttributedCharacterIterator;
33 import javax.swing.JFrame;
34
35 /**
36 * Provides methods that input methods
37 * can use to communicate with their client components or to request
38 * other services. This interface is implemented by the input method
39 * framework, and input methods call its methods on the instance they
40 * receive through
41 * {@link java.awt.im.spi.InputMethod#setInputMethodContext}.
42 * There should be no other implementors or callers.
43 *
44 * @since 1.3
45 *
46 * @author JavaSoft International
47 */
48
49 public interface InputMethodContext extends InputMethodRequests {
50
51 /**
52 * Creates an input method event from the arguments given
53 * and dispatches it to the client component. For arguments,
54 * see {@link java.awt.event.InputMethodEvent#InputMethodEvent}.
55 */
56 public void dispatchInputMethodEvent(int id,
57 AttributedCharacterIterator text, int committedCharacterCount,
58 TextHitInfo caret, TextHitInfo visiblePosition);
59
60 /**
61 * Creates a top-level window for use by the input method.
62 * The intended behavior of this window is:
63 * <ul>
64 * <li>it floats above all document windows and dialogs
65 * <li>it and all components that it contains do not receive the focus
66 * <li>it has lightweight decorations, such as a reduced drag region without title
67 * </ul>
68 * However, the actual behavior with respect to these three items is platform dependent.
69 * <p>
70 * The title may or may not be displayed, depending on the actual type of window created.
71 * <p>
72 * If attachToInputContext is true, the new window will share the input context that
73 * corresponds to this input method context, so that events for components in the window
74 * are automatically dispatched to the input method.
75 * Also, when the window is opened using setVisible(true), the input context will prevent
76 * deactivate and activate calls to the input method that might otherwise be caused.
77 * <p>
78 * Input methods must call {@link java.awt.Window#dispose() Window.dispose} on the
79 * returned input method window when it is no longer needed.
80 * <p>
81 * @param title the title to be displayed in the window's title bar,
82 * if there is such a title bar.
83 * A <code>null</code> value is treated as an empty string, "".
84 * @param attachToInputContext whether this window should share the input context
85 * that corresponds to this input method context
86 * @return a window with special characteristics for use by input methods
87 * @exception HeadlessException if <code>GraphicsEnvironment.isHeadless
88 * </code> returns <code>true</code>
89 */
90 public Window createInputMethodWindow(String title, boolean attachToInputContext);
91
92 /**
93 * Creates a top-level Swing JFrame for use by the input method.
94 * The intended behavior of this window is:
95 * <ul>
96 * <li>it floats above all document windows and dialogs
97 * <li>it and all components that it contains do not receive the focus
98 * <li>it has lightweight decorations, such as a reduced drag region without title
99 * </ul>
100 * However, the actual behavior with respect to these three items is platform dependent.
101 * <p>
102 * The title may or may not be displayed, depending on the actual type of window created.
103 * <p>
104 * If attachToInputContext is true, the new window will share the input context that
105 * corresponds to this input method context, so that events for components in the window
106 * are automatically dispatched to the input method.
107 * Also, when the window is opened using setVisible(true), the input context will prevent
108 * deactivate and activate calls to the input method that might otherwise be caused.
109 * <p>
110 * Input methods must call {@link java.awt.Window#dispose() Window.dispose} on the
111 * returned input method window when it is no longer needed.
112 * <p>
113 * @param title the title to be displayed in the window's title bar,
114 * if there is such a title bar.
115 * A <code>null</code> value is treated as an empty string, "".
116 * @param attachToInputContext whether this window should share the input context
117 * that corresponds to this input method context
118 * @return a JFrame with special characteristics for use by input methods
119 * @exception HeadlessException if <code>GraphicsEnvironment.isHeadless
120 * </code> returns <code>true</code>
121 *
122 * @since 1.4
123 */
124 public JFrame createInputMethodJFrame(String title, boolean attachToInputContext);
125
126 /**
127 * Enables or disables notification of the current client window's
128 * location and state for the specified input method. When
129 * notification is enabled, the input method's {@link
130 * java.awt.im.spi.InputMethod#notifyClientWindowChange
131 * notifyClientWindowChange} method is called as described in that
132 * method's specification. Notification is automatically disabled
133 * when the input method is disposed.
134 *
135 * @param inputMethod the input method for which notifications are
136 * enabled or disabled
137 * @param enable true to enable, false to disable
138 */
139 public void enableClientWindowNotification(InputMethod inputMethod, boolean enable);
140 }