home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / awt / TextArea.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  13.2 KB  |  463 lines
  1. /*
  2.  * @(#)TextArea.java    1.40 98/03/18
  3.  *
  4.  * Copyright 1995-1997 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14. package java.awt;
  15.  
  16. import java.awt.peer.TextAreaPeer;
  17.  
  18. /**
  19.  * A <code>TextArea</code> object is a multi-line region 
  20.  * that displays text. It can be set to allow editing or 
  21.  * to be read-only.
  22.  * <p>
  23.  * The following image shows the appearance of a text area:
  24.  * <p>
  25.  * <img src="images-awt/TextArea-1.gif" 
  26.  * ALIGN=center HSPACE=10 VSPACE=7>
  27.  * <p>
  28.  * This text area could be created by the following line of code:
  29.  * <p>
  30.  * <hr><blockquote><pre>
  31.  * new TextArea("Hello", 5, 40);
  32.  * </pre></blockquote><hr>
  33.  * <p>
  34.  * @version    1.40, 03/18/98
  35.  * @author     Sami Shaio
  36.  * @since       JDK1.0
  37.  */
  38. public class TextArea extends TextComponent {
  39.  
  40.     /**
  41.      * The number of rows in the TextArea.
  42.      */
  43.     int    rows;
  44.  
  45.     /**
  46.      * The number of columns in the TextArea.
  47.      */
  48.     int    columns;
  49.  
  50.     private static final String base = "text";
  51.     private static int nameCounter = 0;
  52.  
  53.     /**
  54.      * Create and display both vertical and horizontal scrollbars.
  55.      * @since JDK1.1
  56.      */
  57.     public static final int SCROLLBARS_BOTH = 0;
  58.  
  59.     /**
  60.      * Create and display vertical scrollbar only.
  61.      * @since JDK1.1
  62.      */
  63.     public static final int SCROLLBARS_VERTICAL_ONLY = 1;
  64.  
  65.     /**
  66.      * Create and display horizontal scrollbar only.
  67.      * @since JDK1.1
  68.      */
  69.     public static final int SCROLLBARS_HORIZONTAL_ONLY = 2;
  70.  
  71.     /**
  72.      * Do not create or display any scrollbars for the text area.
  73.      * @since JDK1.1
  74.      */
  75.     public static final int SCROLLBARS_NONE = 3;
  76.  
  77.     /**
  78.      * Determines which scrollbars are created for the 
  79.      * text area.
  80.      */
  81.     private int scrollbarVisibility;
  82.  
  83.     /*
  84.      * JDK 1.1 serialVersionUID 
  85.      */
  86.      private static final long serialVersionUID = 3692302836626095722L;
  87.  
  88.     /**
  89.      * Initialize JNI field and method ids 
  90.      */
  91.     private static native void initIDs();
  92.  
  93.     static {
  94.         Toolkit.loadLibraries();
  95.     initIDs();
  96.     }
  97.  
  98.     /**
  99.      * Constructs a new text area.
  100.      * This text area is created with both vertical and
  101.      * horizontal scroll bars.
  102.      */
  103.     public TextArea() {
  104.     this("", 0, 0, SCROLLBARS_BOTH);
  105.     }
  106.  
  107.     /**
  108.      * Constructs a new text area with the specified text.
  109.      * This text area is created with both vertical and
  110.      * horizontal scroll bars.
  111.      * @param     text the text to be displayed. 
  112.      */
  113.     public TextArea(String text) {
  114.     this(text, 0, 0, SCROLLBARS_BOTH);
  115.     }
  116.  
  117.     /**
  118.      * Constructs a new empty TextArea with the specified number of
  119.      * rows and columns.
  120.      * @param rows the number of rows
  121.      * @param columns the number of columns
  122.      */
  123.     public TextArea(int rows, int columns) {
  124.     this("", rows, columns);
  125.     }
  126.  
  127.     /**
  128.      * Constructs a new text area with the specified text,
  129.      * and with the specified number of rows and columns.
  130.      * This text area is created with both vertical and
  131.      * horizontal scroll bars.
  132.      * @param     text      the text to be displayed.
  133.      * @param     rows      the number of rows.
  134.      * @param     columns   the number of columns.
  135.      */
  136.     public TextArea(String text, int rows, int columns) {
  137.         this(text, rows, columns, SCROLLBARS_BOTH);
  138.     }
  139.  
  140.     /**
  141.      * Constructs a new text area with the specified text, 
  142.      * and with the rows, columns, and scroll bar visibility
  143.      * as specified. 
  144.      * <p>
  145.      * The <code>TextArea</code> class defines several constants
  146.      * that can be supplied as values for the
  147.      * <code>scrollbars</code> argument: 
  148.      * <code>SCROLLBARS_BOTH</code>, 
  149.      * <code>SCROLLBARS_VERTICAL_ONLY</code>, 
  150.      * <code>SCROLLBARS_HORIZONTAL_ONLY</code>, 
  151.      * and <code>SCROLLBARS_NONE</code>. 
  152.      * @param     text the text to be displayed.
  153.      * @param     rows the number of rows.
  154.      * @param     columns the number of columns.
  155.      * @param     scrollbars a constant that determines what 
  156.      *                scrollbars are created to view the text area.
  157.      * @since     JDK1.1
  158.      */
  159.     public TextArea(String text, int rows, int columns, int scrollbars) {
  160.     super(text);
  161.     this.name = base + nameCounter++;
  162.     this.rows = rows;
  163.     this.columns = columns;
  164.     this.scrollbarVisibility = scrollbars;
  165.     }
  166.  
  167.     /**
  168.      * Creates the TextArea's peer.  The peer allows us to modify
  169.      * the appearance of the TextArea without changing any of its
  170.      * functionality.
  171.      */
  172.     public void addNotify() {
  173.     peer = getToolkit().createTextArea(this);
  174.     super.addNotify();
  175.     }
  176.  
  177.     /**
  178.      * Inserts the specified text at the specified position
  179.      * in this text area.
  180.      * @param      str the text to insert.
  181.      * @param      pos the position at which to insert.
  182.      * @see        java.awt.TextComponent#setText
  183.      * @see        java.awt.TextArea#replaceRange
  184.      * @see        java.awt.TextArea#append
  185.      * @since      JDK1.1
  186.      */
  187.     public synchronized void insert(String str, int pos) {
  188.         insertText(str, pos);
  189.     }
  190.  
  191.     /**
  192.      * @deprecated As of JDK version 1.1,
  193.      * replaced by <code>insert(String, int)</code>.
  194.      */
  195.     public void insertText(String str, int pos) {
  196.     TextAreaPeer peer = (TextAreaPeer)this.peer;
  197.     if (peer != null) {
  198.         peer.insertText(str, pos);
  199.     } else {
  200.         text = text.substring(0, pos) + str + text.substring(pos);
  201.     }
  202.     }
  203.  
  204.     /**
  205.      * Appends the given text to the text area's current text.
  206.      * @param     str the text to append.
  207.      * @see       java.awt.TextArea#insert
  208.      */
  209.     public synchronized void append(String str) {
  210.         appendText(str);
  211.     }
  212.  
  213.     /**
  214.      * @deprecated As of JDK version 1.1,
  215.      * replaced by <code>append(String)</code>.
  216.      */
  217.     public void appendText(String str) {
  218.     if (peer != null) {
  219.         insertText(str, getText().length());
  220.     } else {
  221.         text = text + str;
  222.     }
  223.     }
  224.  
  225.     /**
  226.      * Replaces text between the indicated start and end positions 
  227.      * with the specified replacement text.
  228.      * @param     str      the text to use as the replacement.
  229.      * @param     start    the start position.
  230.      * @param     end      the end position.
  231.      * @see       java.awt.TextArea#insert
  232.      * @since     JDK1.1
  233.      */
  234.     public synchronized void replaceRange(String str, int start, int end) {
  235.     replaceText(str, start, end);
  236.     }
  237.  
  238.     /**
  239.      * @deprecated As of JDK version 1.1,
  240.      * replaced by <code>replaceRange(String, int, int)</code>.
  241.      */
  242.     public void replaceText(String str, int start, int end) {
  243.     TextAreaPeer peer = (TextAreaPeer)this.peer;
  244.     if (peer != null) {
  245.         peer.replaceText(str, start, end);
  246.     } else {
  247.         text = text.substring(0, start) + str + text.substring(end);
  248.     }
  249.     }
  250.  
  251.     /**
  252.      * Gets the number of rows in the text area.
  253.      * @return    the number of rows in the text area.
  254.      * @see       java.awt.TextArea#setRows
  255.      * @see       java.awt.TextArea#getColumns
  256.      * @since     JDK1
  257.      */
  258.     public int getRows() {
  259.     return rows;
  260.     }
  261.  
  262.     /**
  263.      * Sets the number of rows for this text area.
  264.      * @param       rows   the number of rows.
  265.      * @see         java.awt.TextArea#getRows
  266.      * @see         java.awt.TextArea#setColumns
  267.      * @exception   IllegalArgumentException if the value supplied
  268.      *                  for <code>rows</code> is less than zero.
  269.      * @since       JDK1.1
  270.      */
  271.     public void setRows(int rows) {
  272.     int oldVal = this.rows;
  273.     if (rows < 0) {
  274.         throw new IllegalArgumentException("rows less than zero.");
  275.     }
  276.     if (rows != oldVal) {
  277.         this.rows = rows;
  278.         invalidate();
  279.     }
  280.     }
  281.  
  282.     /**
  283.      * Gets the number of columns in this text area.
  284.      * @return    the number of columns in the text area.
  285.      * @see       java.awt.TextArea#setColumns
  286.      * @see       java.awt.TextArea#getRows
  287.      */
  288.     public int getColumns() {
  289.     return columns;
  290.     }
  291.  
  292.     /**
  293.      * Sets the number of columns for this text area.
  294.      * @param       columns   the number of columns.
  295.      * @see         java.awt.TextArea#getColumns
  296.      * @see         java.awt.TextArea#setRows
  297.      * @exception   IllegalArgumentException if the value supplied
  298.      *                  for <code>columns</code> is less than zero.
  299.      * @since       JDK1.1
  300.      */
  301.     public void setColumns(int columns) {
  302.     int oldVal = this.columns;
  303.     if (columns < 0) {
  304.         throw new IllegalArgumentException("columns less than zero.");
  305.     }
  306.     if (columns != oldVal) {
  307.         this.columns = columns;
  308.         invalidate();
  309.     }
  310.     }
  311.  
  312.     /**
  313.      * Gets an enumerated value that indicates which scroll bars
  314.      * the text area uses. 
  315.      * <p>
  316.      * The <code>TextArea</code> class defines four integer constants 
  317.      * that are used to specify which scroll bars are available. 
  318.      * <code>TextArea</code> has one constructor that gives the 
  319.      * application discretion over scroll bars.
  320.      * @return     an integer that indicates which scroll bars are used.
  321.      * @see        java.awt.TextArea#SCROLLBARS_BOTH 
  322.      * @see        java.awt.TextArea#SCROLLBARS_VERTICAL_ONLY
  323.      * @see        java.awt.TextArea#SCROLLBARS_HORIZONTAL_ONLY
  324.      * @see        java.awt.TextArea#SCROLLBARS_NONE
  325.      * @see        java.awt.TextArea#TextArea(java.lang.String, int, int, int)
  326.      * @since      JDK1.1
  327.      */
  328.     public int getScrollbarVisibility() {
  329.         return scrollbarVisibility;
  330.     }
  331.  
  332.  
  333.     /**
  334.      * Determines the preferred size of a text area with the specified 
  335.      * number of rows and columns. 
  336.      * @param     rows   the number of rows.
  337.      * @param     cols   the number of columns.
  338.      * @return    the preferred dimensions required to display 
  339.      *                       the text area with the specified 
  340.      *                       number of rows and columns.
  341.      * @see       java.awt.Component#getPreferredSize
  342.      * @since     JDK1.1
  343.      */
  344.     public Dimension getPreferredSize(int rows, int columns) {
  345.         return preferredSize(rows, columns);
  346.     }
  347.  
  348.     /**
  349.      * @deprecated As of JDK version 1.1,
  350.      * replaced by <code>getPreferredSize(int, int)</code>.
  351.      */
  352.     public Dimension preferredSize(int rows, int columns) {
  353.     synchronized (Component.LOCK) {
  354.         TextAreaPeer peer = (TextAreaPeer)this.peer;
  355.         return (peer != null) ? 
  356.                peer.preferredSize(rows, columns) :
  357.                super.preferredSize();
  358.     }
  359.     }
  360.  
  361.     /**
  362.      * Determines the preferred size of this text area.  
  363.      * @return    the preferred dimensions needed for this text area.
  364.      * @see       java.awt.Component#getPreferredSize
  365.      * @since     JDK1.1
  366.      */
  367.     public Dimension getPreferredSize() {
  368.     return preferredSize();
  369.     }
  370.  
  371.     /**
  372.      * @deprecated As of JDK version 1.1,
  373.      * replaced by <code>getPreferredSize()</code>.
  374.      */
  375.     public Dimension preferredSize() {
  376.     synchronized (Component.LOCK) {
  377.         return ((rows > 0) && (columns > 0)) ? 
  378.                preferredSize(rows, columns) :
  379.                super.preferredSize();
  380.     }
  381.     }
  382.  
  383.     /**
  384.      * Determines the minimum size of a text area with the specified 
  385.      * number of rows and columns.
  386.      * @param     rows   the number of rows.
  387.      * @param     cols   the number of columns.
  388.      * @return    the minimum dimensions required to display 
  389.      *                       the text area with the specified 
  390.      *                       number of rows and columns.
  391.      * @see       java.awt.Component#getMinimumSize
  392.      * @since     JDK1.1
  393.      */
  394.     public Dimension getMinimumSize(int rows, int columns) {
  395.         return minimumSize(rows, columns);
  396.     }
  397.  
  398.     /**
  399.      * @deprecated As of JDK version 1.1,
  400.      * replaced by <code>getMinimumSize(int, int)</code>.
  401.      */
  402.     public Dimension minimumSize(int rows, int columns) {
  403.     synchronized (Component.LOCK) {
  404.         TextAreaPeer peer = (TextAreaPeer)this.peer;
  405.         return (peer != null) ? 
  406.                peer.minimumSize(rows, columns) :
  407.                super.minimumSize();
  408.     }
  409.     }
  410.  
  411.     /**
  412.      * Determines the minimum size of this text area. 
  413.      * @return    the preferred dimensions needed for this text area.
  414.      * @see       java.awt.Component#getPreferredSize
  415.      * @since     JDK1.1
  416.      */
  417.     public Dimension getMinimumSize() {
  418.     return minimumSize();
  419.     }
  420.  
  421.     /**
  422.      * @deprecated As of JDK version 1.1,
  423.      * replaced by <code>getMinimumSize()</code>.
  424.      */
  425.     public Dimension minimumSize() {
  426.     synchronized (Component.LOCK) {
  427.         return ((rows > 0) && (columns > 0)) ? 
  428.                minimumSize(rows, columns) :
  429.                super.minimumSize();
  430.     }
  431.     }
  432.  
  433.     /**
  434.      * Returns the parameter string representing the state of
  435.      * this text area. This string is useful for debugging.
  436.      * @return      the parameter string of this text area.
  437.      */
  438.     protected String paramString() {
  439.     String sbVisStr;
  440.     switch (scrollbarVisibility) {
  441.         case SCROLLBARS_BOTH:
  442.         sbVisStr = "both";
  443.         break;
  444.         case SCROLLBARS_VERTICAL_ONLY:
  445.         sbVisStr = "vertical-only";
  446.         break;
  447.         case SCROLLBARS_HORIZONTAL_ONLY:
  448.         sbVisStr = "horizontal-only";
  449.         break;
  450.         case SCROLLBARS_NONE:
  451.         sbVisStr = "none";
  452.         break;
  453.         default:
  454.         sbVisStr = "invalid display policy";
  455.     }
  456.       
  457.     return super.paramString() + ",rows=" + rows + 
  458.         ",columns=" + columns + 
  459.       ", scrollbarVisibility=" + sbVisStr;
  460.     }
  461.  
  462. }
  463.