Package org.fife.ui.rtextarea

Class RTextArea

  • All Implemented Interfaces:
    ImageObserver, MenuContainer, Printable, Serializable, Accessible, Scrollable
    Direct Known Subclasses:
    RSyntaxTextArea
    public class RTextArea
extends RTextAreaBase
implements Printable
    An extension of JTextArea that adds the following features:
    • Insert/Overwrite modes (can be toggled via the Insert key)
    • A right-click popup menu with standard editing options
    • Macro support
    • "Mark all" functionality.
    • A way to change the background to an image (gif/png/jpg)
    • Highlight the current line (can be toggled)
    • An easy way to print its text (implements Printable)
    • Hard/soft (emulated with spaces) tabs
    • Fixes a bug with setTabSize
    • Other handy new methods
    NOTE: If the background for an RTextArea is set to a color, its opaque property is set to true for performance reasons. If the background is set to an image, then the opaque property is set to false. This slows things down a little, but if it didn't happen then we would see garbage on-screen when the user scrolled through a document using the arrow keys (not the page-up/down keys though). You should never have to set the opaque property yourself; it is always done for you.
    See Also:
    Serialized Form

    • Constructor Detail

      • RTextArea

        public RTextArea()
        Constructor.

      • RTextArea

        public RTextArea​(AbstractDocument doc)
        Constructor.
        Parameters:
        doc - The document for the editor.

      • RTextArea

        public RTextArea​(String text)
        Constructor.
        Parameters:
        text - The initial text to display.

      • RTextArea

        public RTextArea​(int rows,
                 int cols)
        Constructor.
        Parameters:
        rows - The number of rows to display.
        cols - The number of columns to display.
        Throws:
        IllegalArgumentException - If either rows or cols is negative.

      • RTextArea

        public RTextArea​(String text,
                 int rows,
                 int cols)
        Constructor.
        Parameters:
        text - The initial text to display.
        rows - The number of rows to display.
        cols - The number of columns to display.
        Throws:
        IllegalArgumentException - If either rows or cols is negative.

      • RTextArea

        public RTextArea​(AbstractDocument doc,
                 String text,
                 int rows,
                 int cols)
        Constructor.
        Parameters:
        doc - The document for the editor.
        text - The initial text to display.
        rows - The number of rows to display.
        cols - The number of columns to display.
        Throws:
        IllegalArgumentException - If either rows or cols is negative.

      • RTextArea

        public RTextArea​(int textMode)
        Creates a new RTextArea.
        Parameters:
        textMode - Either INSERT_MODE or OVERWRITE_MODE.

    • Method Detail

      • beginAtomicEdit

        public void beginAtomicEdit()
        Begins an "atomic edit." All text editing operations between this call and the next call to endAtomicEdit() will be treated as a single operation by the undo manager.

        Using this method should be done with great care. You should probably wrap the call to endAtomicEdit() in a finally block: 

         textArea.beginAtomicEdit();
 try {
    // Do editing
 } finally {
    textArea.endAtomicEdit();
 }
        See Also:
        endAtomicEdit()

      • beginRecordingMacro

        public static void beginRecordingMacro()
        Begins recording a macro. After this method is called, all input/caret events, etc. are recorded until endMacroRecording is called. If this method is called but the text component is already recording a macro, nothing happens (but the macro keeps recording).
        See Also:
        isRecordingMacro(), endRecordingMacro()

      • configurePopupMenu

        protected void configurePopupMenu​(JPopupMenu popupMenu)
        Configures the popup menu for this text area. This method is called right before it is displayed, so a hosting application can do any custom configuration (configuring actions, adding/removing items, etc.).

        The default implementation does nothing.

        If you set the popup menu via setPopupMenu(JPopupMenu), you will want to override this method, especially if you removed any of the menu items in the default popup menu.

        Parameters:
        popupMenu - The popup menu. This will never be null.
        See Also:
        createPopupMenu(), setPopupMenu(JPopupMenu)

      • createDefaultModel

        protected Document createDefaultModel()
        Creates the default implementation of the model to be used at construction if one isn't explicitly given. A new instance of RDocument is returned.
        Overrides:
        createDefaultModel in class JTextArea
        Returns:
        The default document.

      • createPopupMenuItem

        protected JMenuItem createPopupMenuItem​(Action a)
        Creates and configures a menu item for used in the popup menu.
        Parameters:
        a - The action for the menu item.
        Returns:
        The menu item.
        See Also:
        createPopupMenu()

      • createUndoManager

        protected RUndoManager createUndoManager()
        Creates an undo manager for use in this text area.
        Returns:
        The undo manager.

      • discardAllEdits

        public void discardAllEdits()
        Removes all undoable edits from this document's undo manager. This method also makes the undo/redo actions disabled.

      • endAtomicEdit

        public void endAtomicEdit()
        Completes an "atomic" edit.
        See Also:
        beginAtomicEdit()

      • endRecordingMacro

        public static void endRecordingMacro()
        Ends recording a macro. If this method is called but the text component is not recording a macro, nothing happens.
        See Also:
        isRecordingMacro(), beginRecordingMacro()

      • fireCaretUpdate

        protected void fireCaretUpdate​(CaretEvent e)
        Notifies all listeners that a caret change has occurred.
        Overrides:
        fireCaretUpdate in class JTextComponent
        Parameters:
        e - The caret event.

      • getAction

        public static RecordableTextAction getAction​(int action)
        Provides a way to gain access to the editor actions on the right-click popup menu. This way you can make toolbar/menu bar items use the actual actions used by all RTextAreas, so that icons stay synchronized and you don't have to worry about enabling/disabling them yourself.

        Keep in mind that these actions are shared across all instances of RTextArea, so a change to any action returned by this method is global across all RTextArea editors in your application.

        Parameters:
        action - The action to retrieve, such as CUT_ACTION. If the action name is invalid, null is returned.
        Returns:
        The action, or null if an invalid action is requested.

      • getCurrentMacro

        public static Macro getCurrentMacro()
        Returns the macro currently stored in this RTextArea. Since macros are shared, all RTextAreas in the currently- running application are using this macro.
        Returns:
        The current macro, or null if no macro has been recorded/loaded.
        See Also:
        loadMacro(Macro)

      • getIconGroup

        public static IconGroup getIconGroup()
        Returns the icon group being used for the actions of this text area.
        Returns:
        The icon group.
        See Also:
        setIconGroup(IconGroup)

      • getMaxAscent

        public int getMaxAscent()
        Returns the maximum ascent of all fonts used in this text area. In the case of a standard RTextArea, this is simply the ascent of the current font.

        This value could be useful, for example, to implement a line-numbering scheme.

        Returns:
        The ascent of the current font.

      • getSelectedOccurrenceText

        public static String getSelectedOccurrenceText()
        Returns the text last selected and used in a Ctrl+K operation.
        Returns:
        The text, or null if none.
        See Also:
        setSelectedOccurrenceText(String)

      • handleReplaceSelection

        protected void handleReplaceSelection​(String content)
        Does the actual dirty-work of replacing the selected text in this text area (i.e., in its document). This method provides a hook for subclasses to handle this in a different way.
        Parameters:
        content - The content to add.

      • init

        protected void init()
        Initializes this text area.
        Overrides:
        init in class RTextAreaBase

      • isRecordingMacro

        public static boolean isRecordingMacro()
        Returns whether or not a macro is being recorded.
        Returns:
        Whether or not a macro is being recorded.
        See Also:
        beginRecordingMacro(), endRecordingMacro()

      • loadMacro

        public static void loadMacro​(Macro macro)
        Loads a macro to be used by all RTextAreas in the current application.
        Parameters:
        macro - The macro to load.
        See Also:
        getCurrentMacro()

      • playbackLastMacro

        public void playbackLastMacro()
        "Plays back" the last recorded macro in this text area.

      • print

        public int print​(Graphics g,
                 PageFormat pageFormat,
                 int pageIndex)
        Method called when it's time to print this badboy (the old-school, AWT way).
        Specified by:
        print in interface Printable
        Parameters:
        g - The context into which the page is drawn.
        pageFormat - The size and orientation of the page being drawn.
        pageIndex - The zero based index of the page to be drawn.

      • read

        public void read​(Reader in,
                 Object desc)
          throws IOException
        We override this method because the super version gives us an entirely new Document, thus requiring us to re-attach our Undo manager. With this version we just replace the text.
        Overrides:
        read in class JTextComponent
        Throws:
        IOException

      • redoLastAction

        public void redoLastAction()
        Attempt to redo the last action.
        See Also:
        undoLastAction()

      • replaceRange

        public void replaceRange​(String str,
                         int start,
                         int end)
        Replaces text from the indicated start to end position with the new text specified. Does nothing if the model is null. Simply does a delete if the new string is null or empty.

        This method is thread safe, although most Swing methods are not.

        This method is overridden so that our Undo manager remembers it as a single operation (it has trouble with this, especially for RSyntaxTextArea and the "auto-indent" feature).

        Overrides:
        replaceRange in class JTextArea
        Parameters:
        str - the text to use as the replacement
        start - the start position >= 0
        end - the end position >= start
        Throws:
        IllegalArgumentException - if part of the range is an invalid position in the model
        See Also:
        JTextArea.insert(String, int), replaceRange(String, int, int)

      • replaceSelection

        public void replaceSelection​(String text)
        This method overrides JTextComponent's replaceSelection, so that if textMode is OVERWRITE_MODE, it actually overwrites.
        Overrides:
        replaceSelection in class JTextComponent
        Parameters:
        text - The content to replace the selection with.

      • setActionProperties

        public static void setActionProperties​(int action,
                                       String name,
                                       char mnemonic,
                                       KeyStroke accelerator)
        Sets the properties of one of the actions this text area owns.
        Parameters:
        action - The action to modify; for example, CUT_ACTION.
        name - The new name for the action.
        mnemonic - The new mnemonic for the action.
        accelerator - The new accelerator key for the action.

      • setActionProperties

        public static void setActionProperties​(int action,
                                       String name,
                                       Integer mnemonic,
                                       KeyStroke accelerator)
        Sets the properties of one of the actions this text area owns.
        Parameters:
        action - The action to modify; for example, CUT_ACTION.
        name - The new name for the action.
        mnemonic - The new mnemonic for the action.
        accelerator - The new accelerator key for the action.

      • setCaret

        public void setCaret​(Caret caret)
        Sets the caret to use in this text area. It is strongly encouraged to use ConfigurableCarets (which is used by default), or a subclass, since they know how to render themselves differently when the user toggles between insert and overwrite modes.
        Overrides:
        setCaret in class JTextComponent
        Parameters:
        caret - The caret to use. If this is not an instance of ConfigurableCaret, an exception is thrown.
        Throws:
        IllegalArgumentException - If the specified caret is not an ConfigurableCaret.
        See Also:
        setCaretStyle(int, CaretStyle)

      • setIconGroup

        public static void setIconGroup​(IconGroup group)
        Sets the path in which to find images to associate with the editor's actions. The path MUST contain the following images (with the appropriate extension as defined by the icon group):
        • cut
        • copy
        • paste
        • delete
        • undo
        • redo
        • selectall
        If any of the above images don't exist, the corresponding action will not have an icon.
        Parameters:
        group - The icon group to load.
        See Also:
        getIconGroup()

      • setMarkAllHighlightColor

        public void setMarkAllHighlightColor​(Color color)
        Sets the color used for "mark all." This fires a property change of type MARK_ALL_COLOR_PROPERTY.
        Parameters:
        color - The color to use for "mark all."
        See Also:
        getMarkAllHighlightColor()

      • setPopupMenu

        public void setPopupMenu​(JPopupMenu popupMenu)
        Sets the popup menu used by this text area.

        If you set the popup menu with this method, you'll want to consider also overriding configurePopupMenu(JPopupMenu), especially if you removed any of the default menu items.

        Parameters:
        popupMenu - The popup menu. If this is null, no popup menu will be displayed.
        See Also:
        getPopupMenu(), configurePopupMenu(JPopupMenu)

      • setSelectedOccurrenceText

        public static void setSelectedOccurrenceText​(String text)
        Sets the text last selected/Ctrl+K'd in an RTextArea. This text will be searched for in subsequent Ctrl+K/Ctrl+Shift+K actions (Cmd+K on OS X).

        Since the selected occurrence actions are built into RTextArea, applications usually do not have to call this method directly, but can choose to do so if they wish (for example, if they wish to set this value when the user does a search via a Find dialog).

        Parameters:
        text - The selected text.
        See Also:
        getSelectedOccurrenceText()

      • setTextMode

        public void setTextMode​(int mode)
        Sets the text mode for this editor pane. If the currently installed caret is an instance of ConfigurableCaret, it will be automatically updated to render itself appropriately for the new text mode.
        Parameters:
        mode - Either INSERT_MODE or OVERWRITE_MODE.
        See Also:
        getTextMode()

      • setToolTipSupplier

        public void setToolTipSupplier​(ToolTipSupplier supplier)
        Sets the tool tip supplier.
        Parameters:
        supplier - The new tool tip supplier, or null if there is to be no supplier.
        See Also:
        getToolTipSupplier()

      • setUI

        public final void setUI​(TextUI ui)
        Sets the UI used by this text area. This is overridden so only the right-click popup menu's UI is updated. The look and feel of an RTextArea is independent of the Java Look and Feel, and so this method does not change the text area itself. Subclasses (such as RSyntaxTextArea can call setRTextAreaUI if they wish to install a new UI.
        Overrides:
        setUI in class JTextComponent
        Parameters:
        ui - This parameter is ignored.

      • undoLastAction

        public void undoLastAction()
        Attempt to undo an "action" done in this text area.
        See Also:
        redoLastAction()