GUI programming with Swing

From this session on, everything we write has a window. The rest of the semester – the second and the third assignment included – uses Swing, the GUI toolkit that ships with the JDK. This session covers the three ideas every Swing program is made of: a tree of components, a layout manager per container that decides where things go, and listeners that react when the user does something. Then we look at how to keep the program's rules out of the window, so the GUI stays small and the logic stays testable.

The whole session in one breath: build a tree of panels, give each panel one simple layout, attach a listener to every control, and let each listener do three things only – read the input, call the model, redraw the screen from the model.

Why Swing

Swing is part of the JDK, so there is nothing to install and every IDE runs it out of the box. The interface is built in code, step by step, with no generated files or hidden magic – which makes it a good tool for learning how GUIs work. It is also not a toy: IntelliJ IDEA, Android Studio and NetBeans itself are Swing applications, and plenty of banking and enterprise desktop software is too.

The more important reason: the concepts carry over. The web, other desktop toolkits and mobile frameworks all use the same three ideas with different names.

A window is a tree of components

A Swing interface is a tree. The root is the window, a JFrame. Its content pane holds panels (JPanel), and the panels hold the controls: buttons, text fields, labels. The smallest useful program already shows the pattern – a frame, a panel, two components and a listener:

SwingUtilities.invokeLater(() -> {
    JFrame frame = new JFrame("Hello");
    frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);

    JLabel label = new JLabel("Hello!");
    JButton button = new JButton("Click me");
    button.addActionListener(e -> label.setText("Hello, Swing!"));

    JPanel panel = new JPanel();       // FlowLayout by default
    panel.add(label);
    panel.add(button);
    frame.add(panel);                  // goes into the content pane

    frame.pack();                      // size from the components
    frame.setLocationRelativeTo(null); // centre of the screen
    frame.setVisible(true);            // always last
});

The calculator from Session 1 comes back this week, rewritten. Its tree has three levels of panels (Fig. 1). The leaves are what the user sees; everything above them exists only to arrange the leaves.

component

Anything visible: JButton, JLabel, JTextField, JToggleButton, JList …

container

A component that holds others: JFrame, JPanel. Every container has a layout manager.

content pane

The part of a JFrame below the menu bar. frame.add(x) actually adds to it.

layout manager

The object that computes the position and size of a container’s children.

listener

An object whose method runs when an event happens, e.g. an ActionListener on a button.

Layout managers

In Swing you don't give components pixel positions. Each container has a layout manager that computes where its children go and how big they are – and computes it again when the window is resized, when the font is larger on another machine, or when a label's text gets longer. The course uses four of them (Fig. 2).

A real screen is never one layout. You get it by nesting panels, each with the simplest layout that fits its part. Draw the window first and mark the panels on the drawing, then build the tree from the drawing (Fig. 3).

JPanel labelPanel = new JPanel(new GridLayout(0, 1, GAP, GAP)); // 0 rows = as many as needed
labelPanel.add(new JLabel("A:"));
labelPanel.add(new JLabel("B:"));
labelPanel.add(new JLabel("Result:"));

JPanel fieldPanel = new JPanel(new GridLayout(0, 1, GAP, GAP));
fieldPanel.add(operand1);
fieldPanel.add(operand2);
fieldPanel.add(result);

JPanel numPanel = new JPanel(new BorderLayout(GAP, GAP));
numPanel.add(labelPanel, BorderLayout.WEST);   // only as wide as the labels
numPanel.add(fieldPanel, BorderLayout.CENTER); // the rest of the width

The five operation buttons are not written one by one. The program loops over the Operation enum and creates a button per value, each with the same listener class and a different parameter. Adding a new operation is one new line in the enum; the button appears by itself.

JPanel buttonPanel = new JPanel(new GridLayout(1, 0, GAP, GAP)); // one row
for (Operation operation : Operation.values()) {
    JButton button = new JButton(operation.getSymbol());
    button.addActionListener(new CalcActionListener(operation));
    buttonPanel.add(button);
}

