This class is the visible component that displays the file being edited. It is derived from Java's JComponent class.
Methods in this class that deal with selecting text rely upon classes derived from jEdit's Selection class. The "Selection API" permits selection and concurrent manipulation of multiple, non-contiguous regions of text. After describing the selection classes, we will outline the selection methods of JEditTextArea, followed by a listing of other methods in this class that are useful in writing macros.
This is an abstract class which holds data on a region of selected text. As an abstract class, it cannot be used directly, but instead serves as a parent class for specific types of selection structures. The definition of Selection contains two child classes used by the Selection API:
Selection.Range - representing an ordinary range of selected text
Selection.Rect - representing a rectangular selection region
A new instance of either type of Selection can be created by specifying its starting and ending caret positions:
selRange = new Selection.Range(start, end); setRect = new Selection.Rect(start, end); |
Both classes inherit or implement the following methods of the parent Selection class:
public int getStart(
void)
;
public int getEnd(
void)
;
Retrieves the buffer position representing the start or end of the selection.
public int getStartLine(
void)
;
public int getEndLine(
void)
;
Retrieves the zero-based index number representing the line on which the selection starts or ends.
public int getStart(
Buffer buffer, int line)
;
public int getEnd(
Buffer buffer, int line)
;
These two methods return the position of the beginning or end of that portion of the selection falling on the line referenced by the line parameter. The parameter buffer is required because a Selection object is a lightweight structure that does not contain a reference to the Buffer object to which it relates.
These methods do not check whether the line parameter is within the range of lines actually covered by the selection. They would typically be used within a loop defined by the getStartLine() and getEndLine() methods to manipulate selection text on a line-by-line basis. Using them without range checking could cause unintended behavior.
A JEditTextArea object maintains an Vector of current Selection objects. When a selection is added, the JEditTextArea attempts to merge the new selection with any existing selection whose range contains or overlaps with the new item. When selections are added or removed using by these methods, the editing display is updated to show the change in selection status.
Here are the principal methods of JEditTextArea dealing with Selection objects:
public void setMultipleSelectionEnabled( | boolean | multi) ; |
Set multiple selection on or off according to the value of multi. This only affects the ability to make multiple selections in the user interface; macros and plugins can manipulate them regardless of the setting of this flag. In fact, in most cases, calling this method should not be necessary.
public Selection[] getSelection(
void)
;
Returns an array containing a copy of the current selections.
public int getSelectionCount(
void)
;
Returns the current number of selections. This can be used to test for the existence of selections.
public Selection getSelectionAtOffset( | int | offset) ; |
Returns the Selection containing the specific offset, or null if there is no selection at that offset.
public void addToSelection( | Selection | selection) ; |
public void addToSelection( | Selection[] | selection) ; |
Adds a single Selection or an array of Selection objects to the existing collection maintained by the JEditTextArea. Nested or overlapping selections will be merged where possible.
public void extendSelection( | int | offset, |
int | end) ; |
Extends the existing selection containing the position at offset to the position represented by end. If there is no selection containing offset the method creates a new Selection.Range extending from offset to end and adds it to the current collection.
public void removeFromSelection( | Selection | sel) ; |
public void removeFromSelection( | int | offset) ; |
These methods remove a selection from the current collection. The second version removes any selection that contains the position at offset, and has no effect if no such selection exists.
public String getSelectedText( | Selection | s) ; |
public String getSelectedText( | String | separator) ; |
public String getSelectedText(
void)
;
These three methods return a String containing text corresponding to the current selections. The first version returns the text corresponding to a particular selection named as the parameter, allowing for iteration through the collection or focus on a specific selection (such as a selection containing the current caret position). The second version combines all selection text in a single String, separated by the String given as the separator. The final version operates like the second version, separating individual selections with newline characters.
public void setSelectedText( | Selection | s, |
String | selectedText) ; |
public void setSelectedText( | String | selectedText) ; |
The first version changes the text of the selection represented by s to selectedText. The second version sets the text of all active selections; if there are no selections, the text will be inserted at the current caret position.
The second version of setSelectedText() is the method that will typically be used in macro scripts to insert text.
public int[] getSelectedLines(
void)
;
Returns a sorted array of line numbers on which a selection or selections are present.
This method is the most convenient way to iterate through selected lines in a buffer. The line numbers in the array returned by this method can be passed as a parameter to such methods as Buffer.getLineText() (see the section called "General editing methods").
The following methods perform selection operations without using Selection objects as parameters or return values. These methods should only be used in macros.
public void selectBlock(
void)
;
Selects the code block surrounding the caret.
public void selectWord(
void)
;
public void selectLine(
void)
;
public void selectParagraph(
void)
;
public void selectFold(
void)
;
Selects the "fold" (a portion of text sharing a given indentation level) that contains the line where the editing caret is positioned.
public void selectFoldAt(
int line)
;
Selects the fold containing the line referenced by line.
public void selectAll(
void)
;
public void selectNone(
void)
;
public void indentSelectedLines(
void)
;
These methods are used to get, set and move the position of the editing caret:
public int getCaretPosition(
void)
;
Returns a zero-based index of the caret position in the existing buffer.
public void setCaretPosition(
int caret)
;
Sets the caret position at caret and deactivates any selection of text.
public void moveCaretPosition(
int caret)
;
This moves the caret to the position represented by caret without affecting any selection of text.
public int getCaretLine(
void)
;
Returns the line on which the caret is positioned.
Each of the following shortcut methods moves the caret. If the select parameter is set to true, the intervening text will be selected as well.
public void goToStartOfLine( | boolean | select) ; |
public void goToEndOfLine(
boolean select)
;
public void goToStartOfWhiteSpace( | boolean | select) ; |
public void goToEndOfWhiteSpace( | boolean | select) ; |
public void goToFirstVisibleLine( | boolean | select) ; |
public void goToLastVisibleLine( | boolean | select) ; |
public void goToNextCharacter( | boolean | select) ; |
public void goToPrevCharacter( | boolean | select) ; |
public void goToNextWord(
boolean select)
;
public void goToPrevWord(
boolean select)
;
public void goToNextLine(
boolean select)
;
public void goToPrevLine(
boolean select)
;
public void goToNextParagraph( | boolean | select) ; |
public void goToPrevParagraph( | boolean | select) ; |
public void goToNextBracket( | boolean | select) ; |
public void goToPrevBracket( | boolean | select) ; |
public void scrollUpLine(
void)
;
public void scrollUpPage(
void)
;
public void scrollDownLine(
void)
;
public void scrollUpPage(
void)
;
public void scrollTo( | int | location, |
boolean | doElectricScroll) ; |
public void scrollToCaret( | boolean | doElectricScroll) ; |
The first version scrolls the text area to ensure that the caret is visible; the second scrolls to ensure that an arbitrary offset (from the start of the buffer) is visible. The doElectricScroll parameter determines whether "electric scrolling" will occur. This leaves a minimum number of lines between the target line and the top and bottom of the editing pane.
public void centerCaret(
void)
;
Scrolls the text area so that the line containing the edit caret is vertically centered.
public void setFirstLine(
int firstLine)
;
public int getFirstLine(
void)
;
This pair of methods deals with the line number of the first line displayed at the top of the text area. Lines that are hidden by folds or narrowing are ignored when making this "virtual" line count, so the line number will not necessarily conform to the line numbers displayed in the text area's gutter. In addition, the virtual line index is zero-based, so getFirstLine() will always return zero for the first line of text.
To convert a virtual line count to a physical count or vice versa, see the section called "Virtual and physical line indices".
public void backspace(
void)
;
public void backspaceWord(
void)
;
public void delete(
void)
;
public void deleteWord(
void)
;
public void deleteLine(
void)
;
public void deleteParagraph(
void)
;
public void deleteToStartOfLine(
void)
;
public void deleteToEndOfLine(
void)
;
public void toLowerCase(
void)
;
public void toUpperCase(
void)
;
These two methods operate on all selected text, including multiple selections.
public void joinLines(
void)
;
Joins the current line with the following line.
public void setOverwriteEnabled( | boolean | overwrite) ; |
public boolean isOverwriteEnabled(
void)
;
Sets and gets whether added text will overwrite text at the editing caret or whether it will be inserted immediately to the right of the caret.
public void userInput(
char ch)
;
Inserts the character at the caret position as if it were typed at the keyboard (keyboard input is actually passed to this method). Unlike setSelectedText(), or insert() in the Buffer class, this method triggers any active text formatting features such as auto indent, abbreviation expansion and word wrap.
public void lineComment(
void)
;
This inserts the line comment string at the beginning of each selected line.
public void rangeComment(
void)
;
This surrounds each selected text chunk with the comment start and end strings.
When jEdit's folding or narrowing features are used to hide portions of a buffer, the "virtual" line count visible in the text area is generally not equal to the "physical" line count of the buffer represented by the gutter's display. The following pair of methods translate one enumeration to the other.
public int virtualToPhysical(
int lineNo)
;
public int physicalToVirtual(
int lineNo)
;