Introduction · Sample Program Code · Display Properties
Text Display · User Interaction · Selection Properties
Highlight Properties · TopCharacter and TopRow Properties · Events
Property Listing · Example Programs
Text areas and text fields are standard Graphical User Interface (GUI) components that are common to virtually all windowing systems. Text areas are capable of displaying multiline text areas while text fields can display a single line of text. They are typically used within programs that require textual information from a user.
Text areas and text fields are included in the Java Development Kit (JDK), but their JClass BWT equivalents offer more control and flexibility than their AWT counterparts. JCTextArea
and JCTextField
both offer the programmer direct control over the following elements:
For the end user, JCTextArea
and JCTextField
both offer the following features:
JCTextComponent
is an abstract class which is the superclass for both JCTextArea
and JCTextField
, and functions in a similar manner to AWT's TextComponent
.
JCTextArea
and JCTextField
behave in the following way:
The LEFT and RIGHT cursor key move the "I" cursor within any text contained within a text area/field. Pressing the TAB key cycles through multiple text fields contained within an application.
When the scrollbar of a JCTextArea
has focus, hitting the
UP
or
DOWN
cursor keys (for a vertical scrollbar) or the
RIGHT
or
LEFT
cursor keys (for a horizontal scrollbar) scrolls the scrollbar in the direction of the cursor key. It also switches focus to the arrow button in the direction of the cursor. Pressing either the
ENTER
key or the SPACE BAR activates the arrow button (i.e. it is depressed), and it moves the scrollbar in the direction of the arrow button. Clicking
PAGE-UP
or
PAGE-DOWN
will scroll up or down by a page respectively. Clicking
HOME
or
END
will scroll to the beginning or end of the scrollable area respectively.
The following code fragment shows how both JCTextArea
and JCTextField
can be incorporated into a program:
package jclass.bwt.examples; import jclass.bwt.BWTEnum; import jclass.bwt.BWTUtil; import jclass.bwt.JCAlignerLayout; import jclass.bwt.JCLabel; import jclass.bwt.JCTextArea; import jclass.bwt.JCTextComponent; import jclass.bwt.JCTextCursorEvent; import jclass.bwt.JCTextCursorListener; import jclass.bwt.JCTextField; import jclass.bwt.JCTextEvent; import jclass.bwt.JCTextListener; import jclass.contrib.ContribFrame; import java.awt.*; /** * This example demonstrates the use of a JCTextField and JCTextArea. */ public class text extends java.applet.Applet implements JCTextListener, JCTextCursorListener { public void textCursorMoveBegin(JCTextCursorEvent ev) { JCTextComponent field = (JCTextComponent) ev.getSource(); if (field.getName().equals("phone")) { int new_pos = ev.getNewPosition(), old_pos = ev.getCurrentPosition(); if (new_pos == field.getNumChar()) return; char c = field.getText().charAt(new_pos); if (c == '-') { if (new_pos > old_pos) ev.setNewPosition(new_pos+1); else ev.setNewPosition(new_pos-1); } } } public void textCursorMoveEnd(JCTextCursorEvent ev) {} public void textValueChangeBegin(JCTextEvent ev) { JCTextComponent field = (JCTextComponent) ev.getSource(); if (field.getName().equals("phone")) { boolean allow = true; int text_len = ev.getText().length(); if (text_len > 1) allow = false; else if (field.getText().charAt(ev.getStartPosition()) == '-') ev.setText("-"); else if (text_len == 1) { char c = ev.getText().charAt(0); if (c != ' ' && !Character.isDigit(c)) allow = false; } ev.setAllowChange(allow); if (!allow) field.beep(); } } public void textValueChangeEnd(JCTextEvent ev) {} final static String PHONE = "905-555-1212"; public void init() { JCTextField f1, f2, f3; setBackground(Color.lightGray); setLayout(new JCAlignerLayout(2, 10, 10)); add(new JCLabel("Name:")); add(f1 = new JCTextField(System.getProperty("user.name"))); f1.setStringCase(BWTEnum.CASE_UPPER); add(new JCLabel("Password:")); add(f2 = new JCTextField("WHO KNOWS?")); f2.setEchoChar('*'); add(new JCLabel("Java Vendor:")); add(new JCTextField(System.getProperty("java.vendor"))); add(new JCLabel("Phone:")); add(f3 = new JCTextField(PHONE, null, "phone")); f3.setOverstrike(true); f3.setMaximumLength(PHONE.length()); f3.addTextListener(this); f3.addTextCursorListener(this); add(new JCLabel("Comments:")); JCTextArea area = new JCTextArea(); area.setScrollbarDisplay(BWTEnum.DISPLAY_VERTICAL_ONLY); add(area); } public static void main(String args[]) { ContribFrame frame = new ContribFrame("Text"); text t = new text(); t.init(); frame.add(t); frame.pack(); frame.show(); } }
This code produces the following results:
This sample code is incorporated into the example file text.class provided with JClass BWT. For information on how to run this program, see the " Example Programs " section at the end of this chapter.
The Columns
property sets the number of columns, effectively setting the width of a JCTextField
/JCTextArea
. Similarly, the Rows
property sets the number of rows for a JCTextArea
.
The PreferredSize
property returns the preferred size of this container. If the application has set the preferred size, it is returned. Otherwise the subclass' preferredWidth()
and/or preferredHeight()
method is called.
The MaximumLength
property is used to set the maximum number of characters that can be entered into a JCTextField
by a user (default: MAXINT
). If a user attempts to enter more characters in the field, the values are ignored and a bell is sounded. This value is ignored for values set programmatically.
The display of scrollbars within JCTextArea
can be set with ScrollbarDisplay
, which can take one of five values: DISPLAY_ALWAYS
(scrollbars are always displayed), DISPLAY_AS_NEEDED
(scrollbars are displayed as necessary), DISPLAY_VERTICAL_ONLY
(only the vertical scrollbar is displayed), DISPLAY_HORIZONTAL_ONLY
(only the horizontal scrollbar is displayed), or DISPLAY_NONE
(never display scrollbars). DISPLAY_ALWAYS
is the default setting for ScrollbarDisplay
.
There are a number of properties that handle the display of text within JCTextFields
and JCTextAreas
. It is possible to set the following features within these components:
It is also possible to set the display values for the selected text. This is discussed in the next section.
Text can be set in a JCTextField
/JCTextArea
by using the Text
property. Text takes a string of alphanumeric characters which are displayed within the specified JCTextField
/JCTextArea
.
The Alignment
property sets the position of the any text within a JCTextField
/JCTextArea
. Alignment
has three values: LEFT
(default), CENTER
, or RIGHT
.
In JCTextField
it is possible to set the case of the text that is entered by a user or set programmatically by using the StringCase
property. It takes one of three values: CASE_AS_IS
(no conversion is made), CASE_LOWER
(converts all text to lower case) and CASE_UPPER
(converts all text to upper case). The default value for StringCase
is CASE_AS_IS
.
The Background
and Foreground
properties can be used to set the color of the background and text/foreground elements of a JCTextField
/JCTextArea
. Foreground
sets the color of any alphanumeric characters contained within the text field.
The display of fonts within a JCTextField
/JCTextArea
is controlled by the Font
property. For a listing of available fonts, see
.
Most text fields and text areas are designed to accept user input. JCTextArea
and JCTextField
have a number of properties that enable the programmer more direct control over the type of textual information users can enter into a program containing JClass BWT components.
The Editable
property determines whether this component is editable, and the Traversable
property sets whether the component can accept focus (default: true
).
The CursorPosition
property sets the position of the cursor within a JCTextField
/JCTextArea
. The CaretPosition
property also sets the position of the cursor within a JCTextField
/JCTextArea
. It is included for JDK 1.1 compatibility. Both CursorPosition
and CaretPosition
work in conjunction with the ShowCursorPosition
property, which, if set to true
(default), displays the cursor position with a vertical I-beam.
The Multiline
property enables a user to break text into multiple lines within a JCTextArea
. The default value for Multiline
is true
.
The Overstrike
property inserts characters typed by the user into the current text. The default value of Overstrike
is false
.
The EchoChar
property of JCTextField
sets the echo character for a text field. Echo characters are useful in cases where user input should not be displayed (or "echoed") to the screen, as in the case of a password prompt. It takes the parameter c
, which sets the echo character, or 0
if no echo character is to be set.
There are several properties that control the display of selected text. SelectedBackground
property sets the background color of selected text (default: blue
), and SelectedForeground
sets the foreground color of selected text (default: the background color).
The SelectionStart
property is used to get the beginning position, and the SelectionEnd
property sets the selected text's end position.
The SelectionList
property sets a list of values used for multi-click. As the mouse is clicked in rapid succession, each click selects the next type in the list. Valid values are: SELECT_POSITION
(selects the current pointer position), SELECT_WORD
(selects the current word), SELECT_LINE
(selects the current line) and SELECT_ALL
(selects all the text).
In JCTextField
, there are properties available to set the color and thickness of the highlight which denote that a particular JCTextField
has focus.
The HighlightColor
property sets the color of the rectangle drawn when the component has focus (default: black
), and the HighlightThickness
property sets the thickness of the rectangle drawn when the component has focus (default: 2
).
The TopCharacter
property sets the position of the left-most character on the first line currently displayed. This position is the number of characters from the beginning of the text buffer. The first character position is 0
.
Similarly, the TopRow
property sets the top-most visible row.
A class can be notified before and after a JCTextField
's or JCTextArea
's value has changed by implementing the JCTextListener
interface and registering itself with the field via addTextListener
, as the following code demonstrates:
public interface JCTextListener { // Invoked before the field's value is changed. The event's values can be modified via its setXXX methods. public void textValueChangeBegin(JCTextEvent e); // Invoked after the field's value is changed. Any changes made to the event are ignored. public void textValueChangeEnd(JCTextEvent e); } public class JCTextEvent { // Returns the component where the event originated. public Object getSource() // Returns the event type: TEXT_VALUE_CHANGED. public int getId() // Gets the starting position of the text to modify. public int getStartPosition() // Sets the starting position of the text to modify. public void setStartPosition(int v) // Gets the ending position of the text to modify. public int getEndPosition() // Sets the ending position of the text to modify. public void setEndPosition(int v) // Gets the string to be inserted. public String getText() // Sets the string to be inserted. public void setText(String v) // Returns true if text is being deleted. public boolean isDeletion() // Determines whether the value change be allowed. public boolean getAllowChange() // Determines whether the value change be allowed (default: true). public void setAllowChange(boolean v) }
A class can be notified before and after the JCTextField
's or JCTextArea
's cursor has moved by implementing the JCTextCursorListener
interface and registering itself with the field via addTextCursorListener
:
public interface JCTextCursorListener { // Invoked before the field's cursor is moved. The event's values can be modified via its setXXX methods. public void textCursorMoveBegin(JCTextCursorEvent e); // Invoked after the field's cursor is moved. Any changes made to the event are ignored. public void textCursorMoveEnd(JCTextCursorEvent e); } public class JCTextCursorEvent { // Returns the component where the event originated. public Object getSource() // Returns the event type. public int getId() // Gets the current cursor position. public int getCurrentPosition() // Gets the new cursor position. public int getNewPosition() // Sets the new cursor position. public void setNewPosition(int v) // Determines whether the cursor movement should be allowed. public boolean getAllowMovement() // Determines whether the cursor movement should be allowed (default: true). public void setAllowMovement(boolean v) }
JCTextField
has an additional event. A class can be notified when the user presses the
ENTER
key in a JCTextField
by implementing the JCActionListener
interface and registering itself with the field via addActionListener
:
public interface JCActionListener { public void actionPerformed(JCActionEvent e); } public class JCActionEvent { // Returns the component where the event originated. public Object getSource() // Returns the event type: ACTION_PERFORMED. public int getId() }
The following summarizes the properties of JCTextComponent
, JCTextArea
and JCTextField
. Complete reference documentation is available online in standard
javadoc format in
jclass.bwt.JCTextComponent.html,
jclass.bwt.JCTextArea.html and
jclass.bwt.JCTextField.html.
Demonstration programs and example code containing JCTextArea
and JCTextField
come with JClass BWT. The examples can be viewed in applet form by launching index.html within the /jclass/bwt/examples directory. textarea.class
and textfield.class
can also be run as stand-alone Java applications from the command prompt by typing:
java jclass.bwt.examples.text