1 /*
2 * Copyright (c) 1997, 2015, 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
140 * components that preprocess events to let users enter thousands of
141 * different characters using keyboards with far fewer keys.
142 * <code>JTextComponent</code> is an <em>active client</em> of
143 * the framework, so it implements the preferred user interface for interacting
144 * with input methods. As a consequence, some key events do not reach the text
145 * component because they are handled by an input method, and some text input
146 * reaches the text component as committed text within an {@link
147 * java.awt.event.InputMethodEvent} instead of as a key event.
148 * The complete text input is the combination of the characters in
149 * <code>keyTyped</code> key events and committed text in input method events.
150 * <p>
151 * The AWT listener model lets applications attach event listeners to
152 * components in order to bind events to actions. Swing encourages the
153 * use of keymaps instead of listeners, but maintains compatibility
154 * with listeners by giving the listeners a chance to steal an event
155 * by consuming it.
156 * <p>
157 * Keyboard event and input method events are handled in the following stages,
158 * with each stage capable of consuming the event:
159 *
160 * <table border=1 summary="Stages of keyboard and input method event handling">
161 * <tr>
162 * <th id="stage"><p style="text-align:left">Stage</p></th>
163 * <th id="ke"><p style="text-align:left">KeyEvent</p></th>
164 * <th id="ime"><p style="text-align:left">InputMethodEvent</p></th></tr>
165 * <tr><td headers="stage">1. </td>
166 * <td headers="ke">input methods </td>
167 * <td headers="ime">(generated here)</td></tr>
168 * <tr><td headers="stage">2. </td>
169 * <td headers="ke">focus manager </td>
170 * <td headers="ime"></td>
171 * </tr>
172 * <tr>
173 * <td headers="stage">3. </td>
174 * <td headers="ke">registered key listeners</td>
175 * <td headers="ime">registered input method listeners</tr>
176 * <tr>
177 * <td headers="stage">4. </td>
178 * <td headers="ke"></td>
179 * <td headers="ime">input method handling in JTextComponent</tr>
180 * <tr>
181 * <td headers="stage">5. </td><td headers="ke ime" colspan=2>keymap handling using the current keymap</td></tr>
182 * <tr><td headers="stage">6. </td><td headers="ke">keyboard handling in JComponent (e.g. accelerators, component navigation, etc.)</td>
183 * <td headers="ime"></td></tr>
184 * </table>
185 *
186 * <p>
187 * To maintain compatibility with applications that listen to key
188 * events but are not aware of input method events, the input
189 * method handling in stage 4 provides a compatibility mode for
190 * components that do not process input method events. For these
191 * components, the committed text is converted to keyTyped key events
192 * and processed in the key event pipeline starting at stage 3
193 * instead of in the input method event pipeline.
194 * <p>
195 * By default the component will create a keymap (named <b>DEFAULT_KEYMAP</b>)
196 * that is shared by all JTextComponent instances as the default keymap.
197 * Typically a look-and-feel implementation will install a different keymap
198 * that resolves to the default keymap for those bindings not found in the
199 * different keymap. The minimal bindings include:
200 * <ul>
201 * <li>inserting content into the editor for the
202 * printable keys.
203 * <li>removing content with the backspace and del
|
1 /*
2 * Copyright (c) 1997, 2017, 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
140 * components that preprocess events to let users enter thousands of
141 * different characters using keyboards with far fewer keys.
142 * <code>JTextComponent</code> is an <em>active client</em> of
143 * the framework, so it implements the preferred user interface for interacting
144 * with input methods. As a consequence, some key events do not reach the text
145 * component because they are handled by an input method, and some text input
146 * reaches the text component as committed text within an {@link
147 * java.awt.event.InputMethodEvent} instead of as a key event.
148 * The complete text input is the combination of the characters in
149 * <code>keyTyped</code> key events and committed text in input method events.
150 * <p>
151 * The AWT listener model lets applications attach event listeners to
152 * components in order to bind events to actions. Swing encourages the
153 * use of keymaps instead of listeners, but maintains compatibility
154 * with listeners by giving the listeners a chance to steal an event
155 * by consuming it.
156 * <p>
157 * Keyboard event and input method events are handled in the following stages,
158 * with each stage capable of consuming the event:
159 *
160 * <table class="striped">
161 * <caption>Stages of keyboard and input method event handling</caption>
162 * <thead>
163 * <tr>
164 * <th id="stage">Stage</th>
165 * <th id="ke">KeyEvent</th>
166 * <th id="ime">InputMethodEvent</th></tr>
167 * </thead>
168 * <tbody>
169 * <tr><td headers="stage">1. </td>
170 * <td headers="ke">input methods </td>
171 * <td headers="ime">(generated here)</td></tr>
172 * <tr><td headers="stage">2. </td>
173 * <td headers="ke">focus manager </td>
174 * <td headers="ime"></td>
175 * </tr>
176 * <tr>
177 * <td headers="stage">3. </td>
178 * <td headers="ke">registered key listeners</td>
179 * <td headers="ime">registered input method listeners</tr>
180 * <tr>
181 * <td headers="stage">4. </td>
182 * <td headers="ke"></td>
183 * <td headers="ime">input method handling in JTextComponent</tr>
184 * <tr>
185 * <td headers="stage">5. </td><td headers="ke ime" colspan=2>keymap handling using the current keymap</td></tr>
186 * <tr><td headers="stage">6. </td><td headers="ke">keyboard handling in JComponent (e.g. accelerators, component navigation, etc.)</td>
187 * <td headers="ime"></td></tr>
188 * </tbody>
189 * </table>
190 *
191 * <p>
192 * To maintain compatibility with applications that listen to key
193 * events but are not aware of input method events, the input
194 * method handling in stage 4 provides a compatibility mode for
195 * components that do not process input method events. For these
196 * components, the committed text is converted to keyTyped key events
197 * and processed in the key event pipeline starting at stage 3
198 * instead of in the input method event pipeline.
199 * <p>
200 * By default the component will create a keymap (named <b>DEFAULT_KEYMAP</b>)
201 * that is shared by all JTextComponent instances as the default keymap.
202 * Typically a look-and-feel implementation will install a different keymap
203 * that resolves to the default keymap for those bindings not found in the
204 * different keymap. The minimal bindings include:
205 * <ul>
206 * <li>inserting content into the editor for the
207 * printable keys.
208 * <li>removing content with the backspace and del
|