JTextComponent.java revision 3909
3293N/A * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved. 3293N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 3293N/A * This code is free software; you can redistribute it and/or modify it 3293N/A * under the terms of the GNU General Public License version 2 only, as 3293N/A * published by the Free Software Foundation. Oracle designates this 3293N/A * particular file as subject to the "Classpath" exception as provided 3293N/A * by Oracle in the LICENSE file that accompanied this code. 3293N/A * This code is distributed in the hope that it will be useful, but WITHOUT 3293N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 3293N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 3293N/A * version 2 for more details (a copy is included in the LICENSE file that 3293N/A * You should have received a copy of the GNU General Public License version 3293N/A * 2 along with this work; if not, write to the Free Software Foundation, 3293N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 3293N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 3293N/A * or visit www.oracle.com if you need additional information or have any 3293N/A * <code>JTextComponent</code> is the base class for swing text 3293N/A * components. It tries to be compatible with the 3293N/A * <code>java.awt.TextComponent</code> class 3293N/A * where it can reasonably do so. Also provided are other services 3293N/A * for additional flexibility (beyond the pluggable UI and bean 3293N/A * You can find information on how to use the functionality 3293N/A * a section in <em>The Java Tutorial.</em> 3293N/A * <dt><b><font size=+1>Caret Changes</font></b> * The caret is a pluggable object in swing text components. * Notification of changes to the caret position and the selection * are sent to implementations of the <code>CaretListener</code> * interface that have been registered with the text component. * The UI will install a default caret unless a customized caret * By default the caret tracks all the document changes * performed on the Event Dispatching Thread and updates it's position * accordingly if an insertion occurs before or at the caret position * or a removal occurs before the caret position. <code>DefaultCaret</code> * tries to make itself visible which may lead to scrolling * of a text component within <code>JScrollPane</code>. The default caret * behavior can be changed by the {@link DefaultCaret#setUpdatePolicy} method. * <b>Note</b>: Non-editable text components also have a caret though * <dt><b><font size=+1>Commands</font></b> * Text components provide a number of commands that can be used * to manipulate the component. This is essentially the way that * the component expresses its capabilities. These are expressed * in terms of the swing <code>Action</code> interface, * using the <code>TextAction</code> implementation. * The set of commands supported by the text component can be * found with the {@link #getActions} method. These actions * can be bound to key events, fired from buttons, etc. * <dt><b><font size=+1>Text Input</font></b> * The text components support flexible and internationalized text input, using * keymaps and the input method framework, while maintaining compatibility with * the AWT listener model. * A {@link javax.swing.text.Keymap} lets an application bind key * In order to allow keymaps to be shared across multiple text components, they * can use actions that extend <code>TextAction</code>. * <code>TextAction</code> can determine which <code>JTextComponent</code> * most recently has or had focus and therefore is the subject of * the action (In the case that the <code>ActionEvent</code> * sent to the action doesn't contain the target text component as its source). * lets text components interact with input methods, separate software * components that preprocess events to let users enter thousands of * different characters using keyboards with far fewer keys. * <code>JTextComponent</code> is an <em>active client</em> of * the framework, so it implements the preferred user interface for interacting * with input methods. As a consequence, some key events do not reach the text * component because they are handled by an input method, and some text input * reaches the text component as committed text within an {@link * java.awt.event.InputMethodEvent} instead of as a key event. * The complete text input is the combination of the characters in * <code>keyTyped</code> key events and committed text in input method events. * The AWT listener model lets applications attach event listeners to * components in order to bind events to actions. Swing encourages the * use of keymaps instead of listeners, but maintains compatibility * with listeners by giving the listeners a chance to steal an event * Keyboard event and input method events are handled in the following stages, * with each stage capable of consuming the event: * <table border=1 summary="Stages of keyboard and input method event handling"> * <th id="stage"><p align="left">Stage</p></th> * <th id="ke"><p align="left">KeyEvent</p></th> * <th id="ime"><p align="left">InputMethodEvent</p></th></tr> * <tr><td headers="stage">1. </td> * <td headers="ke">input methods </td> * <td headers="ime">(generated here)</td></tr> * <tr><td headers="stage">2. </td> * <td headers="ke">focus manager </td> * <td headers="ime"></td> * <td headers="stage">3. </td> * <td headers="ke">registered key listeners</td> * <td headers="ime">registered input method listeners</tr> * <td headers="stage">4. </td> * <td headers="ime">input method handling in JTextComponent</tr> * <td headers="stage">5. </td><td headers="ke ime" colspan=2>keymap handling using the current keymap</td></tr> * <tr><td headers="stage">6. </td><td headers="ke">keyboard handling in JComponent (e.g. accelerators, component navigation, etc.)</td> * <td headers="ime"></td></tr> * To maintain compatibility with applications that listen to key * events but are not aware of input method events, the input * method handling in stage 4 provides a compatibility mode for * components that do not process input method events. For these * components, the committed text is converted to keyTyped key events * and processed in the key event pipeline starting at stage 3 * instead of in the input method event pipeline. * By default the component will create a keymap (named <b>DEFAULT_KEYMAP</b>) * that is shared by all JTextComponent instances as the default keymap. * Typically a look-and-feel implementation will install a different keymap * that resolves to the default keymap for those bindings not found in the * different keymap. The minimal bindings include: * <li>inserting content into the editor for the * <li>removing content with the backspace and del * <li>caret movement forward and backward * <dt><b><font size=+1>Model/View Split</font></b> * The text components have a model-view split. A text component pulls * together the objects used to represent the model, view, and controller. * The text document model may be shared by other views which act as observers * of the model (e.g. a document may be shared by multiple components). * <p align=center><img src="doc-files/editor.gif" alt="Diagram showing interaction between Controller, Document, events, and ViewFactory" * HEIGHT=358 WIDTH=587></p> * The model is defined by the {@link Document} interface. * This is intended to provide a flexible text storage mechanism * that tracks change during edits and can be extended to more sophisticated * models. The model interfaces are meant to capture the capabilities of * expression given by SGML, a system used to express a wide variety of * Each modification to the document causes notification of the * details of the change to be sent to all observers in the form of a * {@link DocumentEvent} which allows the views to stay up to date with the model. * This event is sent to observers that have implemented the * {@link DocumentListener} * interface and registered interest with the model being observed. * <dt><b><font size=+1>Location Information</font></b> * The capability of determining the location of text in * the view is provided. There are two methods, {@link #modelToView} * and {@link #viewToModel} for determining this information. * <dt><b><font size=+1>Undo/Redo support</font></b> * Support for an edit history mechanism is provided to allow * undo/redo operations. The text component does not itself * provide the history buffer by default, but does provide * the <code>UndoableEdit</code> records that can be used in conjunction * with a history buffer to provide the undo/redo support. * The support is provided by the Document model, which allows * one to attach UndoableEditListener implementations. * <dt><b><font size=+1>Thread Safety</font></b> * The swing text components provide some support of thread * safe operations. Because of the high level of configurability * of the text components, it is possible to circumvent the * protection provided. The protection primarily comes from * the model, so the documentation of <code>AbstractDocument</code> * describes the assumptions of the protection provided. * The methods that are safe to call asynchronously are marked * <dt><b><font size=+1>Newlines</font></b> * For a discussion on how newlines are handled, see * <dt><b><font size=+1>Printing support</font></b> * Several {@link #print print} methods are provided for basic * document printing. If more advanced printing is needed, use the * {@link #getPrintable} method. * <strong>Warning:</strong> * Serialized objects of this class will not be compatible with * future Swing releases. The current serialization support is * appropriate for short term storage or RMI between applications running * the same version of Swing. As of 1.4, support for long term storage * of all JavaBeans<sup><font size="-2">TM</font></sup> * has been added to the <code>java.beans</code> package. * attribute: isContainer false * @author Timothy Prinzing * @author Igor Kushnirskiy (printing support) * Creates a new <code>JTextComponent</code>. * Listeners for caret events are established, and the pluggable * UI installed. The component is marked as editable. No layout manager * is used, because layout is managed by the view subsystem of text. * The document model is set to <code>null</code>. // enable InputMethodEvent for on-the-spot pre-editing * Fetches the user-interface factory for this text-oriented editor. * Sets the user-interface factory for this text-oriented editor. * Reloads the pluggable UI. The key used to fetch the * new interface is <code>getUIClassID()</code>. The type of * the UI is <code>TextUI</code>. <code>invalidate</code> * is called after setting the UI. * Adds a caret listener for notification of any changes * @param listener the listener to be added * @see javax.swing.event.CaretEvent * Removes a caret listener. * @param listener the listener to be removed * @see javax.swing.event.CaretEvent * Returns an array of all the caret listeners * registered on this text component. * @return all of this component's <code>CaretListener</code>s * array if no caret listeners are currently registered * @see #removeCaretListener * Notifies all listeners that have registered interest for * notification on this event type. The event instance * is lazily created using the parameters passed into * the fire method. The listener list is processed in a // Guaranteed to return a non-null array // Process the listeners last to first, notifying // those that are interested in this event * Associates the editor with a text document. * The currently registered factory is used to build a view for * the document, which gets displayed by the editor after revalidation. * A PropertyChange event ("document") is propagated to each listener. * description: the text document model * aquire a read lock on the old model to prevent notification of * mutations while we disconnecting the old model. // Set the document's run direction property to match the // component's ComponentOrientation property. * Fetches the model associated with the editor. This is * primarily for the UI to get at the minimal amount of * state required to be a text editor. Subclasses will * return the actual type of the model which will typically * be something that extends Document. // Override of Component.setComponentOrientation // Set the document's run direction property to match the // ComponentOrientation property. * Fetches the command list for the editor. This is * the list of commands supported by the plugged-in UI * augmented by the collection of commands that the * editor itself supports. These are useful for binding * to events, such as in a keymap. * @return the command list * Sets margin space between the text component's border * and its text. The text component's default <code>Border</code> * object will use this value to create the proper margin. * However, if a non-default border is set on the text component, * it is that <code>Border</code> object's responsibility to create the * appropriate margin space (else this property will effectively * be ignored). This causes a redraw of the component. * A PropertyChange event ("margin") is sent to all listeners. * @param m the space between the border and the text * description: desired space between the border and text area * Returns the margin between the text component's border and * Sets the <code>NavigationFilter</code>. <code>NavigationFilter</code> * is used by <code>DefaultCaret</code> and the default cursor movement * actions as a way to restrict the cursor movement. * Returns the <code>NavigationFilter</code>. <code>NavigationFilter</code> * is used by <code>DefaultCaret</code> and the default cursor movement * actions as a way to restrict the cursor movement. A null return value * implies the cursor movement and selection should not be restricted. * @return the NavigationFilter * Fetches the caret that allows text-oriented navigation over * Sets the caret to be used. By default this will be set * by the UI that gets installed. This can be changed to * a custom caret if desired. Setting the caret results in a * PropertyChange event ("caret") being fired. * Fetches the object responsible for making highlights. * @return the highlighter * Sets the highlighter to be used. By default this will be set * by the UI that gets installed. This can be changed to * a custom highlighter if desired. The highlighter can be set to * <code>null</code> to disable it. * A PropertyChange event ("highlighter") is fired * when a new highlighter is installed. * @param h the highlighter * description: object responsible for background highlights * Sets the keymap to use for binding events to * actions. Setting to <code>null</code> effectively disables * A PropertyChange event ("keymap") is fired when a new keymap * description: set of key event to action bindings to use * Turns on or off automatic drag handling. In order to enable automatic * drag handling, this property should be set to {@code true}, and the * component's {@code TransferHandler} needs to be {@code non-null}. * The default value of the {@code dragEnabled} property is {@code false}. * The job of honoring this property, and recognizing a user drag gesture, * lies with the look and feel implementation, and in particular, the component's * {@code TextUI}. When automatic drag handling is enabled, most look and * feels (including those that subclass {@code BasicLookAndFeel}) begin a * drag and drop operation whenever the user presses the mouse button over * a selection and then moves the mouse a few pixels. Setting this property to * {@code true} can therefore have a subtle effect on how selections behave. * If a look and feel is used that ignores this property, you can still * begin a drag and drop operation by calling {@code exportAsDrag} on the * component's {@code TransferHandler}. * @param b whether or not to enable automatic drag handling * @exception HeadlessException if * <code>b</code> is <code>true</code> and * <code>GraphicsEnvironment.isHeadless()</code> * returns <code>true</code> * @see java.awt.GraphicsEnvironment#isHeadless * @see #setTransferHandler * description: determines whether automatic drag handling is enabled * Returns whether or not automatic drag handling is enabled. * @return the value of the {@code dragEnabled} property * Sets the drop mode for this component. For backward compatibility, * the default for this property is <code>DropMode.USE_SELECTION</code>. * Usage of <code>DropMode.INSERT</code> is recommended, however, * for an improved user experience. It offers similar behavior of dropping * between text locations, but does so without affecting the actual text * selection and caret location. * <code>JTextComponents</code> support the following drop modes: * <li><code>DropMode.USE_SELECTION</code></li> * <li><code>DropMode.INSERT</code></li> * The drop mode is only meaningful if this component has a * <code>TransferHandler</code> that accepts drops. * @param dropMode the drop mode to use * @throws IllegalArgumentException if the drop mode is unsupported * @see #setTransferHandler * @see javax.swing.TransferHandler * Returns the drop mode for this component. * @return the drop mode for this component * Calculates a drop location in this component, representing where a * drop at the given point should insert data. * Note: This method is meant to override * <code>JComponent.dropLocationForPoint()</code>, which is package-private * in javax.swing. <code>TransferHandler</code> will detect text components * and call this method instead via reflection. It's name should therefore * @param p the point to calculate a drop location for * @return the drop location, or <code>null</code> // viewToModel currently returns null for some HTML content // when the point is within the component's top inset * Called to set or clear the drop location during a DnD operation. * In some cases, the component may need to use it's internal selection * temporarily to indicate the drop location. To help facilitate this, * this method returns and accepts as a parameter a state object. * This state object can be used to store, and later restore, the selection * state. Whatever this method returns will be passed back to it in * future calls, as the state parameter. If it wants the DnD system to * continue storing the same state, it must pass it back every time. * Here's how this is used: * Let's say that on the first call to this method the component decides * to save some state (because it is about to use the selection to show * a drop index). It can return a state object to the caller encapsulating * any saved selection state. On a second call, let's say the drop location * is being changed to something else. The component doesn't need to * restore anything yet, so it simply passes back the same state object * to have the DnD system continue storing it. Finally, let's say this * method is messaged with <code>null</code>. This means DnD * is finished with this component for now, meaning it should restore * state. At this point, it can use the state parameter to restore * said state, and of course return <code>null</code> since there's * no longer anything to store. * Note: This method is meant to override * <code>JComponent.setDropLocation()</code>, which is package-private * in javax.swing. <code>TransferHandler</code> will detect text components * and call this method instead via reflection. It's name should therefore * @param location the drop location (as calculated by * <code>dropLocationForPoint</code>) or <code>null</code> * if there's no longer a valid drop location * @param state the state object saved earlier for this component, * @param forDrop whether or not the method is being called because an * @return any saved state for this component, or <code>null</code> if none * This object represents the state saved earlier. * If the caret is a DefaultCaret it will be * an Object array containing, in order: * - the saved caret mark (Integer) * - the saved caret dot (Integer) * - the saved caret visibility (Boolean) * - the saved mark bias (Position.Bias) * - the saved dot bias (Position.Bias) * If the caret is not a DefaultCaret it will * be similar, but will not contain the dot * Returns the location that this component should visually indicate * as the drop location during a DnD operation over the component, * or {@code null} if no location is to currently be shown. * This method is not meant for querying the drop location * from a {@code TransferHandler}, as the drop location is only * set after the {@code TransferHandler}'s <code>canImport</code> * has returned and has allowed for the location to be shown. * When this property changes, a property change event with * name "dropLocation" is fired by the component. * @return the drop location * @see TransferHandler#canImport(TransferHandler.TransferSupport) * Updates the <code>InputMap</code>s in response to a * <code>Keymap</code> change. * @param oldKm the old <code>Keymap</code> * @param newKm the new <code>Keymap</code> // Locate the current KeymapWrapper. // Found it, tweak the InputMap that points to it, as well // as anything it points to. // Set the parent of WHEN_FOCUSED InputMap to be the new one. // Do the same thing with the ActionMap // Found it, tweak the Actionap that points to it, as well // as anything it points to. // Set the parent of ActionMap to be the new one. * Fetches the keymap currently active in this text * Adds a new keymap into the keymap hierarchy. Keymap bindings * resolve from bottom up so an attribute specified in a child * will override an attribute specified in the parent. * @param nm the name of the keymap (must be unique within the * collection of named keymaps in the document); the name may * be <code>null</code> if the keymap is unnamed, * but the caller is responsible for managing the reference * returned as an unnamed keymap can't * @param parent the parent keymap; this may be <code>null</code> if * unspecified bindings need not be resolved in some other keymap // add a named keymap, a class of bindings * Removes a named keymap previously added to the document. Keymaps * with <code>null</code> names may not be removed in this way. * @param nm the name of the keymap to remove * @return the keymap that was removed * Fetches a named keymap previously added to the document. * This does not work with <code>null</code>-named keymaps. * @param nm the name of the keymap //initialize default keymap * Binding record for creating key bindings. * <strong>Warning:</strong> * Serialized objects of this class will not be compatible with * future Swing releases. The current serialization support is * appropriate for short term storage or RMI between applications running * the same version of Swing. As of 1.4, support for long term storage * of all JavaBeans<sup><font size="-2">TM</font></sup> * has been added to the <code>java.beans</code> package. * The name of the action for the key. * Creates a new key binding. * @param actionName the name of the action for the key * Loads a keymap with a bunch of * bindings. This can be used to take a static table of * definitions and load them into some keymap. The following * example illustrates an example of binding some keys to * the cut, copy, and paste actions associated with a * JTextComponent. A code fragment to accomplish * this might look as follows: * static final JTextComponent.KeyBinding[] defaultBindings = { * new JTextComponent.KeyBinding( * KeyStroke.getKeyStroke(KeyEvent.VK_C, InputEvent.CTRL_MASK), * DefaultEditorKit.copyAction), * new JTextComponent.KeyBinding( * KeyStroke.getKeyStroke(KeyEvent.VK_V, InputEvent.CTRL_MASK), * DefaultEditorKit.pasteAction), * new JTextComponent.KeyBinding( * KeyStroke.getKeyStroke(KeyEvent.VK_X, InputEvent.CTRL_MASK), * DefaultEditorKit.cutAction), * JTextComponent c = new JTextPane(); * Keymap k = c.getKeymap(); * JTextComponent.loadKeymap(k, defaultBindings, c.getActions()); * The sets of bindings and actions may be empty but must be * @param bindings the bindings * @param actions the set of actions * Returns true if <code>klass</code> is NOT a JTextComponent and it or * one of its superclasses (stoping at JTextComponent) overrides * <code>processInputMethodEvent</code>. It is assumed this will be * invoked from within a <code>doPrivileged</code>, and it is also * assumed <code>klass</code> extends <code>JTextComponent</code>. // If our superclass has overriden it, then by definition klass // klass's superclass didn't override it, check for an override in * Fetches the current color used to render the * Sets the current color used to render the caret. * Setting to <code>null</code> effectively restores the default color. * Setting the color results in a PropertyChange event ("caretColor") * description: the color used to render the caret * Fetches the current color used to render the * Sets the current color used to render the selection. * Setting the color to <code>null</code> is the same as setting * <code>Color.white</code>. Setting the color results in a * PropertyChange event ("selectionColor"). * @see #getSelectionColor * description: color used to render selection background * Fetches the current color used to render the * Sets the current color used to render the selected text. * Setting the color to <code>null</code> is the same as * <code>Color.black</code>. Setting the color results in a * PropertyChange event ("selectedTextColor") being fired. * @see #getSelectedTextColor * description: color used to render selected text * Fetches the current color used to render the * Sets the current color used to render the * disabled text. Setting the color fires off a * PropertyChange event ("disabledTextColor"). * @see #getDisabledTextColor * description: color used to render disabled text * Replaces the currently selected content with new content * represented by the given string. If there is no selection * this amounts to an insert of the given text. If there * is no replacement text this amounts to a removal of the * This is the method that is used by the default implementation * of the action for inserting content that gets bound to the * @param content the content to replace the selection with * Fetches a portion of the text represented by the * component. Returns an empty string if length is 0. * @param offs the offset >= 0 * @param len the length >= 0 * @exception BadLocationException if the offset or length are invalid * Converts the given location in the model to a place in * the view coordinate system. * The component must have a positive size for * this translation to be computed (i.e. layout cannot * be computed until the component has been sized). The * component does not have to be visible or painted. * @param pos the position >= 0 * @return the coordinates as a rectangle, with (r.x, r.y) as the location * in the coordinate system, or null if the component does * not yet have a positive size. * @exception BadLocationException if the given position does not * represent a valid location in the associated document * @see TextUI#modelToView * Converts the given place in the view coordinate system * to the nearest representative location in the model. * The component must have a positive size for * this translation to be computed (i.e. layout cannot * be computed until the component has been sized). The * component does not have to be visible or painted. * @param pt the location in the view to translate * @return the offset >= 0 from the start of the document, * or -1 if the component does not yet have a positive * @see TextUI#viewToModel * Transfers the currently selected range in the associated * text model to the system clipboard, removing the contents * from the model. The current selection is reset. Does nothing * for <code>null</code> selections. * @see java.awt.Toolkit#getSystemClipboard * @see java.awt.datatransfer.Clipboard * Transfers the currently selected range in the associated * text model to the system clipboard, leaving the contents * in the text model. The current selection remains intact. * Does nothing for <code>null</code> selections. * @see java.awt.Toolkit#getSystemClipboard * @see java.awt.datatransfer.Clipboard * Transfers the contents of the system clipboard into the * associated text model. If there is a selection in the * associated view, it is replaced with the contents of the * clipboard. If there is no selection, the clipboard contents * are inserted in front of the current insert position in * the associated view. If the clipboard is empty, does nothing. * @see java.awt.Toolkit#getSystemClipboard * @see java.awt.datatransfer.Clipboard * This is a conveniance method that is only useful for * <code>cut</code>, <code>copy</code> and <code>paste</code>. If * an <code>Action</code> with the name <code>name</code> does not * exist in the <code>ActionMap</code>, this will attemp to install a * <code>TransferHandler</code> and then use <code>altAction</code>. * If the current <code>TransferHandler</code> is null, this will * Moves the caret to a new position, leaving behind a mark * defined by the last time <code>setCaretPosition</code> was * called. This forms a selection. * If the document is <code>null</code>, does nothing. The position * must be between 0 and the length of the component's text or else * an exception is thrown. * @param pos the position * @exception IllegalArgumentException if the value supplied * for <code>position</code> is less than zero or greater * than the component's text length * The bound property name for the focus accelerator. * Sets the key accelerator that will cause the receiving text * component to get the focus. The accelerator will be the * key combination of the <em>alt</em> key and the character * given (converted to upper case). By default, there is no focus * accelerator key. Any previous key accelerator setting will be * superseded. A '\0' key setting will be registered, and has the * effect of turning off the focus accelerator. When the new key * is set, a PropertyChange event (FOCUS_ACCELERATOR_KEY) will be fired. * @see #getFocusAccelerator * description: accelerator character used to grab focus // Fix for 4341002: value of FOCUS_ACCELERATOR_KEY is wrong. // So we fire both FOCUS_ACCELERATOR_KEY, for compatibility, // and the correct event here. * Returns the key accelerator that will cause the receiving * text component to get the focus. Return '\0' if no focus * accelerator has been set. * Initializes from a stream. This creates a * model of the type appropriate for the component * and initializes the model from the stream. * By default this will load the model as plain * text. Previous contents of the model are discarded. * @param in the stream to read from * @param desc an object describing the stream; this * might be a string, a File, a URL, etc. Some kinds * of documents (such as html for example) might be * able to make use of this information; if non-<code>null</code>, * it is added as a property of the document * @exception IOException as thrown by the stream being * @see EditorKit#createDefaultDocument * Stores the contents of the model into the given * stream. By default this will store the model as plain * @param out the output stream * @exception IOException on any I/O error // --- java.awt.TextComponent methods ------------------------ * Sets the position of the text insertion caret for the * <code>TextComponent</code>. Note that the caret tracks change, * so this may move if the underlying text of the component is changed. * If the document is <code>null</code>, does nothing. The position * must be between 0 and the length of the component's text or else * an exception is thrown. * @param position the position * @exception IllegalArgumentException if the value supplied * for <code>position</code> is less than zero or greater * than the component's text length * description: the caret position * Returns the position of the text insertion caret for the * @return the position of the text insertion caret for the * Sets the text of this <code>TextComponent</code> * to the specified text. If the text is <code>null</code> * or empty, has the effect of simply deleting the old text. * When text has been inserted, the resulting caret location * is determined by the implementation of the caret class. * Note that text is not a bound property, so no <code>PropertyChangeEvent * </code> is fired when it changes. To listen for changes to the text, * use <code>DocumentListener</code>. * @param t the new text to be set * description: the text of this component * Returns the text contained in this <code>TextComponent</code>. * If the underlying document is <code>null</code>, * will give a <code>NullPointerException</code>. * Note that text is not a bound property, so no <code>PropertyChangeEvent * </code> is fired when it changes. To listen for changes to the text, * use <code>DocumentListener</code>. * @exception NullPointerException if the document is <code>null</code> * Returns the selected text contained in this * <code>TextComponent</code>. If the selection is * <code>null</code> or the document empty, returns <code>null</code>. * @exception IllegalArgumentException if the selection doesn't * have a valid mapping into the document for some reason * Returns the boolean indicating whether this * <code>TextComponent</code> is editable or not. * @return the boolean value * Sets the specified boolean to indicate whether or not this * <code>TextComponent</code> should be editable. * A PropertyChange event ("editable") is fired when the * @param b the boolean to be set * description: specifies if the text can be edited * Returns the selected text's start position. Return 0 for an * empty document, or the value of dot if no selection. * @return the start position >= 0 * Sets the selection start to the specified position. The new * starting point is constrained to be before or at the current * This is available for backward compatibility to code * that called this method on <code>java.awt.TextComponent</code>. * This is implemented to forward to the <code>Caret</code> * implementation which is where the actual selection is maintained. * @param selectionStart the start position of the text >= 0 * description: starting location of the selection. /* Route through select method to enforce consistent policy * between selectionStart and selectionEnd. * Returns the selected text's end position. Return 0 if the document * is empty, or the value of dot if there is no selection. * @return the end position >= 0 * Sets the selection end to the specified position. The new * end point is constrained to be at or after the current * This is available for backward compatibility to code * that called this method on <code>java.awt.TextComponent</code>. * This is implemented to forward to the <code>Caret</code> * implementation which is where the actual selection is maintained. * @param selectionEnd the end position of the text >= 0 * description: ending location of the selection. /* Route through select method to enforce consistent policy * between selectionStart and selectionEnd. * Selects the text between the specified start and end positions. * This method sets the start and end positions of the * selected text, enforcing the restriction that the start position * must be greater than or equal to zero. The end position must be * greater than or equal to the start position, and less than or * equal to the length of the text component's text. * If the caller supplies values that are inconsistent or out of * bounds, the method enforces these constraints silently, and * without failure. Specifically, if the start position or end * position is greater than the length of the text, it is reset to * equal the text length. If the start position is less than zero, * it is reset to zero, and if the end position is less than the * start position, it is reset to the start position. * This call is provided for backward compatibility. * It is routed to a call to <code>setCaretPosition</code> * followed by a call to <code>moveCaretPosition</code>. * The preferred way to manage selection is by calling * those methods directly. * @param selectionStart the start position of the text * @param selectionEnd the end position of the text * @see #moveCaretPosition // argument adjustment done by java.awt.TextComponent * Selects all the text in the <code>TextComponent</code>. * Does nothing on a <code>null</code> or empty document. // --- Tooltip Methods --------------------------------------------- * Returns the string to be used as the tooltip for <code>event</code>. * This will return one of: * <li>If <code>setToolTipText</code> has been invoked with a * value, it will be returned, otherwise * <li>The value from invoking <code>getToolTipText</code> on * the UI will be returned. * By default <code>JTextComponent</code> does not register * itself with the <code>ToolTipManager</code>. * This means that tooltips will NOT be shown from the * <code>TextUI</code> unless <code>registerComponent</code> has * been invoked on the <code>ToolTipManager</code>. * @param event the event in question * @return the string to be used as the tooltip for <code>event</code> * @see javax.swing.JComponent#setToolTipText * @see javax.swing.plaf.TextUI#getToolTipText * @see javax.swing.ToolTipManager#registerComponent // --- Scrollable methods --------------------------------------------- * Returns the preferred size of the viewport for a view component. * This is implemented to do the default behavior of returning * the preferred size of the component. * @return the <code>preferredSize</code> of a <code>JViewport</code> * whose view is this <code>Scrollable</code> * Components that display logical rows or columns should compute * the scroll increment that will completely expose one new row * or column, depending on the value of orientation. Ideally, * components should handle a partially exposed row or column by * returning the distance required to completely expose the item. * The default implementation of this is to simply return 10% of * the visible area. Subclasses are likely to be able to provide * a much more reasonable value. * @param visibleRect the view area visible within the viewport * @param orientation either <code>SwingConstants.VERTICAL</code> or * <code>SwingConstants.HORIZONTAL</code> * @param direction less than zero to scroll up/left, greater than * @return the "unit" increment for scrolling in the specified direction * @exception IllegalArgumentException for an invalid orientation * @see JScrollBar#setUnitIncrement * Components that display logical rows or columns should compute * the scroll increment that will completely expose one block * of rows or columns, depending on the value of orientation. * The default implementation of this is to simply return the visible * area. Subclasses will likely be able to provide a much more * @param visibleRect the view area visible within the viewport * @param orientation either <code>SwingConstants.VERTICAL</code> or * <code>SwingConstants.HORIZONTAL</code> * @param direction less than zero to scroll up/left, greater than zero * @return the "block" increment for scrolling in the specified direction * @exception IllegalArgumentException for an invalid orientation * @see JScrollBar#setBlockIncrement * Returns true if a viewport should always force the width of this * <code>Scrollable</code> to match the width of the viewport. * For example a normal text view that supported line wrapping * would return true here, since it would be undesirable for * wrapped lines to disappear beyond the right * edge of the viewport. Note that returning true for a * <code>Scrollable</code> whose ancestor is a <code>JScrollPane</code> * effectively disables horizontal scrolling. * Scrolling containers, like <code>JViewport</code>, * will use this method each time they are validated. * @return true if a viewport should force the <code>Scrollable</code>s * Returns true if a viewport should always force the height of this * <code>Scrollable</code> to match the height of the viewport. * For example a columnar text view that flowed text in left to * right columns could effectively disable vertical scrolling by * Scrolling containers, like <code>JViewport</code>, * will use this method each time they are validated. * @return true if a viewport should force the Scrollables height * A convenience print method that displays a print dialog, and then * prints this {@code JTextComponent} in <i>interactive</i> mode with no * header or footer text. Note: this method * blocks until printing is done. * Note: In <i>headless</i> mode, no dialogs will be shown. * <p> This method calls the full featured * {@link #print(MessageFormat, MessageFormat, boolean, PrintService, PrintRequestAttributeSet, boolean) * print} method to perform printing. * @return {@code true}, unless printing is canceled by the user * @throws PrinterException if an error in the print system causes the job * @throws SecurityException if this thread is not allowed to * initiate a print job request * @see #print(MessageFormat, MessageFormat, boolean, PrintService, PrintRequestAttributeSet, boolean) * A convenience print method that displays a print dialog, and then * prints this {@code JTextComponent} in <i>interactive</i> mode with * the specified header and footer text. Note: this method * blocks until printing is done. * Note: In <i>headless</i> mode, no dialogs will be shown. * <p> This method calls the full featured * {@link #print(MessageFormat, MessageFormat, boolean, PrintService, PrintRequestAttributeSet, boolean) * print} method to perform printing. * @param headerFormat the text, in {@code MessageFormat}, to be * used as the header, or {@code null} for no header * @param footerFormat the text, in {@code MessageFormat}, to be * used as the footer, or {@code null} for no footer * @return {@code true}, unless printing is canceled by the user * @throws PrinterException if an error in the print system causes the job * @throws SecurityException if this thread is not allowed to * initiate a print job request * @see #print(MessageFormat, MessageFormat, boolean, PrintService, PrintRequestAttributeSet, boolean) * @see java.text.MessageFormat * Prints the content of this {@code JTextComponent}. Note: this method * blocks until printing is done. * Page header and footer text can be added to the output by providing * {@code MessageFormat} arguments. The printing code requests * {@code Strings} from the formats, providing a single item which may be * included in the formatted string: an {@code Integer} representing the * {@code showPrintDialog boolean} parameter allows you to specify whether * a print dialog is displayed to the user. When it is, the user * may use the dialog to change printing attributes or even cancel the * {@code service} allows you to provide the initial * {@code PrintService} for the print dialog, or to specify * {@code PrintService} to print to when the dialog is not shown. * {@code attributes} can be used to provide the * initial values for the print dialog, or to supply any needed * attributes when the dialog is not shown. {@code attributes} can * be used to control how the job will print, for example * <i>duplex</i> or <i>single-sided</i>. * {@code interactive boolean} parameter allows you to specify * whether to perform printing in <i>interactive</i> * mode. If {@code true}, a progress dialog, with an abort option, * is displayed for the duration of printing. This dialog is * <i>modal</i> when {@code print} is invoked on the <i>Event Dispatch * Thread</i> and <i>non-modal</i> otherwise. <b>Warning</b>: * calling this method on the <i>Event Dispatch Thread</i> with {@code * interactive false} blocks <i>all</i> events, including repaints, from * being processed until printing is complete. It is only * recommended when printing from an application with no * Note: In <i>headless</i> mode, {@code showPrintDialog} and * {@code interactive} parameters are ignored and no dialogs are * This method ensures the {@code document} is not mutated during printing. * To indicate it visually, {@code setEnabled(false)} is set for the * This method uses {@link #getPrintable} to render document content. * This method is thread-safe, although most Swing methods are not. Please * How to Use Threads</A> for more information. * <b>Sample Usage</b>. This code snippet shows a cross-platform print * dialog and then prints the {@code JTextComponent} in <i>interactive</i> mode * unless the user cancels the dialog: * textComponent.print(new MessageFormat("My text component header"), * new MessageFormat("Footer. Page - {0}"), true, null, null, true); * Executing this code off the <i>Event Dispatch Thread</i> * performs printing on the <i>background</i>. * The following pattern might be used for <i>background</i> * FutureTask<Boolean> future = * new FutureTask<Boolean>( * new Callable<Boolean>() { * public Boolean call() { * return textComponent.print(.....); * executor.execute(future); * @param headerFormat the text, in {@code MessageFormat}, to be * used as the header, or {@code null} for no header * @param footerFormat the text, in {@code MessageFormat}, to be * used as the footer, or {@code null} for no footer * @param showPrintDialog {@code true} to display a print dialog, * {@code false} otherwise * @param service initial {@code PrintService}, or {@code null} for the * @param attributes the job attributes to be applied to the print job, or * @param interactive whether to print in an interactive mode * @return {@code true}, unless printing is canceled by the user * @throws PrinterException if an error in the print system causes the job * @throws SecurityException if this thread is not allowed to * initiate a print job request * @see java.text.MessageFormat * @see java.awt.GraphicsEnvironment#isHeadless * @see java.util.concurrent.FutureTask * there are three cases for printing: * 1. print non interactively (! interactive || isHeadless) * 2. print interactively off EDT * 3. print interactively on EDT * 1 and 2 prints on the current thread (3 prints on another thread) * 2 and 3 deal with PrintingStatusDialog //the printing is done successfully or otherwise. //dialog is hidden if needed. * Returns a {@code Printable} to use for printing the content of this * {@code JTextComponent}. The returned {@code Printable} prints * the document as it looks on the screen except being reformatted * The returned {@code Printable} can be wrapped inside another * {@code Printable} in order to create complex reports and * The returned {@code Printable} shares the {@code document} with this * {@code JTextComponent}. It is the responsibility of the developer to * ensure that the {@code document} is not mutated while this {@code Printable} * is used. Printing behavior is undefined when the {@code document} is * mutated during printing. * Page header and footer text can be added to the output by providing * {@code MessageFormat} arguments. The printing code requests * {@code Strings} from the formats, providing a single item which may be * included in the formatted string: an {@code Integer} representing the * The returned {@code Printable} when printed, formats the * document content appropriately for the page size. For correct * line wrapping the {@code imageable width} of all pages must be the * same. See {@link java.awt.print.PageFormat#getImageableWidth}. * This method is thread-safe, although most Swing methods are not. Please * How to Use Threads</A> for more information. * The returned {@code Printable} can be printed on any thread. * This implementation returned {@code Printable} performs all painting on * the <i>Event Dispatch Thread</i>, regardless of what thread it is * @param headerFormat the text, in {@code MessageFormat}, to be * used as the header, or {@code null} for no header * @param footerFormat the text, in {@code MessageFormat}, to be * used as the footer, or {@code null} for no footer * @return a {@code Printable} for use in printing content of this * @see java.awt.print.Printable * @see java.awt.print.PageFormat * @see javax.swing.text.Document#render(java.lang.Runnable) * Gets the <code>AccessibleContext</code> associated with this * <code>JTextComponent</code>. For text components, * the <code>AccessibleContext</code> takes the form of an * <code>AccessibleJTextComponent</code>. * A new <code>AccessibleJTextComponent</code> instance * is created if necessary. * @return an <code>AccessibleJTextComponent</code> that serves as the * <code>AccessibleContext</code> of this * <code>JTextComponent</code> * This class implements accessibility support for the * <code>JTextComponent</code> class. It provides an implementation of * the Java Accessibility API appropriate to menu user-interface elements. * <strong>Warning:</strong> * Serialized objects of this class will not be compatible with * future Swing releases. The current serialization support is * appropriate for short term storage or RMI between applications running * the same version of Swing. As of 1.4, support for long term storage * of all JavaBeans<sup><font size="-2">TM</font></sup> * has been added to the <code>java.beans</code> package. * Constructs an AccessibleJTextComponent. Adds a listener to track // Fire a ACCESSIBLE_VISIBLE_DATA_PROPERTY PropertyChangeEvent // when the text component moves (e.g., when scrolling). // Using an anonymous class since making AccessibleJTextComponent // implement ComponentListener would be an API change. * Handles caret updates (fire appropriate property change event, * which are AccessibleContext.ACCESSIBLE_CARET_PROPERTY and * AccessibleContext.ACCESSIBLE_SELECTION_PROPERTY). * This keeps track of the dot position internally. When the caret * moves, the internal position is updated after firing the event. * @param e the CaretEvent // DocumentListener methods * Handles document insert (fire appropriate property change event * which is AccessibleContext.ACCESSIBLE_TEXT_PROPERTY). * This tracks the changed offset via the event. * @param e the DocumentEvent * Handles document remove (fire appropriate property change event, * which is AccessibleContext.ACCESSIBLE_TEXT_PROPERTY). * This tracks the changed offset via the event. * @param e the DocumentEvent * Handles document remove (fire appropriate property change event, * which is AccessibleContext.ACCESSIBLE_TEXT_PROPERTY). * This tracks the changed offset via the event. * @param e the DocumentEvent * Gets the state set of the JTextComponent. * The AccessibleStateSet of an object is composed of a set of * unique AccessibleState's. A change in the AccessibleStateSet * of an object will cause a PropertyChangeEvent to be fired * for the AccessibleContext.ACCESSIBLE_STATE_PROPERTY property. * @return an instance of AccessibleStateSet containing the * current state set of the object * @see AccessibleStateSet * @see #addPropertyChangeListener * Gets the role of this object. * @return an instance of AccessibleRole describing the role of the * object (AccessibleRole.TEXT) * Get the AccessibleText associated with this object. In the * implementation of the Java Accessibility API for this class, * return this object, which is responsible for implementing the * AccessibleText interface on behalf of itself. // --- interface AccessibleText methods ------------------------ * Many of these methods are just convenience methods; they * just call the equivalent on the parent * Given a point in local coordinates, return the zero-based index * of the character under that Point. If the point is invalid, * this method returns -1. * @param p the Point in local coordinates * @return the zero-based index of the character under Point p. * Gets the editor's drawing rectangle. Stolen * from the unfortunately named * BasicTextUI.getVisibleEditorRect() * @return the bounding box for the root view * Determines the bounding box of the character at the given * index into the string. The bounds are returned in local * coordinates. If the index is invalid a null rectangle * The screen coordinates returned are "unscrolled coordinates" * if the JTextComponent is contained in a JScrollPane in which * case the resulting rectangle should be composed with the parent * coordinates. A good algorithm to use is: * AccessibleText at = a.getAccessibleText(); * AccessibleComponent ac = a.getAccessibleComponent(); * Rectangle r = at.getCharacterBounds(); * Point p = ac.getLocation(); * Note: the JTextComponent must have a valid size (e.g. have * been added to a parent container whose ancestor container * is a valid top-level window) for this method to be able * to return a meaningful (non-null) value. * @param i the index into the String >= 0 * @return the screen coordinates of the character's bounding box * Returns the number of characters (valid indices) * @return the number of characters >= 0 * Returns the zero-based offset of the caret. * Note: The character to the right of the caret will have the * same index value as the offset (the caret is between * @return the zero-based offset of the caret. * Returns the AttributeSet for a given character (at a given index). * @param i the zero-based index into the text * @return the AttributeSet of the character * Returns the start offset within the selected text. * If there is no selection, but there is * a caret, the start and end offsets will be the same. * Return 0 if the text is empty, or the caret position * @return the index into the text of the start of the selection >= 0 * Returns the end offset within the selected text. * If there is no selection, but there is * a caret, the start and end offsets will be the same. * Return 0 if the text is empty, or the caret position * @return the index into teh text of the end of the selection >= 0 * Returns the portion of the text that is selected. * @return the text, null if no selection * IndexedSegment extends Segment adding the offset into the * the model the <code>Segment</code> was asked for. * Offset into the model that the position represents. * Returns the String at a given index. Whitespace * between words is treated as a word. * @param part the CHARACTER, WORD, or SENTENCE to retrieve * @param index an index within the text * @return the letter, word, or sentence. * Returns the String after a given index. Whitespace * between words is treated as a word. * @param part the CHARACTER, WORD, or SENTENCE to retrieve * @param index an index within the text * @return the letter, word, or sentence. * Returns the String before a given index. Whitespace * between words is treated a word. * @param part the CHARACTER, WORD, or SENTENCE to retrieve * @param index an index within the text * @return the letter, word, or sentence. * Gets the word, sentence, or character at <code>index</code>. * If <code>direction</code> is non-null this will find the * Returns the paragraph element for the specified index. * Returns a <code>Segment</code> containing the paragraph text * at <code>index</code>, or null if <code>index</code> isn't * Returns the Segment at <code>index</code> representing either * the paragraph or sentence as identified by <code>part</code>, or * will point to the start of the word/sentence in the array, and * the modelOffset will point to the location of the word/sentence // begin AccessibleEditableText methods ----- * Returns the AccessibleEditableText interface for * @return the AccessibleEditableText interface * Sets the text contents to the specified string. * @param s the string to set the text contents * Inserts the specified string at the given index * @param index the index in the text where the string will * @param s the string to insert in the text * Returns the text string between two indices. * @param startIndex the starting index in the text * @param endIndex the ending index in the text * @return the text string between the indices * Deletes the text between two indices * @param startIndex the starting index in the text * @param endIndex the ending index in the text * Cuts the text between two indices into the system clipboard. * @param startIndex the starting index in the text * @param endIndex the ending index in the text * Pastes the text from the system clipboard into the text * starting at the specified index. * @param startIndex the starting index in the text * Replaces the text between two indices with the specified * @param startIndex the starting index in the text * @param endIndex the ending index in the text * @param s the string to replace the text between two indices * Selects the text between two indices. * @param startIndex the starting index in the text * @param endIndex the ending index in the text * Sets attributes for the text between two indices. * @param startIndex the starting index in the text * @param endIndex the ending index in the text * @param as the attribute set // ----- end AccessibleEditableText methods // ----- begin AccessibleExtendedText methods // Probably should replace the helper method getAtIndex() to return // instead an AccessibleTextSequence also for LINE & ATTRIBUTE_RUN // and then make the AccessibleText methods get[At|After|Before]Point // call this new method instead and return only the string portion * Returns the AccessibleTextSequence at a given <code>index</code>. * If <code>direction</code> is non-null this will find the * @param part the <code>CHARACTER</code>, <code>WORD</code>, * <code>SENTENCE</code>, <code>LINE</code> or * <code>ATTRIBUTE_RUN</code> to retrieve * @param index an index within the text * @param direction is either -1, 0, or 1 * @return an <code>AccessibleTextSequence</code> specifying the text * if <code>part</code> and <code>index</code> are valid. Otherwise, * <code>null</code> is returned. * @see javax.accessibility.AccessibleText#CHARACTER * @see javax.accessibility.AccessibleText#WORD * @see javax.accessibility.AccessibleText#SENTENCE * @see javax.accessibility.AccessibleExtendedText#LINE * @see javax.accessibility.AccessibleExtendedText#ATTRIBUTE_RUN return null;
// direction must be 1, 0, or -1 // we are intentionally silent; our contract says we return // null if there is any failure in this method }
// else we leave rangeSequence set to null // we are intentionally silent; our contract says we return // null if there is any failure in this method // already validated 'direction' above... // we are intentionally silent; our contract says we return // null if there is any failure in this method // assumptions: (1) that all characters in a single element // share the same attribute set; (2) that adjacent elements // *may* share the same attribute set // going backwards, so find left edge of this run - // that'll be the end of the previous run // now set ourselves up to find the left edge of the // going forward, so find right edge of this run - // that'll be the start of the next run // now set ourselves up to find the right edge of the // interested in the current run, so nothing special to // only those three values of direction allowed... // set the unset edge; if neither set then we're getting // both edges of the current run around our 'index' // we are intentionally silent; our contract says we return // null if there is any failure in this method * Starting at text position <code>index</code>, and going in * <code>direction</code>, return the edge of run that shares the * same <code>AttributeSet</code> and parent element as those at * Note: we assume the document is already locked... // locate the Element at index // cache the AttributeSet and parentElement atindex // if we are already at edge of the first element in our parent // we already caught this case earlier; this is to satisfy // getTextRange() not needed; defined in AccessibleEditableText * Returns the <code>AccessibleTextSequence</code> at a given * @param part the <code>CHARACTER</code>, <code>WORD</code>, * <code>SENTENCE</code>, <code>LINE</code> or * <code>ATTRIBUTE_RUN</code> to retrieve * @param index an index within the text * @return an <code>AccessibleTextSequence</code> specifying the text if * <code>part</code> and <code>index</code> are valid. Otherwise, * <code>null</code> is returned * @see javax.accessibility.AccessibleText#CHARACTER * @see javax.accessibility.AccessibleText#WORD * @see javax.accessibility.AccessibleText#SENTENCE * @see javax.accessibility.AccessibleExtendedText#LINE * @see javax.accessibility.AccessibleExtendedText#ATTRIBUTE_RUN * Returns the <code>AccessibleTextSequence</code> after a given * @param part the <code>CHARACTER</code>, <code>WORD</code>, * <code>SENTENCE</code>, <code>LINE</code> or * <code>ATTRIBUTE_RUN</code> to retrieve * @param index an index within the text * @return an <code>AccessibleTextSequence</code> specifying the text * if <code>part</code> and <code>index</code> are valid. Otherwise, * <code>null</code> is returned * @see javax.accessibility.AccessibleText#CHARACTER * @see javax.accessibility.AccessibleText#WORD * @see javax.accessibility.AccessibleText#SENTENCE * @see javax.accessibility.AccessibleExtendedText#LINE * @see javax.accessibility.AccessibleExtendedText#ATTRIBUTE_RUN * Returns the <code>AccessibleTextSequence</code> before a given * @param part the <code>CHARACTER</code>, <code>WORD</code>, * <code>SENTENCE</code>, <code>LINE</code> or * <code>ATTRIBUTE_RUN</code> to retrieve * @param index an index within the text * @return an <code>AccessibleTextSequence</code> specifying the text * if <code>part</code> and <code>index</code> are valid. Otherwise, * <code>null</code> is returned * @see javax.accessibility.AccessibleText#CHARACTER * @see javax.accessibility.AccessibleText#WORD * @see javax.accessibility.AccessibleText#SENTENCE * @see javax.accessibility.AccessibleExtendedText#LINE * @see javax.accessibility.AccessibleExtendedText#ATTRIBUTE_RUN * Returns the <code>Rectangle</code> enclosing the text between * @param startIndex the start index in the text * @param endIndex the end index in the text * @return the bounding rectangle of the text if the indices are valid. * Otherwise, <code>null</code> is returned // ----- end AccessibleExtendedText methods // --- interface AccessibleAction methods ------------------------ * Returns the number of accessible actions available in this object * If there are more than one, the first one is considered the * "default" action of the object. * @return the zero-based number of Actions in this object * Returns a description of the specified action of the object. * @param i zero-based index of the actions * @return a String description of the action * @see #getAccessibleActionCount * Performs the specified Action on the object * @param i zero-based index of actions * @return true if the action was performed; otherwise false. * @see #getAccessibleActionCount // ----- end AccessibleAction methods // --- serialization --------------------------------------------- // --- member variables ---------------------------------- * The caret used to display the insert position * and navigate throughout the document. * This should be serializable, default installed * Object responsible for restricting the cursor navigation. * The object responsible for managing highlights. * This should be serializable, default installed * The current key bindings in effect. * This should be serializable, default installed * The drop mode for this component. * Represents a drop location for <code>JTextComponent</code>s. * Returns the index where dropped data should be inserted into the * associated component. This index represents a position between * characters, as would be interpreted by a caret. * Returns the bias for the drop index. * Returns a string representation of this drop location. * This method is intended to be used for debugging purposes, * and the content and format of the returned string may vary * between implementations. * @return a string representation of this drop location * TransferHandler used if one hasn't been supplied by the UI. * Maps from class name to Boolean indicating if * <code>processInputMethodEvent</code> has been overriden. * Returns a string representation of this <code>JTextComponent</code>. * This method is intended to be used only for debugging purposes, and the * content and format of the returned string may vary between * implementations. The returned string may be empty but may not * Overriding <code>paramString</code> to provide information about the * specific new aspects of the JFC components. * @return a string representation of this <code>JTextComponent</code> * A Simple TransferHandler that exports the data as a String, and * imports the data from the String clipboard. This is only used * if the UI hasn't supplied one, which would only happen if someone * hasn't subclassed Basic. // this may throw an IllegalStateException, // but it will be caught and handled in the // action that invoked this method * Returns the JTextComponent that most recently had focus. The returned * value may currently have focus. // member variables used for on-the-spot input method * Set to true after the check for the override of processInputMethodEvent * Fetch the default action to fire if a * key is typed (ie a KEY_TYPED KeyEvent is received) * and there is no binding for it. Typically this * would be some action that inserts text so that * the keymap doesn't require an action for each * Set the default action to fire if a key is typed. // Determine local bindings first. // See if the parent has any. // Remove any bindings defined in the parent that * String representation of the keymap... potentially * KeymapWrapper wraps a Keymap inside an InputMap. For KeymapWrapper * to be useful it must be used with a KeymapActionMap. * KeymapWrapper for the most part, is an InputMap with two parents. * The first parent visited is ALWAYS the Keymap, with the second * parent being the parent inherited from InputMap. If * <code>keymap.getAction</code> returns null, implying the Keymap * does not have a binding for the KeyStroke, * the parent is then visited. If the Keymap has a binding, the * Action is returned, if not and the KeyStroke represents a * KeyTyped event and the Keymap has a defaultAction, * <code>DefaultActionKey</code> is returned. * <p>KeymapActionMap is then able to transate the object passed in * to either message the Keymap, or message its default implementation. // There may be some duplication here... // There may be some duplication here... // Implies this is a KeyTyped event, use the default * Wraps a Keymap inside an ActionMap. This is used with * a KeymapWrapper. If <code>get</code> is passed in * <code>KeymapWrapper.DefaultActionKey</code>, the default action is * returned, otherwise if the key is an Action, it is returned. // There may be some duplication here... // There may be some duplication here... // This is a little iffy, technically an Action is // a valid Key. We're assuming the Action came from * The default keymap that will be shared by all * <code>JTextComponent</code> instances unless they * have had a different keymap set. * Event to use when firing a notification of change to caret * position. This is mutable so that the event can be reused * since caret events can be fairly high in bandwidth. return "dot=" +
dot +
"," +
"mark=" +
mark;
// --- CaretEvent methods ----------------------- // --- ChangeListener methods ------------------- // --- FocusListener methods ----------------------------------- // --- MouseListener methods ----------------------------------- * Requests focus on the associated * text component, and try to set the cursor position. * @param e the mouse event * @see MouseListener#mousePressed * Called when the mouse is released. * @param e the mouse event * @see MouseListener#mouseReleased // Process any input method events that the component itself // recognizes. The default on-the-spot handling for input method // composed(uncommitted) text is done here after all input // method listeners get called for stealing the events. // let listeners handle the events // Overrides this method to become an active input method client. // Overrides this method to watch the listener installed. // Default implementation of the InputMethodRequests interface. // --- InputMethodRequests methods --- * this is the case when this method is invoked * from DocumentListener. At this point * composedTextEnd and composedTextStart are // --- DocumentListener methods --- // Replaces the current input method (composed) text according to // the passed input method event. This method also inserts the // committed text into the document. // old composed text deletion // committed text insertion // Remember latest committed text start index // Need to generate KeyTyped events for the committed text for components // that are not aware they are active input method clients. // map it to an ActionEvent // Remember latest committed text end index // new composed text insertion // Save the latest committed text information // create attributed string with no attributes * Saves composed text around the specified position. * The composed text (if any) around the specified position is saved * in a backing store and removed from the document. * @param pos document position to identify the composed text location * @return {@code true} if the composed text exists and is saved, * {@code false} otherwise * @see #restoreComposedText * Restores composed text previously saved by {@code saveComposedText}. * The saved composed text is inserted back into the document. This method * should be invoked only if {@code saveComposedText} returns {@code true}. // Map committed text to an ActionEvent. If the committed text length is 1, // treat it as a KeyStroke, otherwise or there is no KeyStroke defined, // treat it just as a default action. // Sets the caret position according to the passed input method // event. Also, sets/resets composed text caret appropriately. // Sets composed text caret // Scroll the component if needed so that the composed text // Restores original caret * Returns true if KeyEvents should be synthesized from an InputEvent. // Checks whether the client code overrides processInputMethodEvent. If it is overridden, // need not to generate KeyTyped events for committed text. If it's not, behave as an // passive input method client. // Checks whether a composed text in this text component // Caret implementation for editing the composed text. // Get the background color of the component // Draw caret in XOR mode. //System.err.println("Can't render cursor"); // If some area other than the composed text is clicked by mouse, // issue endComposition() to force commit the composed text. // Post a caret positioning runnable to assure that the positioning // occurs *after* committing the composed text. // Runnable class for invokeLater() to set caret position later.