public enum Operation {
    ADD("+", (a, b) -> a + b),
    SUBTRACT("-", (a, b) -> a - b),
    // … MULTIPLY, DIVIDE (throws on b == 0), POWER("^", Math::pow)

    private final String symbol;
    private final DoubleBinaryOperator function;
    // constructor, getSymbol(), apply(a, b) that rejects non-finite results
}

Events and listeners

A GUI program is event-driven. main builds the window and ends; from then on the program only does something when an event arrives – a click, a key press, a menu choice. You attach a listener to each event. For buttons and menu items that is an ActionListener, an interface with a single method, actionPerformed(ActionEvent e).

The same listener can be written in four ways, and the QWERTY example uses all four on purpose:

// 1. Named inner class – it has a parameter and several buttons share it
class QwertyListener implements ActionListener {
    private final String letter;
    QwertyListener(String letter) { this.letter = letter; }

    @Override
    public void actionPerformed(ActionEvent e) {
        model.type(letter);
        refresh();
    }
}
button.addActionListener(new QwertyListener(letter));

// 2. Anonymous class – the form you will meet in older code
exitItem.addActionListener(new ActionListener() {
    @Override
    public void actionPerformed(ActionEvent e) {
        System.exit(0);
    }
});

// 3. Lambda – short code used once
clearButton.addActionListener(e -> { model.clear(); refresh(); });

// 4. Method reference – an existing method with the same parameter
backButton.addActionListener(this::backspace);   // void backspace(ActionEvent e)

What do -> and :: mean? addActionListener wants an object with an actionPerformed method. Because ActionListener has only that one method (it is a functional interface), you can give just the method body: e -> display.setText(""), parameter on the left, code on the right. A method reference names an existing method instead of writing a body. this::backspace does not call backspace – it hands the method over, to be called later, when the button is pressed. Before the :: stands whose method it is: this, or any other object, e.g. model::clearHistory.

An inner class and a lambda can both use the fields of the enclosing object (model, display), so you don't have to pass everything in as a parameter. A lambda can only use local variables that are effectively final – this matters in loops, as the board example below shows.

One thread for the whole GUI

Swing is not thread-safe. Every component must be created and changed on one thread, the Event Dispatch Thread (EDT). Listeners run on it automatically. The only place you have to think about it is main, which runs on a different thread – so it hands the construction of the GUI over with SwingUtilities.invokeLater (Fig. 4).

The consequence for you: a listener must return quickly. While it runs, the window does not repaint and does not react – a Thread.sleep or a long loop in a listener freezes the whole window. For something that has to happen repeatedly (a clock, a countdown, an animation later in the semester) use javax.swing.Timer, which also runs its code on the EDT:

Timer timer = new Timer(1000, e -> secondsLabel.setText(String.valueOf(++seconds)));
timer.start();   // runs every second, on the EDT; timer.stop() ends it

Keep the rules out of the window

A GUI program does three things: it holds the state and applies the rules, it shows the state, and it reacts to the user. If all three live in one class, the class grows fast, every change touches everything, and nothing can be tested without clicking. So we split it. In the model–view (MV) structure:

• —the model is a plain Java class with no Swing in it – CalcModel computes and stores the result, Operation holds the rules of each operation;
• —the view builds the window, and its listeners call the model and then redraw the screen from the model with one method, refresh(). In MV the view is also the controller.

Follow one click through the calculator (Fig. 5). The listener only forwards: it turns text into numbers, lets the model compute, and asks refresh() to show the model.

@Override
public void actionPerformed(ActionEvent e) {
    try {
        double a = parseOperand(operand1, "A");   // text → number, may throw
        double b = parseOperand(operand2, "B");
        model.calculate(a, operation, b);          // the model computes
        refresh();                                 // the view shows the model
    } catch (NumberFormatException | ArithmeticException ex) {
        model.clearResult();                       // no stale result on screen
        refresh();
        JOptionPane.showMessageDialog(frame, ex.getMessage(), "Error",
                JOptionPane.ERROR_MESSAGE);
    }
}

