Handling User Input in Swing Components

Imagine a form with two entry boxes. You expect the cursor to be waiting in the second box, but the user types and nothing appears there, or the text sits jammed against the border of the box. Problems like these almost always come from a small number of calls on the text component itself. This article works through those calls in the order a program would make them, so you can predict what each call changes and find the exact point where a result stops matching your expectation.

Keep one question in mind as you read: at which line does the component's state stop matching what you expected? Each section below adds one piece of that picture, and the final trace puts them together.

JTextField and JTextArea are both components that hold text the user can edit. A JTextField holds a single line of text. A JTextArea can hold multiple lines. Both classes are subclasses of an abstract class named JTextComponent, and that parent class defines the properties they have in common. Because the shared behavior lives in one place, the methods you learn for one text component apply to the other as well.

The diagram shows the relationship that matters for this article. Methods such as setText() and getText() are shared through the parent. Constructors are different: each subclass declares its own constructors, and those constructors take parameters that suit that subclass. A JTextField is described by a number of characters, while a JTextArea is described by rows and columns. Keep this split in mind when you choose a constructor.

Two methods handle the contents of a text component. The setText() method takes a String parameter and changes the text that is displayed in the component. The getText() method takes no parameters and returns the contents as a String. Calling setText() replaces what is shown, and calling getText() later returns whatever the component holds at that moment.

The setEditable() method controls whether the user can change the text. Calling setEditable(false) makes the component read-only, so the user can still read the text it contains but cannot edit it. Calling setEditable(true) makes it editable again. The method only controls the user's ability to edit. Your program can still change the text with setText() while the component is read-only.

The rows parameter specifies how many lines of text should be visible in the text area. It determines the preferred height of the text area, just as columns determines the preferred width of a text field. The text area can still hold more lines than are visible, because the user can scroll to reveal lines that are not currently on screen. So rows describes what is visible, not the total amount of text the component can contain. The same reasoning applies to columns for a text field.

A JTextArea is commonly placed in the CENTER position of a BorderLayout. In that position it expands to fill all the space available in the center area of the container. Specifying rows and columns is then less useful, because the layout decides the size. This is a practical difference between a text area in a fixed-size window and one placed in a resizable layout.

A text component accepts typing only when it has the input focus. The user can give a text component the input focus by clicking it with the mouse. Sometimes the program should move focus itself. For instance, when the program finds an error in what the user entered, it can give focus to the field that holds the error so the user sees where the problem is and can start typing the correction right away.

The program requests focus by calling requestFocusInWindow() on the text component. This is the single call that moves focus to a text field programmatically. If the text component does not appear to receive keystrokes, check whether this request was made, and whether it was made on the component you intended, before assuming the component itself is broken.

By default, there is no space between the text in a text component and the edge of the component. This usually does not look very good. The setMargin() method adds blank space between the edge of the component and its text. The method takes a parameter of type java.awt.Insets. An Insets object holds four integer values that specify the margins on the top, left, bottom, and right edges of the component, in that order.

In this example the same margin of 5 is used on all four sides, which gives a uniform gap around the text. Because each side is a separate argument, you can also make the gaps unequal. The margin changes only the space inside the component's edge. It does not change what the text says or whether the component is editable.

Now follow the calls in the order a program makes them. The sequence below mixes program calls, the window appearing, and a user keystroke. Read it from top to bottom and ask at each step whether the field's state still matches what the code requested.

Walk the trace step by step. Step 1 makes the field read-only, which blocks typing but not later program changes. Step 2 replaces the displayed text, and that still succeeds because the program is the caller. Step 3 asks for focus, but the window is not yet on screen at that point, because step 4 comes after it. Step 5 is where the user's keystroke arrives. If the typed text does not land where the code seemed to point, step 3 is the first place to check: the focus request was made before the window existed on screen, and you should confirm the request reached the component you intended.

JTextField and JTextArea share their behavior through the abstract class JTextComponent, so setText(), getText(), and setEditable() work the same way on both.