Download the JDK
Search the Tutorials
Hide the TOC
Trail: Creating a GUI with JFC/Swing
Lesson: Using Swing Components
Section: How to Use Various Components
Using Swing Components
Using Top-Level Containers
The JComponent Class
Using Text Components
Text Component Features
The Text Component API
How to Use Various Components
How to Make Applets
How to Use Buttons, Check Boxes, and Radio Buttons
How to Use the ButtonGroup Component
How to Use Color Choosers
How to Use Combo Boxes
How to Make Dialogs
How to Use Editor Panes and Text Panes
How to Use File Choosers
How to Use Formatted Text Fields
How to Make Frames (Main Windows)
How to Use Internal Frames
How to Use Labels
How to Use Layered Panes
How to Use Lists
How to Use Menus
How to Use Panels
How to Use Password Fields
How to Use Progress Bars
How to Use Root Panes
How to Use Scroll Panes
How to Use Separators
How to Use Sliders
How to Use Spinners
How to Use Split Panes
How to Use Tabbed Panes
How to Use Tables
How to Use Text Areas
How to Use Text Fields
How to Use Tool Bars
How to Use Tool Tips
How to Use Trees
How to Use HTML in Swing Components
How to Use Models
How to Use Icons
How to Use Borders
Solving Common Component Problems
Home Page > Creating a GUI with JFC/Swing > Using Swing Components
How to Use Text Fields

> A text field is a basic text control that enables the user to type a small amount of text. When the user indicates that text entry is complete (usually by pressing Enter), the text field fires an action event. If you need to obtain more than one line of input from the user, use a text area.

> The Swing API provides several classes for components that are either varieties of text fields or that include text fields.

> `JTextField` | What this section covers: basic text fields.
> `JFormattedTextField` | A `JTextField` subclass that allows you to specify the legal set of characters that the user can enter. See How to Use Formatted Text Fields.
> `JPasswordField` | A `JTextField` subclass that does not show the characters that the user types. See How to Use Password Fields.
> `JComboBox` | Can be edited, and provides a menu of strings to choose from. See How to Use Combo Boxes.
> `JSpinner` | Combines a formatted text field with a couple of small buttons that enables the user to choose the previous or next available value. See How to Use Spinners.

> The following example displays a basic text field and a text area. The text field is editable. The text area is not editable. When the user presses Enter in the text field, the program copies the text field's contents to the text area, and then selects all the text in the text field.

> Click the Launch button to run TextDemo using Java™ Web Start (download JDK 6). Alternatively, to compile and run the example yourself, consult the example index.

> You can find the entire code for this program in `TextDemo.java`. The following code creates and sets up the text field:

> >     textField = new JTextField(20);

> The integer argument passed to the `JTextField` constructor, `20` in the example, indicates the number of columns in the field. This number is used along with metrics provided by the field's current font to calculate the field's preferred width. It does not limit the number of characters the user can enter. To do that, you can either use a formatted text field or a document listener, as described in Text Component Features.

> > Note: We encourage you to specify the number of columns for each text field. If you do not specify the number of columns or a preferred size, then the field's preferred size changes whenever the text changes, which can result in unwanted layout updates.

> The next line of code registers a `TextDemo` object as an action listener for the text field.

> >     textField.addActionListener(this);

> The `actionPerformed` method handles action events from the text field:

> >     private final static String newline = "\n";
> >     ...
> >     public void actionPerformed(ActionEvent evt) {
> >         String text = textField.getText();
> >         textArea.append(text + newline);
> >         textField.selectAll();
> >     }

> Notice the use of `JTextField`'s `getText` method to retrieve the text currently contained by the text field. The text returned by this method does not include a newline character for the Enter key that fired the action event.

> You have seen how a basic text field can be used. Because the `JTextField` class inherits from the `JTextComponent` class, text fields are very flexible and can be customized almost any way you like. For example, you can add a document listener or a document filter to be notified when the text changes, and in the filter case you can modify the text field accordingly. Information on text components can be found in Text Component Features. Before customizing a `JTextField`, however, make sure that one of the other components based on text fields will not do the job for you.

> Often text fields are paired with labels that describe the text fields. See Examples That Use Text Fields for pointers on creating these pairs.

### Another Example: TextFieldDemo

> The `TextFieldDemo` example introduces a text field and a text area. You can find the entire code for this program in `TextFieldDemo.java`.

> As you type characters in the text field the program searches for the typed text in the text area. If the entry is found it gets highlighted. If the program fails to find the entry then the text field's background becomes pink. A status bar below the text area displays a message whether text is found or not. The Escape key is used to start a new search or to finish the current one. Here is a picture of the `TextFieldDemo` application.

> Click the Launch button ro run TextFieldDemo using Java™ Web Start (download JDK 6). Alternatively, to compile and run the example yourself, consult the example index.