Converting between text and numbers stays in the view: the model works with numbers, the screen works with strings. The parse also guards against input Double.parseDouble happily accepts but a calculator should not – "NaN" and "Infinity" – and accepts a decimal comma as well as a point. Division by zero doesn't throw for double (it gives infinity), so Operation checks it explicitly and throws an ArithmeticException – an exception from the model, reported by the view.

The QWERTY keyboard

The exercise of the session is a small on-screen keyboard: a display, the letters Q W E R T Y, a Back and a CLR button. Try it yourself first (Task 1 below); this section explains how the reference solution is structured (Fig. 6).

• —The letter buttons are created in a loop from an array and kept in a list, so refresh() can relabel them – exactly how a game board is built later.
• —The display is read-only (setEditable(false)) and not focusable, so key presses reach the buttons.
• —The text and the Caps state are not read back from the components (display.getText(), capsButton.isSelected()). The model owns them; the components only show them.

/** The whole screen, always redrawn from the model. */
private void refresh() {
    display.setText(model.getText());
    statusLabel.setText("Characters: " + model.getLength());
    capsButton.setSelected(model.isCapsLock());
    for (int i = 0; i < LETTERS.length; i++) {
        letterButtons.get(i).setText(model.applyCase(LETTERS[i]));
    }
}

Because every listener ends with refresh(), the display, the counter, the Caps button and the button labels can never disagree. Keeping four components in sync "by hand" in four listeners is where GUI bugs come from.

The solution also listens to the physical keyboard. The recommended way in Swing is a key binding: the window's InputMap maps a key to a name, the ActionMap maps the name to an action, and the action simply clicks the matching button. Unlike a KeyListener, this works whichever component has the focus.

private void bindKey(String keyStroke, AbstractButton button) {
    JRootPane root = frame.getRootPane();
    root.getInputMap(JComponent.WHEN_IN_FOCUSED_WINDOW)
            .put(KeyStroke.getKeyStroke(keyStroke), keyStroke);   // key → name
    root.getActionMap().put(keyStroke, new AbstractAction() {     // name → action
        @Override
        public void actionPerformed(ActionEvent e) {
            button.doClick();   // as if the button had been clicked
        }
    });
}

The same calculator in MVC

The calcMVC example is the calculator rebuilt the way you would structure a larger application, with a history list, a memory (MC, MR, M+, M−), errors shown in a status bar instead of a dialog, and JUnit tests for the model. It is a Maven project with three packages – one per layer (Fig. 7). The next session goes deeper into this separation; here it is worth seeing what changes compared to MV.

• —Model (calc.model): the rules and the state – history, memory. When it changes it notifies its subscribers, without knowing who they are.
• —View (calc.view): builds the window and shows only strings it is given. It doesn't hand out its buttons; the controller subscribes through onXxx(…) methods, so whether a function is a button, a menu item or a shortcut is the view's own business.
• —Controller (calc.controller): reads text from the view, parses it, calls the model, reports errors, and redraws the view when the model changes.

private final List<Runnable> listeners = new ArrayList<>();

public void addChangeListener(Runnable listener) {
    listeners.add(listener);
}

public Calculation calculate(double left, Operation operation, double right) {
    double result = operation.apply(left, right);       // the rules live here
    Calculation calculation = new Calculation(left, operation, right, result);
    history.add(0, calculation);
    fireChanged();                                      // "something changed"
    return calculation;
}

public CalculatorController(CalculatorModel model, CalculatorView view) {
    this.model = model;
    this.view = view;
    view.onOperation(this::calculate);             // user event → controller
    view.onEnterInOperand(() -> calculate(lastOperation));
    view.onClearHistory(model::clearHistory);      // straight to the model
    model.addChangeListener(this::render);         // model changed → view
    render();
}

The view's side of onOperation shows why Consumer<Operation> is the parameter type: every operation button gets the same handler, and the handler is told which operation was chosen.

public void onOperation(Consumer<Operation> handler) {
    operationButtons.forEach((operation, button)
            -> button.addActionListener(e -> handler.accept(operation)));
}

