Class RTextArea

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.text.JTextComponent
javax.swing.JTextArea
org.fife.ui.rtextarea.RTextAreaBase
org.fife.ui.rtextarea.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.
Version:
1.0
See Also:

  • Field Details

  • Constructor Details

    • 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 Details

    • addToCurrentMacro

      static void addToCurrentMacro(String id, String actionCommand)
      Adds an action event to the current macro. This shouldn't be called directly, as it is called by the actions themselves.
      Parameters:
      id - The ID of the recordable text action.
      actionCommand - The "command" of the action event passed to it.

    • addLineHighlight

      public Object addLineHighlight(int line, Color color) throws BadLocationException
      Adds a line highlight.
      Parameters:
      line - The line to highlight. This is zero-based.
      color - The color to highlight the line with.
      Returns:
      An opaque tag that can be used to remove the highlight later.
      Throws:
      BadLocationException - If line is an invalid line number.
      See Also:

    • 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:

    • 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:

    • canUndo

      public boolean canUndo()
      Returns whether an undo is possible.
      Returns:
      Whether the operation was successful.
      See Also:

    • canRedo

      public boolean canRedo()
      Returns whether a redo is possible.
      Returns:
      Whether the operation was successful.
      See Also:

    • clearMarkAllHighlights

      public void clearMarkAllHighlights()
      Clears any "mark all" highlights, if any. As SearchEngine handles "mark all" highlights itself, the programmer doesn't usually need to call this directly. One use case to do so might be doing custom highlighting of specific text in the text area.
      See Also:

    • 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:

    • 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.

    • createMouseListener

      protected RTextAreaBase.RTAMouseListener createMouseListener()
      Returns the caret event/mouse listener for RTextAreas.
      Specified by:
      createMouseListener in class RTextAreaBase
      Returns:
      The caret event/mouse listener.

    • createPopupMenu

      protected JPopupMenu createPopupMenu()
      Creates the right-click popup menu. Subclasses can override this method to replace or augment the popup menu returned.
      Returns:
      The popup menu.
      See Also:

    • createPopupMenuActions

      private static void createPopupMenuActions()
      Creates the actions used in the popup menu and retrievable by getAction(int). TODO: Remove these horrible hacks and move localizing of actions into the editor kits, where it should be! The context menu should contain actions from the editor kits.

    • 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:

    • createRTextAreaUI

      protected RTextAreaUI createRTextAreaUI()
      Returns a real UI to install on this text area.
      Specified by:
      createRTextAreaUI in class RTextAreaBase
      Returns:
      The UI.

    • createSpacer

      private String createSpacer(int size)
      Creates a string of space characters of the specified size.
      Parameters:
      size - The number of spaces.
      Returns:
      The string of spaces.

    • 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:

    • 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:

    • 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.

    • fixCtrlH

      private void fixCtrlH()
      Removes the "Ctrl+H invalid input: '<'=> Backspace" behavior that Java shows, for some odd reason...

    • 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:

    • getDefaultMarkAllHighlightColor

      public static Color getDefaultMarkAllHighlightColor()
      Returns the default color used for "mark all" highlights.
      Returns:
      The color.
      See Also:

    • getDefaultModifier

      public static int getDefaultModifier()
      Returns the default modifier key for a system. For example, on Windows this would be the CTRL key (InputEvent.CTRL_MASK).
      Returns:
      The default modifier key.

    • getIconGroup

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

    • getMarkAllOnOccurrenceSearches

      public boolean getMarkAllOnOccurrenceSearches()
      Returns whether "mark all" should be enabled when a user does a "find next/find previous" action via Ctrl+K or Ctrl+Shift+K (the default shortcut keys for this action). The default value is true.
      Returns:
      Whether "mark all" should be enabled.
      See Also:

    • getLineHighlightManager

      LineHighlightManager getLineHighlightManager()
      Returns the line highlight manager.
      Returns:
      The line highlight manager. This may be null.

    • getMarkAllHighlightColor

      public Color getMarkAllHighlightColor()
      Returns the color used in "mark all" highlights.
      Returns:
      The color.
      See Also:

    • 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.

    • getPopupMenu

      public JPopupMenu getPopupMenu()
      Returns the popup menu for this component, lazily creating it if necessary.
      Returns:
      The popup menu.
      See Also:

    • 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:

    • getTextMode

      public final int getTextMode()
      Returns the text mode this editor pane is currently in.
      Returns:
      Either INSERT_MODE or OVERWRITE_MODE.
      See Also:

    • getToolTipSupplier

      public ToolTipSupplier getToolTipSupplier()
      Returns the tool tip supplier.
      Returns:
      The tool tip supplier, or null if one isn't installed.
      See Also:

    • getToolTipText

      public String getToolTipText(MouseEvent e)
      Returns the tooltip to display for a mouse event at the given location. This method is overridden to check for a ToolTipSupplier; if there is one installed, it is queried for tool tip text before using the super class's implementation of this method.
      Overrides:
      getToolTipText in class JTextComponent
      Parameters:
      e - The mouse event.
      Returns:
      The tool tip text, or null if none.
      See Also:

    • 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()
      Description copied from class: RTextAreaBase
      Initializes this text area.
      Overrides:
      init in class RTextAreaBase

    • isRecordingMacro

      public static boolean isRecordingMacro()
      Returns whether a macro is being recorded.
      Returns:
      Whether a macro is being recorded.
      See Also:

    • 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:

    • markAll

      public void markAll(List<DocumentRange> ranges)
      Marks all ranges specified with the "mark all" highlighter. As SearchEngine handles "mark all" highlights itself, the programmer doesn't usually need to call this directly. One use case to do so might be doing custom highlighting of specific text in the text area.

      This method fires a property change event of type MARK_ALL_OCCURRENCES_CHANGED_PROPERTY.

      Parameters:
      ranges - The ranges to mark. This should not be null.
      See Also:

    • paste

      public void paste()
      Overrides:
      paste in class JTextComponent

    • 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.

    • processMouseEvent

      protected void processMouseEvent(MouseEvent e)
      Overridden to disable drag-and-drop if the user triple-clicks. Typically, the user will select text, or double-click a word, then drag it to its destination. Triple-clicking before dragging text to a new location is rare. For that reason, we disable it in that case since it causes issues with triple-click-to-select-by-line. See https://github.com/bobbylight/RSyntaxTextArea/issues/59 for more information.
      Overrides:
      processMouseEvent in class JComponent
      Parameters:
      e - The mouse event being dispatched.

    • 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

    • readObject

      private void readObject(ObjectInputStream s) throws ClassNotFoundException, IOException
      De-serializes a text area.
      Parameters:
      s - The stream to read from.
      Throws:
      ClassNotFoundException - If something bad happens.
      IOException - If an IO error occurs.

    • redoLastAction

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

    • removeAllLineHighlights

      public void removeAllLineHighlights()
      Removes all line highlights.
      See Also:

    • removeLineHighlight

      public void removeLineHighlight(Object tag)
      Removes a line highlight.
      Parameters:
      tag - The tag of the line highlight to remove.
      See Also:

    • 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:

    • 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.

    • replaceTabsWithSpaces

      private String replaceTabsWithSpaces(String text, int docOffs, int firstTab) throws BadLocationException
      Replaces all instances of the tab character in text with the number of spaces equivalent to a tab in this text area.

      This method should only be called from thread-safe methods, such as replaceSelection(String).

      Parameters:
      text - The java.lang.String in which to replace tabs with spaces. This has already been verified to have at least one tab character in it.
      docOffs - The offset in the document at which the text is being inserted.
      firstTab - The offset into text of the first tab. Assumed to be >= 0.
      Returns:
      A String just like text, but with spaces instead of tabs.
      Throws:
      BadLocationException

    • 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.
      See Also:

    • setCaretStyle

      public void setCaretStyle(int mode, CaretStyle style)
      Sets the style of caret used when in insert or overwrite mode.
      Parameters:
      mode - Either INSERT_MODE or OVERWRITE_MODE.
      style - The style for the caret.
      See Also:

    • setDocument

      public void setDocument(Document document)
      Sets the document used by this text area.
      Overrides:
      setDocument in class JTextComponent
      Parameters:
      document - The new document to use.
      Throws:
      IllegalArgumentException - If the document is not an instance of RDocument.

    • 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:

    • 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:

    • setMarkAllOnOccurrenceSearches

      public void setMarkAllOnOccurrenceSearches(boolean markAll)
      Sets whether "mark all" should be enabled when a user does a "find next/find previous" action via Ctrl+K or Ctrl+Shift+K (the default shortcut keys for this action). The default value is true.

      This method fires a property change event of type MARK_ALL_ON_OCCURRENCE_SEARCHES_PROPERTY.

      Parameters:
      markAll - Whether "mark all" should be enabled.
      See Also:

    • 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:

    • setRoundedSelectionEdges

      public void setRoundedSelectionEdges(boolean rounded)
      Description copied from class: RTextAreaBase
      Sets whether the edges of selections are rounded in this text area. This method fires a property change of type RTextAreaBase.ROUNDED_SELECTION_PROPERTY.
      Overrides:
      setRoundedSelectionEdges in class RTextAreaBase
      Parameters:
      rounded - Whether selection edges should be rounded.
      See Also:

    • 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:

    • 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:

    • 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:

    • 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:

    • writeObject

      private void writeObject(ObjectOutputStream s) throws IOException
      Serializes this text area.
      Parameters:
      s - The stream to write to.
      Throws:
      IOException - If an IO error occurs.