JTextArea component provides a multi-line area for displaying
* and editing plain text. The component is designed to act as a lightweight
* replacement for the heavyweight java.awt.TextArea component,
* which provides similar functionality using native widgets.
*
*
* This component has additional functionality to the AWT class. It follows
* the same design pattern as seen in other text components, such as
* JTextField, JTextPane and JEditorPane,
* and embodied in JTextComponent. These classes separate the text
* (the model) from its appearance within the onscreen component (the view). The
* text is held within a javax.swing.text.Document object, which can
* also maintain relevant style information where necessary. As a result, it is the
* document that should be monitored for textual changes, via
* DocumentEvents delivered to registered
* DocumentListeners, rather than this component.
*
*
* Unlike java.awt.TextArea, JTextArea does not
* handle scrolling. Instead, this functionality is delegated to a
* JScrollPane, which can contain the text area and handle
* scrolling when required. Likewise, the word wrapping functionality
* of the AWT component is converted to a property of this component
* and the rows and columns properties
* are used in calculating the preferred size of the scroll pane's
* view port.
*
* @author Michael Koch (konqueror@gmx.de)
* @author Andrew John Hughes (gnu_andrew@member.fsf.org)
* @see java.awt.TextArea
* @see javax.swing.text.JTextComponent
* @see javax.swing.JTextField
* @see javax.swing.JTextPane
* @see javax.swing.JEditorPane
* @see javax.swing.text.Document
* @see javax.swing.event.DocumentEvent
* @see javax.swing.event.DocumentListener
*/
public class JTextArea extends JTextComponent
{
/**
* Provides accessibility support for JTextArea.
*
* @author Roman Kennke (kennke@aicas.com)
*/
protected class AccessibleJTextArea extends AccessibleJTextComponent
{
/**
* Creates a new AccessibleJTextArea object.
*/
protected AccessibleJTextArea()
{
super();
}
/**
* Returns the accessible state of this AccessibleJTextArea.
*
* @return the accessible state of this AccessibleJTextArea
*/
public AccessibleStateSet getAccessibleStateSet()
{
AccessibleStateSet state = super.getAccessibleStateSet();
// TODO: Figure out what state must be added here to the super's state.
return state;
}
}
/**
* Compatible with Sun's JDK
*/
private static final long serialVersionUID = -6141680179310439825L;
/**
* The number of rows used by the component.
*/
private int rows;
/**
* The number of columns used by the component.
*/
private int columns;
/**
* Whether line wrapping is enabled or not.
*/
private boolean lineWrap;
/**
* The number of characters equal to a tab within the text.
*/
private int tabSize = 8;
private boolean wrapStyleWord;
/**
* Creates a new JTextArea object.
*/
public JTextArea()
{
this(null, null, 0, 0);
}
/**
* Creates a new JTextArea object.
*
* @param text the initial text
*/
public JTextArea(String text)
{
this(null, text, 0, 0);
}
/**
* Creates a new JTextArea object.
*
* @param rows the number of rows
* @param columns the number of cols
*
* @exception IllegalArgumentException if rows or columns are negative
*/
public JTextArea(int rows, int columns)
{
this(null, null, rows, columns);
}
/**
* Creates a new JTextArea object.
*
* @param text the initial text
* @param rows the number of rows
* @param columns the number of cols
*
* @exception IllegalArgumentException if rows or columns are negative
*/
public JTextArea(String text, int rows, int columns)
{
this(null, text, rows, columns);
}
/**
* Creates a new JTextArea object.
*
* @param doc the document model to use
*/
public JTextArea(Document doc)
{
this(doc, null, 0, 0);
}
/**
* Creates a new JTextArea object.
*
* @param doc the document model to use
* @param text the initial text
* @param rows the number of rows
* @param columns the number of cols
*
* @exception IllegalArgumentException if rows or columns are negative
*/
public JTextArea(Document doc, String text, int rows, int columns)
{
setDocument(doc == null ? createDefaultModel() : doc);
// Only explicitly setText() when there is actual text since
// setText() might be overridden and not expected to be called
// from the constructor (as in JEdit).
if (text != null)
setText(text);
setRows(rows);
setColumns(columns);
}
/**
* Appends the supplied text to the current contents
* of the document model.
*
* @param toAppend the text to append
*/
public void append(String toAppend)
{
try
{
getDocument().insertString(getText().length(), toAppend, null);
}
catch (BadLocationException exception)
{
/* This shouldn't happen in theory -- but, if it does... */
throw new RuntimeException("Unexpected exception occurred.", exception);
}
if (toAppend != null && toAppend.length() > 0)
revalidate();
}
/**
* Creates the default document model.
*
* @return a new default model
*/
protected Document createDefaultModel()
{
return new PlainDocument();
}
/**
* Returns true if the width of this component should be forced
* to match the width of a surrounding view port. When line wrapping
* is turned on, this method returns true.
*
* @return true if lines are wrapped.
*/
public boolean getScrollableTracksViewportWidth()
{
return lineWrap ? true : super.getScrollableTracksViewportWidth();
}
/**
* Returns the increment that is needed to expose exactly one new line
* of text. This is implemented here to return the values of
* {@link #getRowHeight} and {@link #getColumnWidth}, depending on
* the value of the argument direction.
*
* @param visibleRect the view area that is visible in the viewport
* @param orientation either {@link SwingConstants#VERTICAL} or
* {@link SwingConstants#HORIZONTAL}
* @param direction less than zero for up/left scrolling, greater
* than zero for down/right scrolling
*
* @return the increment that is needed to expose exactly one new row
* or column of text
*
* @throws IllegalArgumentException if orientation is invalid
*/
public int getScrollableUnitIncrement(Rectangle visibleRect, int orientation,
int direction)
{
if (orientation == SwingConstants.VERTICAL)
return getRowHeight();
else if (orientation == SwingConstants.HORIZONTAL)
return getColumnWidth();
else
throw new IllegalArgumentException("orientation must be either "
+ "javax.swing.SwingConstants.VERTICAL "
+ "or "
+ "javax.swing.SwingConstants.HORIZONTAL"
);
}
/**
* Returns the preferred size of that text component in the case
* it is embedded within a JScrollPane. This uses the column and
* row settings if they are explicitly set, or fall back to
* the superclass's behaviour.
*
* @return the preferred size of that text component in the case
* it is embedded within a JScrollPane
*/
public Dimension getPreferredScrollableViewportSize()
{
if ((rows > 0) && (columns > 0))
return new Dimension(columns * getColumnWidth(), rows * getRowHeight());
else
return super.getPreferredScrollableViewportSize();
}
/**
* Returns the UI class ID string.
*
* @return the string "TextAreaUI"
*/
public String getUIClassID()
{
return "TextAreaUI";
}
/**
* Returns the current number of columns.
*
* @return number of columns
*/
public int getColumns()
{
return columns;
}
/**
* Sets the number of rows.
*
* @param columns number of columns
*
* @exception IllegalArgumentException if columns is negative
*/
public void setColumns(int columns)
{
if (columns < 0)
throw new IllegalArgumentException();
if (columns != this.columns)
{
this.columns = columns;
revalidate();
}
}
/**
* Returns the current number of rows.
*
* @return number of rows
*/
public int getRows()
{
return rows;
}
/**
* Sets the number of rows.
*
* @param rows number of rows
*
* @exception IllegalArgumentException if rows is negative
*/
public void setRows(int rows)
{
if (rows < 0)
throw new IllegalArgumentException();
if (rows != this.rows)
{
this.rows = rows;
revalidate();
}
}
/**
* Checks whether line wrapping is enabled.
*
* @return true if line wrapping is enabled,
* false otherwise
*/
public boolean getLineWrap()
{
return lineWrap;
}
/**
* Enables/disables line wrapping.
*
* @param flag true to enable line wrapping,
* false otherwise
*/
public void setLineWrap(boolean flag)
{
if (lineWrap == flag)
return;
boolean oldValue = lineWrap;
lineWrap = flag;
firePropertyChange("lineWrap", oldValue, lineWrap);
}
/**
* Checks whether word style wrapping is enabled.
*
* @return true if word style wrapping is enabled,
* false otherwise
*/
public boolean getWrapStyleWord()
{
return wrapStyleWord;
}
/**
* Enables/Disables word style wrapping.
*
* @param flag true to enable word style wrapping,
* false otherwise
*/
public void setWrapStyleWord(boolean flag)
{
if (wrapStyleWord == flag)
return;
boolean oldValue = wrapStyleWord;
wrapStyleWord = flag;
firePropertyChange("wrapStyleWord", oldValue, wrapStyleWord);
}
/**
* Returns the number of characters used for a tab.
* This defaults to 8.
*
* @return the current number of spaces used for a tab.
*/
public int getTabSize()
{
return tabSize;
}
/**
* Sets the number of characters used for a tab to the
* supplied value. If a change to the tab size property
* occurs (i.e. newSize != tabSize), a property change event
* is fired.
*
* @param newSize The new number of characters to use for a tab.
*/
public void setTabSize(int newSize)
{
if (tabSize == newSize)
return;
int oldValue = tabSize;
tabSize = newSize;
firePropertyChange("tabSize", oldValue, tabSize);
}
protected int getColumnWidth()
{
FontMetrics metrics = getToolkit().getFontMetrics(getFont());
return metrics.charWidth('m');
}
public int getLineCount()
{
return getDocument().getDefaultRootElement().getElementCount();
}
public int getLineStartOffset(int line)
throws BadLocationException
{
int lineCount = getLineCount();
if (line < 0 || line > lineCount)
throw new BadLocationException("Non-existing line number", line);
Element lineElem = getDocument().getDefaultRootElement().getElement(line);
return lineElem.getStartOffset();
}
public int getLineEndOffset(int line)
throws BadLocationException
{
int lineCount = getLineCount();
if (line < 0 || line > lineCount)
throw new BadLocationException("Non-existing line number", line);
Element lineElem = getDocument().getDefaultRootElement().getElement(line);
return lineElem.getEndOffset();
}
public int getLineOfOffset(int offset)
throws BadLocationException
{
Document doc = getDocument();
if (offset < doc.getStartPosition().getOffset()
|| offset >= doc.getEndPosition().getOffset())
throw new BadLocationException("offset outside of document", offset);
return doc.getDefaultRootElement().getElementIndex(offset);
}
protected int getRowHeight()
{
FontMetrics metrics = getToolkit().getFontMetrics(getFont());
return metrics.getHeight();
}
/**
* Inserts the supplied text at the specified position. Nothing
* happens in the case that the model or the supplied string is null
* or of zero length.
*
* @param string The string of text to insert.
* @param position The position at which to insert the supplied text.
* @throws IllegalArgumentException if the position is < 0 or greater
* than the length of the current text.
*/
public void insert(String string, int position)
{
// Retrieve the document model.
Document doc = getDocument();
// Check the model and string for validity.
if (doc == null
|| string == null
|| string.length() == 0)
return;
// Insert the text into the model.
try
{
doc.insertString(position, string, null);
}
catch (BadLocationException e)
{
throw new IllegalArgumentException("The supplied position, "
+ position + ", was invalid.");
}
}
public void replaceRange(String text, int start, int end)
{
Document doc = getDocument();
if (start > end
|| start < doc.getStartPosition().getOffset()
|| end >= doc.getEndPosition().getOffset())
throw new IllegalArgumentException();
try
{
doc.remove(start, end - start);
doc.insertString(start, text, null);
}
catch (BadLocationException e)
{
// This cannot happen as we check offset above.
}
}
/**
* Returns the preferred size for the JTextArea. This is the maximum of
* the size that is needed to display the content and the requested size
* as per {@link #getColumns} and {@link #getRows}.
*
* @return the preferred size of the JTextArea
*/
public Dimension getPreferredSize()
{
int reqWidth = getColumns() * getColumnWidth();
int reqHeight = getRows() * getRowHeight();
View view = getUI().getRootView(this);
int neededWidth = (int) view.getPreferredSpan(View.HORIZONTAL);
int neededHeight = (int) view.getPreferredSpan(View.VERTICAL);
return new Dimension(Math.max(reqWidth, neededWidth),
Math.max(reqHeight, neededHeight));
}
/**
* Returns the accessible context associated with the JTextArea.
*
* @return the accessible context associated with the JTextArea
*/
public AccessibleContext getAccessibleContext()
{
if (accessibleContext == null)
accessibleContext = new AccessibleJTextArea();
return accessibleContext;
}
}