> To highlight text, this example uses a highlighter and a painter. The code below creates and sets up the highlighter and the painter for the text area.

> >     final Highlighter hilit;
> >     final Highlighter.HighlightPainter painter;
> >     ...
> >     hilit = new DefaultHighlighter();
> >     painter = new DefaultHighlighter.DefaultHighlightPainter(HILIT_COLOR);
> >     textArea.setHighlighter(hilit);

> This code adds a document listener to the text field's document.

> >     entry.getDocument().addDocumentListener(this);

> Document listener's `insertUpdate` and `removeUpdate` methods call the `search` method, which not only performs a search in the text area but also handles highlighting. The following code highlights the found text, sets the caret to the end of the found match, sets the default background for the text field, and displays a message in the status bar.

> >     hilit.addHighlight(index, end, painter);
> >     textArea.setCaretPosition(end);
> >     entry.setBackground(entryBg);
> >     message("'" + s + "' found. Press ESC to end search");

> The status bar is a `JLabel` object. The code below shows how the `message` method is implemented.

> >     private JLabel status;
> >     ...
> >     void message(String msg) {
> >         status.setText(msg);
> >     }

> If there is no match in the text area, the following code changes the text field's background to pink and displays a proper information message.

> >     entry.setBackground(ERROR_COLOR);
> >     message("'" + s + "' not found. Press ESC to start a new search");

> The `CancelAction` class is responsible for handling the Escape key as follows.

> >        class CancelAction extends AbstractAction {
> >            public void actionPerformed(ActionEvent ev) {
> >                    hilit.removeAllHighlights();
> >                    entry.setText("");
> >                    entry.setBackground(entryBg);
> >                }
> >        }

### The Text Field API

> The following tables list the commonly used `JTextField` constructors and methods. Other methods you are likely to call are defined in the `JTextComponent` class. Refer to The Text Component API.

> You might also invoke methods on a text field inherited from the text field's other ancestors, such as `setPreferredSize`, `setForeground`, `setBackground`, `setFont`, and so on. See The JComponent Class for tables of commonly used inherited methods.

> The API for using text fields falls into these categories:

> - Setting or Obtaining the Field's Contents
> - Fine Tuning the Field's Appearance
> - Implementing the Field's Functionality

> Setting or Obtaining the Field's Contents
> Method or Constructor | Purpose
> --- | ---
> JTextField() JTextField(String) JTextField(String, int) JTextField(int) | Creates a text field. When present, the `int` argument specifies the desired width in columns. The `String` argument contains the field's initial text.
> void setText(String) String getText() (defined in `JTextComponent`) | Sets or obtains the text displayed by the text field.

> Fine Tuning the Field's Appearance
> Method | Purpose
> --- | ---
> void setEditable(boolean) boolean isEditable() (defined in `JTextComponent`) | Sets or indicates whether the user can edit the text in the text field.
> void setColumns(int); int getColumns() | Sets or obtains the number of columns displayed by the text field. This is really just a hint for computing the field's preferred width.
> void setHorizontalAlignment(int); int getHorizontalAlignment() | Sets or obtains how the text is aligned horizontally within its area. You can use `JTextField.LEADING`, `JTextField.CENTER`, and `JTextField.TRAILING` for arguments.

> Implementing the Field's Functionality
> Method | Purpose
> --- | ---
> void addActionListener(ActionListener) void removeActionListener(ActionListener) | Adds or removes an action listener.
> void selectAll() (defined in `JTextComponent`) | Selects all characters in the text field.

### Examples That Use Text Fields

> This table shows a few of the examples that use text fields and points to where those examples are described. For examples of code that are similar among all varieties of text fields such as dealing with layout, look at the example lists for related components such as formatted text fields and spinners.

> Example | Where Described | Notes
> --- | --- | ---
> TextDemo | This section | An application that uses a basic text field with an action listener.
> TextFieldDemo | This section | An application that uses a text field and a text area. A search is made in the text area to find an entry from the text field.
> DialogDemo | How to Make Dialogs | `CustomDialog.java` includes a text field whose value is checked. You can bring up the dialog by clicking the More Dialogs tab, selecting the Input-validating dialog option, and then clicking the Show it! button.

> TextSamplerDemo

> Using Text Components

> Lays out label-text field pairs using a `GridBagLayout` and a convenience method:

>     addLabelTextRows(JLabel[] labels,
>     		 JTextField[] textFields,
>     		 GridBagLayout gridbag,
>     		 Container container)

> TextInputDemo

> How to Use Formatted Text Fields

> Lays out label-text field pairs using a `SpringLayout` and a `SpringUtilities` convenience method:

>     makeCompactGrid(Container parent,
>                     int rows, int cols,
>                     int initialX, int initialY,
>                     int xPad, int yPad)

Previous page: How to Use Text Areas
Next page: How to Use Tool Bars