Working with Actions and Buttons in Java GUI Programming

A JButton can show an icon in addition to text, or instead of text, and icons are represented by the Icon interface.

Programming

Predicting What a Button Will Show

This article starts with a short program rather than a list of rules. Read the code as it would run, and pay attention to the moment the button first gets its icon. Your job at this point is only to notice what the program does. The vocabulary and the explanation come after you have seen the result.

java

import javax.swing.*;
import java.awt.*;
import java.awt.image.BufferedImage;

public class IconDemo {
    public static void main(String[] args) {
        BufferedImage picture = new BufferedImage(16, 16, BufferedImage.TYPE_INT_ARGB);
        Graphics2D g = picture.createGraphics();
        g.setColor(Color.BLUE);
        g.fillRect(0, 0, 16, 16);
        g.dispose();

        ImageIcon icon = new ImageIcon(picture);
        JButton button = new JButton("Save", icon);

        JFrame frame = new JFrame("Icon demo");
        frame.add(button);
        frame.pack();
        frame.setVisible(true);
    }
}

import javax.swing.*;
import java.awt.*;
import java.awt.image.BufferedImage;

public class IconDemo {
    public static void main(String[] args) {
        BufferedImage picture = new BufferedImage(16, 16, BufferedImage.TYPE_INT_ARGB);
        Graphics2D g = picture.createGraphics();
        g.setColor(Color.BLUE);
        g.fillRect(0, 0, 16, 16);
        g.dispose();

        ImageIcon icon = new ImageIcon(picture);
        JButton button = new JButton("Save", icon);

        JFrame frame = new JFrame("Icon demo");
        frame.add(button);
        frame.pack();
        frame.setVisible(true);
    }
}

Notes on the code

The BufferedImage holds the pixels of a small blue square.
ImageIcon wraps that picture so it can be used as an icon.
The constructor call hands the text and the icon to the button in one step.

What do you think happens?

Before reading on: when this program runs, will the button show only the blue square, only the text Save, or both?

Only the blue square
Only the text Save
Both the blue square and the text Save

Reveal answer

Answer:

Both the blue square and the text Save

The source describes a JButton constructor that takes both text and an icon, so the button displays the icon in addition to the text. The rest of this article explains where the picture comes from and how it reaches the button.

Following the Picture Through the Code

Keep track of which object holds the picture at each stage of the program. That object is the thread that connects the whole process. In the example, the picture starts life as a BufferedImage. The pixel-drawing lines fill that image with blue. Then a single ImageIcon is created from the BufferedImage, and the icon is handed to the button. The picture itself is converted into an icon only once, at the ImageIcon step.

How does pixel image data move from a BufferedImage through an ImageIcon and onto a JButton?

Worked example

Tracing the Icon Through Each Stage

Follow the object that holds the picture from the first line that creates it to the moment the button displays it.

1
Create the image
new BufferedImage(16, 16, ...) creates an empty picture that can hold pixels.
2
Draw the pixels
The Graphics2D object fills the rectangle with blue, so the BufferedImage now holds the blue square.
3
Wrap as an icon
new ImageIcon(picture) creates an Icon object that carries the picture. The picture is now usable as an icon.
4
Hand to the button
new JButton("Save", icon) gives the button both its text and its icon in one step.

Result

The button displays the blue square together with the text Save, which matches the prediction reveal in the opening section.

Text, Icon, or Both on a Button

A button in a graphical user interface does not have to show text. It can show a picture instead, or both. Icons are represented by the Icon interface. Icons are usually created as ImageIcon objects, so ImageIcon is the class most programs use to supply an icon to a button. The source also describes a JButton constructor that takes only an icon, which creates a button that has an icon and no text.

Definition

Icon is the interface that represents a small picture a component can display. ImageIcon is a class that implements the Icon interface and can be built from a BufferedImage.

Button setup	What the learner sees	Typical source route
Text only, such as new JButton("Save")	The text Save and no picture	Text-only constructor
Icon only, such as new JButton(icon)	The picture and no text	Constructor that takes just the icon
Text and icon, such as new JButton("Save", icon)	The picture together with the text	Constructor that takes text and icon

Three ways a JButton's content can be arranged, based on which constructor or value is used.

Three Routes to a Button's Icon

The source describes three routes by which a JButton can receive an icon. Each route attaches the same kind of ImageIcon object, but at a different point in the program. Choosing a route decides when the icon is attached and which object must be checked if the icon is missing.

Finding the Step Where the Display Goes Wrong

When an icon does not appear on a button, the first useful question is which route the icon took. The point where the displayed result stops matching your expectation is usually the step where the icon was attached, or the step where it was not. The flowchart below turns the source's checks into a sequence of questions you can follow.

At which step in the sequence of creating and assigning an icon does the button's displayed result stop matching what the code was meant to produce?

Read the flowchart as a diagnosis rather than a fixed recipe. Start from the route the icon took. Each route has one check tied to it: the icon must be the second constructor argument, setIcon() must be called on the button that is actually displayed, or putValue with Action.SMALL_ICON must happen before the button is built. A failed check tells you the step to repair.

Mistakes That Hide a Button's Icon

Common mistake
Passing the arguments to the constructor in the wrong order
What it looks like
```
new JButton(icon, "Save")
```
Why it fails
The constructor that takes text and an icon expects the text first and the icon second.
Do this instead
```
new JButton("Save", icon)
```
Common mistake
Calling setIcon() on a different button than the one displayed
What it looks like
A second button is created and given the icon, but the window shows the first button.
Why it fails
The icon is attached to an object that is not on screen, so the visible button never receives it.
Do this instead
Call setIcon() on the same JButton variable that is added to the frame.
Common mistake
Building the button from an Action before storing the icon
What it looks like
new JButton(saveAction) is called, and only afterward saveAction.putValue(Action.SMALL_ICON, icon) runs.
Why it fails
The source says the button takes its icon from Action.SMALL_ICON, so the value must already be present when the button is built.
Do this instead
Run putValue with Action.SMALL_ICON first, then construct the button from the Action.
Common mistake
Assuming an icon-only button still needs text, when the constructor that takes just the icon creates a button with no text

Checking Your Understanding of the Action Route

MEDIUM

A learner creates an Action, builds a JButton from that Action, and only then calls putValue(Action.SMALL_ICON, icon). The button shows the text but no icon. Identify the step that is out of order, explain why the displayed result departs from what was intended, and describe the corrected order of the statements.

Hints

Look at which statement stores the icon and which statement builds the button.
The source says the button takes its icon from the Action.SMALL_ICON value at the time it uses that Action.
Consider what the button can read when it is constructed.

Your attempt (not saved)

Key Takeaways

A JButton can show an icon in addition to text, or instead of text, and icons are represented by the Icon interface.
ImageIcon is the usual Icon implementation, and it can be built from a BufferedImage that holds a custom picture.
An icon can reach a button through the constructor that takes text and icon, through setIcon() after the button exists, or through an Action whose Action.SMALL_ICON value holds the icon.
When an icon is missing, trace which route it took and check the step that attaches it, since the point of failure is usually that step.