Where does the arithmetic go – the controller or the model? The model. The controller only mediates; the rules (what mod means, what division by zero does) are the core of the program. If they were in the controller, only clicking could test them, and a command-line version would have to rewrite them.

double left = parse(view.getOperandText(Operand.A));               // text → number
double right = parse(view.getOperandText(Operand.B));
Calculation calculation = model.calculate(left, operation, right);  // the model computes
view.showResult(format(calculation.result()));                     // number → text

Towards the second assignment

The second assignment is a two-player board game (or a logic game) in Swing. The shared requirements:

• —a user-friendly interface and an object-oriented solution – a layered architecture is not mandatory, but separating the model from the view is strongly recommended;
• —the board drawn with controls (a grid of buttons) or with graphics;
• —the window always fits the board, for every board size;
• —a New game menu with the board sizes the task specifies; the program detects the end of the game, announces the winner (or a draw) and starts a new game automatically;
• —documentation: task analysis, a UML class diagram of the program, and the event – listener pairs with a short description of each.

The fragments below are building blocks, not solutions. Board is your game's model – the rules – and you write it for your own task.

The structure to aim for: a model (Board, Field, Player …) that holds the board and the rules and imports nothing from Swing, so you can test it with JUnit as in Session 4; and a view (…GUI, BoardGUI) that builds the window, forwards events to the model and redraws the board from it.

Common mistakes

Practice

private static final String[] LETTERS = {"Q", "W", "E", "R", "T", "Y"};

JPanel keyPanel = new JPanel();          // FlowLayout
for (String letter : LETTERS) {
    JButton button = new JButton(letter);
    button.addActionListener(/* a listener that knows its letter */);
    keyPanel.add(button);
}

public class QwertyModel {
    private final StringBuilder text = new StringBuilder();

    public void type(String letter) { text.append(letter); }
    public void backspace() { /* delete the last char if there is one */ }
    public String getText() { return text.toString(); }
}

capsButton = new JToggleButton("Caps");
capsButton.addActionListener(e -> {
    model.toggleCapsLock();
    refresh();   // refresh() calls capsButton.setSelected(model.isCapsLock())
});

String[] rows = {"QWERTYUIOP", "ASDFGHJKL", "ZXCVBNM"};
JPanel keyboard = new JPanel(new GridLayout(0, 1));   // one row per panel
for (String row : rows) {
    JPanel rowPanel = new JPanel();
    // for each char of row: a button, added to rowPanel
    keyboard.add(rowPanel);
}

// in refresh(): the model decides, the view only reflects it
boolean full = model.getLength() >= QwertyModel.MAX_LENGTH;
for (JButton button : letterButtons) {
    button.setEnabled(!full);
}

MODULO("mod", (a, b) -> {
    // which check does DIVIDE already do that this one needs too?
    return a % b;
}),

// the view only exposes what the controller needs
public void showValue(int value) { valueLabel.setText("Value: " + value); }
public JButton getIncButton() { return incButton; }

// the controller connects both directions
view.getIncButton().addActionListener(e -> model.increment());
model.addChangeListener(() -> view.showValue(model.getValue()));

For more detail on layouts and listeners, the Oracle tutorial Creating a GUI With Swing is still the best reference – in particular Laying Out Components Within a Container and Writing Event Listeners.

Summary

• —A Swing window is a tree: JFrame → content pane → panels → controls. Every component has exactly one parent.
• —Each container has one layout manager. Complex screens come from nesting panels with simple layouts – sketch the screen first.
• —BorderLayout for the main split, FlowLayout for rows of buttons, GridLayout for boards and keypads, BoxLayout for forms.
• —Listeners can be named inner classes, anonymous classes, lambdas or method references; this::method hands a method over, it doesn’t call it.
• —Build the GUI with SwingUtilities.invokeLater and keep listeners fast – they run on the one Event Dispatch Thread.
• —Keep the rules in a Swing-free model. A listener reads input, calls the model and calls refresh(); refresh() redraws everything from the model.
• —MV is plenty for the assignments; MVC adds a controller and a model that notifies its listeners.