1 /*
2 * Copyright (c) 1997, 2011, 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
71
72
73 import sun.swing.PrintingStatus;
74 import sun.swing.SwingUtilities2;
75 import sun.swing.text.TextComponentPrintable;
76 import sun.swing.SwingAccessor;
77
78 /**
79 * <code>JTextComponent</code> is the base class for swing text
80 * components. It tries to be compatible with the
81 * <code>java.awt.TextComponent</code> class
82 * where it can reasonably do so. Also provided are other services
83 * for additional flexibility (beyond the pluggable UI and bean
84 * support).
85 * You can find information on how to use the functionality
86 * this class provides in
87 * <a href="http://docs.oracle.com/javase/tutorial/uiswing/components/generaltext.html">General Rules for Using Text Components</a>,
88 * a section in <em>The Java Tutorial.</em>
89 *
90 * <dl>
91 * <dt><b><font size=+1>Caret Changes</font></b>
92 * <dd>
93 * The caret is a pluggable object in swing text components.
94 * Notification of changes to the caret position and the selection
95 * are sent to implementations of the <code>CaretListener</code>
96 * interface that have been registered with the text component.
97 * The UI will install a default caret unless a customized caret
98 * has been set. <br>
99 * By default the caret tracks all the document changes
100 * performed on the Event Dispatching Thread and updates it's position
101 * accordingly if an insertion occurs before or at the caret position
102 * or a removal occurs before the caret position. <code>DefaultCaret</code>
103 * tries to make itself visible which may lead to scrolling
104 * of a text component within <code>JScrollPane</code>. The default caret
105 * behavior can be changed by the {@link DefaultCaret#setUpdatePolicy} method.
106 * <br>
107 * <b>Note</b>: Non-editable text components also have a caret though
108 * it may not be painted.
109 *
110 * <dt><b><font size=+1>Commands</font></b>
111 * <dd>
112 * Text components provide a number of commands that can be used
113 * to manipulate the component. This is essentially the way that
114 * the component expresses its capabilities. These are expressed
115 * in terms of the swing <code>Action</code> interface,
116 * using the <code>TextAction</code> implementation.
117 * The set of commands supported by the text component can be
118 * found with the {@link #getActions} method. These actions
119 * can be bound to key events, fired from buttons, etc.
120 *
121 * <dt><b><font size=+1>Text Input</font></b>
122 * <dd>
123 * The text components support flexible and internationalized text input, using
124 * keymaps and the input method framework, while maintaining compatibility with
125 * the AWT listener model.
126 * <p>
127 * A {@link javax.swing.text.Keymap} lets an application bind key
128 * strokes to actions.
129 * In order to allow keymaps to be shared across multiple text components, they
130 * can use actions that extend <code>TextAction</code>.
131 * <code>TextAction</code> can determine which <code>JTextComponent</code>
132 * most recently has or had focus and therefore is the subject of
133 * the action (In the case that the <code>ActionEvent</code>
134 * sent to the action doesn't contain the target text component as its source).
135 * <p>
136 * The <a href="../../../../technotes/guides/imf/spec.html">input method framework</a>
137 * lets text components interact with input methods, separate software
138 * components that preprocess events to let users enter thousands of
139 * different characters using keyboards with far fewer keys.
140 * <code>JTextComponent</code> is an <em>active client</em> of
141 * the framework, so it implements the preferred user interface for interacting
186 * events but are not aware of input method events, the input
187 * method handling in stage 4 provides a compatibility mode for
188 * components that do not process input method events. For these
189 * components, the committed text is converted to keyTyped key events
190 * and processed in the key event pipeline starting at stage 3
191 * instead of in the input method event pipeline.
192 * <p>
193 * By default the component will create a keymap (named <b>DEFAULT_KEYMAP</b>)
194 * that is shared by all JTextComponent instances as the default keymap.
195 * Typically a look-and-feel implementation will install a different keymap
196 * that resolves to the default keymap for those bindings not found in the
197 * different keymap. The minimal bindings include:
198 * <ul>
199 * <li>inserting content into the editor for the
200 * printable keys.
201 * <li>removing content with the backspace and del
202 * keys.
203 * <li>caret movement forward and backward
204 * </ul>
205 *
206 * <dt><b><font size=+1>Model/View Split</font></b>
207 * <dd>
208 * The text components have a model-view split. A text component pulls
209 * together the objects used to represent the model, view, and controller.
210 * The text document model may be shared by other views which act as observers
211 * of the model (e.g. a document may be shared by multiple components).
212 *
213 * <p style="text-align:center"><img src="doc-files/editor.gif" alt="Diagram showing interaction between Controller, Document, events, and ViewFactory"
214 * HEIGHT=358 WIDTH=587></p>
215 *
216 * <p>
217 * The model is defined by the {@link Document} interface.
218 * This is intended to provide a flexible text storage mechanism
219 * that tracks change during edits and can be extended to more sophisticated
220 * models. The model interfaces are meant to capture the capabilities of
221 * expression given by SGML, a system used to express a wide variety of
222 * content.
223 * Each modification to the document causes notification of the
224 * details of the change to be sent to all observers in the form of a
225 * {@link DocumentEvent} which allows the views to stay up to date with the model.
226 * This event is sent to observers that have implemented the
227 * {@link DocumentListener}
228 * interface and registered interest with the model being observed.
229 *
230 * <dt><b><font size=+1>Location Information</font></b>
231 * <dd>
232 * The capability of determining the location of text in
233 * the view is provided. There are two methods, {@link #modelToView}
234 * and {@link #viewToModel} for determining this information.
235 *
236 * <dt><b><font size=+1>Undo/Redo support</font></b>
237 * <dd>
238 * Support for an edit history mechanism is provided to allow
239 * undo/redo operations. The text component does not itself
240 * provide the history buffer by default, but does provide
241 * the <code>UndoableEdit</code> records that can be used in conjunction
242 * with a history buffer to provide the undo/redo support.
243 * The support is provided by the Document model, which allows
244 * one to attach UndoableEditListener implementations.
245 *
246 * <dt><b><font size=+1>Thread Safety</font></b>
247 * <dd>
248 * The swing text components provide some support of thread
249 * safe operations. Because of the high level of configurability
250 * of the text components, it is possible to circumvent the
251 * protection provided. The protection primarily comes from
252 * the model, so the documentation of <code>AbstractDocument</code>
253 * describes the assumptions of the protection provided.
254 * The methods that are safe to call asynchronously are marked
255 * with comments.
256 *
257 * <dt><b><font size=+1>Newlines</font></b>
258 * <dd>
259 * For a discussion on how newlines are handled, see
260 * <a href="DefaultEditorKit.html">DefaultEditorKit</a>.
261 *
262 *
263 * <dt><b><font size=+1>Printing support</font></b>
264 * <dd>
265 * Several {@link #print print} methods are provided for basic
266 * document printing. If more advanced printing is needed, use the
267 * {@link #getPrintable} method.
268 * </dl>
269 *
270 * <p>
271 * <strong>Warning:</strong>
272 * Serialized objects of this class will not be compatible with
273 * future Swing releases. The current serialization support is
274 * appropriate for short term storage or RMI between applications running
275 * the same version of Swing. As of 1.4, support for long term storage
276 * of all JavaBeans™
277 * has been added to the <code>java.beans</code> package.
278 * Please see {@link java.beans.XMLEncoder}.
279 *
280 * @beaninfo
281 * attribute: isContainer false
282 *
283 * @author Timothy Prinzing
|
1 /*
2 * Copyright (c) 1997, 2013, 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
71
72
73 import sun.swing.PrintingStatus;
74 import sun.swing.SwingUtilities2;
75 import sun.swing.text.TextComponentPrintable;
76 import sun.swing.SwingAccessor;
77
78 /**
79 * <code>JTextComponent</code> is the base class for swing text
80 * components. It tries to be compatible with the
81 * <code>java.awt.TextComponent</code> class
82 * where it can reasonably do so. Also provided are other services
83 * for additional flexibility (beyond the pluggable UI and bean
84 * support).
85 * You can find information on how to use the functionality
86 * this class provides in
87 * <a href="http://docs.oracle.com/javase/tutorial/uiswing/components/generaltext.html">General Rules for Using Text Components</a>,
88 * a section in <em>The Java Tutorial.</em>
89 *
90 * <dl>
91 * <dt><b>Caret Changes</b>
92 * <dd>
93 * The caret is a pluggable object in swing text components.
94 * Notification of changes to the caret position and the selection
95 * are sent to implementations of the <code>CaretListener</code>
96 * interface that have been registered with the text component.
97 * The UI will install a default caret unless a customized caret
98 * has been set. <br>
99 * By default the caret tracks all the document changes
100 * performed on the Event Dispatching Thread and updates it's position
101 * accordingly if an insertion occurs before or at the caret position
102 * or a removal occurs before the caret position. <code>DefaultCaret</code>
103 * tries to make itself visible which may lead to scrolling
104 * of a text component within <code>JScrollPane</code>. The default caret
105 * behavior can be changed by the {@link DefaultCaret#setUpdatePolicy} method.
106 * <br>
107 * <b>Note</b>: Non-editable text components also have a caret though
108 * it may not be painted.
109 *
110 * <dt><b>Commands</b>
111 * <dd>
112 * Text components provide a number of commands that can be used
113 * to manipulate the component. This is essentially the way that
114 * the component expresses its capabilities. These are expressed
115 * in terms of the swing <code>Action</code> interface,
116 * using the <code>TextAction</code> implementation.
117 * The set of commands supported by the text component can be
118 * found with the {@link #getActions} method. These actions
119 * can be bound to key events, fired from buttons, etc.
120 *
121 * <dt><b>Text Input</b>
122 * <dd>
123 * The text components support flexible and internationalized text input, using
124 * keymaps and the input method framework, while maintaining compatibility with
125 * the AWT listener model.
126 * <p>
127 * A {@link javax.swing.text.Keymap} lets an application bind key
128 * strokes to actions.
129 * In order to allow keymaps to be shared across multiple text components, they
130 * can use actions that extend <code>TextAction</code>.
131 * <code>TextAction</code> can determine which <code>JTextComponent</code>
132 * most recently has or had focus and therefore is the subject of
133 * the action (In the case that the <code>ActionEvent</code>
134 * sent to the action doesn't contain the target text component as its source).
135 * <p>
136 * The <a href="../../../../technotes/guides/imf/spec.html">input method framework</a>
137 * lets text components interact with input methods, separate software
138 * components that preprocess events to let users enter thousands of
139 * different characters using keyboards with far fewer keys.
140 * <code>JTextComponent</code> is an <em>active client</em> of
141 * the framework, so it implements the preferred user interface for interacting
186 * events but are not aware of input method events, the input
187 * method handling in stage 4 provides a compatibility mode for
188 * components that do not process input method events. For these
189 * components, the committed text is converted to keyTyped key events
190 * and processed in the key event pipeline starting at stage 3
191 * instead of in the input method event pipeline.
192 * <p>
193 * By default the component will create a keymap (named <b>DEFAULT_KEYMAP</b>)
194 * that is shared by all JTextComponent instances as the default keymap.
195 * Typically a look-and-feel implementation will install a different keymap
196 * that resolves to the default keymap for those bindings not found in the
197 * different keymap. The minimal bindings include:
198 * <ul>
199 * <li>inserting content into the editor for the
200 * printable keys.
201 * <li>removing content with the backspace and del
202 * keys.
203 * <li>caret movement forward and backward
204 * </ul>
205 *
206 * <dt><b>Model/View Split</b>
207 * <dd>
208 * The text components have a model-view split. A text component pulls
209 * together the objects used to represent the model, view, and controller.
210 * The text document model may be shared by other views which act as observers
211 * of the model (e.g. a document may be shared by multiple components).
212 *
213 * <p style="text-align:center"><img src="doc-files/editor.gif" alt="Diagram showing interaction between Controller, Document, events, and ViewFactory"
214 * HEIGHT=358 WIDTH=587></p>
215 *
216 * <p>
217 * The model is defined by the {@link Document} interface.
218 * This is intended to provide a flexible text storage mechanism
219 * that tracks change during edits and can be extended to more sophisticated
220 * models. The model interfaces are meant to capture the capabilities of
221 * expression given by SGML, a system used to express a wide variety of
222 * content.
223 * Each modification to the document causes notification of the
224 * details of the change to be sent to all observers in the form of a
225 * {@link DocumentEvent} which allows the views to stay up to date with the model.
226 * This event is sent to observers that have implemented the
227 * {@link DocumentListener}
228 * interface and registered interest with the model being observed.
229 *
230 * <dt><b>Location Information</b>
231 * <dd>
232 * The capability of determining the location of text in
233 * the view is provided. There are two methods, {@link #modelToView}
234 * and {@link #viewToModel} for determining this information.
235 *
236 * <dt><b>Undo/Redo support</b>
237 * <dd>
238 * Support for an edit history mechanism is provided to allow
239 * undo/redo operations. The text component does not itself
240 * provide the history buffer by default, but does provide
241 * the <code>UndoableEdit</code> records that can be used in conjunction
242 * with a history buffer to provide the undo/redo support.
243 * The support is provided by the Document model, which allows
244 * one to attach UndoableEditListener implementations.
245 *
246 * <dt><b>Thread Safety</b>
247 * <dd>
248 * The swing text components provide some support of thread
249 * safe operations. Because of the high level of configurability
250 * of the text components, it is possible to circumvent the
251 * protection provided. The protection primarily comes from
252 * the model, so the documentation of <code>AbstractDocument</code>
253 * describes the assumptions of the protection provided.
254 * The methods that are safe to call asynchronously are marked
255 * with comments.
256 *
257 * <dt><b>Newlines</b>
258 * <dd>
259 * For a discussion on how newlines are handled, see
260 * <a href="DefaultEditorKit.html">DefaultEditorKit</a>.
261 *
262 *
263 * <dt><b>Printing support</b>
264 * <dd>
265 * Several {@link #print print} methods are provided for basic
266 * document printing. If more advanced printing is needed, use the
267 * {@link #getPrintable} method.
268 * </dl>
269 *
270 * <p>
271 * <strong>Warning:</strong>
272 * Serialized objects of this class will not be compatible with
273 * future Swing releases. The current serialization support is
274 * appropriate for short term storage or RMI between applications running
275 * the same version of Swing. As of 1.4, support for long term storage
276 * of all JavaBeans™
277 * has been added to the <code>java.beans</code> package.
278 * Please see {@link java.beans.XMLEncoder}.
279 *
280 * @beaninfo
281 * attribute: isContainer false
282 *
283 * @author Timothy Prinzing
|