Previous | Next | Trail Map | Creating a User Interface | Using the JFC/Swing Packages

How to Use Labels

With the JLabel(in the API reference documentation) class, you can display unselectable text and images. Sometimes it's tempting to subclass JLabel to create interactive components that display simple a simple string/image. However, labels can't accept the keyboard focus, so they're unacceptable as the basis of interactive components. [PENDING: CHECK] Alternatives to subclassing JLabel include subclassing JButton or implementing a custom subclass of JComponent that performs its own drawing. [PENDING: link to custom component discussion.]

Here's a picture of an application that displays three labels. The window is divided into three rows of equal height; the label in each row is as wide as possible.

Try this:
  1. Compile and run the application. The source code is in LabelDemo.java, and the image is middle.gif.
    See Getting Started with Swing if you need help.
  2. Resize the window so you can see how the labels' contents are placed with the labels' drawing area.
    All the labels have the default vertical alignment -- the label contents are centered vertically in the label's drawing area. The top label, which contains both image and text, is specified to have horizontal center alignment. The second label, which contains just text, has the left alignment that is the default for text-only labels. The third label, which contains just an image, has horizontal center alignment, which is the default for image-only labels.

    [PENDING: Should I clarify X/Y alignment vs. label alignment? label bounds and layout problems?]

Below is the code from LabelDemo.java that creates the labels in the previous example. 

ImageIcon icon = new ImageIcon("images/middle.gif");
. . .
label1 = new JLabel("Image and Text",
		    icon,
		    JLabel.CENTER);
//Set the position of the text, relative to the icon:
label1.setVerticalTextPosition(JLabel.BOTTOM);
label1.setHorizontalTextPosition(JLabel.CENTER);

label2 = new JLabel("Text-Only Label");

label3 = new JLabel(icon);

//Add labels to the JPanel. 
add(label1);
add(label2);
add(label3);

The Label API

The following tables list the commonly used JLabel constructors and methods. Other methods you're likely to call are defined by the Component(in the API reference documentation) class. They include setFont and setForeground. [link to Component discussion.] The API for using labels falls into two categories:

Setting or Getting the Label's Contents
Method or Constructor Purpose
JLabel(Icon)
JLabel(Icon, int)
JLabel(String)
JLabel(String, Icon, int)
JLabel(String, int)
JLabel() 		Create a JLabel instance, initializing it to have the specified text/image/alignment. The int argument specifies the horizontal alignment of the label's contents within its drawing area. The horizontal alignment must be one of the following constants defined in the SwingConstants(in the API reference documentation) interface (which JLabel implements): LEFT, CENTER, or RIGHT.
void setText(String)
String getText() 		Set or get the text displayed by the label.
void setIcon(Icon)
Icon getIcon() 		Set or get the image displayed by the label.
void setDisplayedMnemonic(char)
char getDisplayedMnemonic() 		Set or get the letter that should look like a keyboard alternative. This is handy when a label describes a component (such as a text field) that has a keyboard alternative but can't display it.
void setDisabledIcon(Icon)
Icon getDisabledIcon() 		Set or get the image displayed by the label when it's disabled. If you don't specify a disabled image, then the look-and-feel creates one by manipulating the default image.

Fine Tuning the Label's Appearance
Method Purpose
void setHorizontalAlignment(int)
void setVerticalAlignment(int)
int getHorizontalAlignment()
int getVerticalAlignment() 		Set or get where in the label its contents should be placed. The SwingConstants(in the API reference documentation) interface defines three possible values for horizontal alignment: LEFT (the default for text-only labels), CENTER (the default for image-only labels), or RIGHT. For vertical alignment: TOP, CENTER (the default), and BOTTOM.
void setHorizontalTextPosition(int)
void setVerticalTextPosition(int)
int getHorizontalTextPosition()
int getVerticalTextPosition() 		Set or get where the button's text should be placed, relative to the button's image. The SwingConstants(in the API reference documentation) interface defines three possible values for horizontal position: LEFT, CENTER, and RIGHT (the default). For vertical position: TOP, CENTER (the default), and BOTTOM.
void setIconTextGap(int)
int getIconTextGap() 		Set or get the number of pixels between the label's text and its image.

Examples that Use Labels

The following table lists some of the many examples that use labels.

Example Where Described Notes
LabelDemo.java This page. Shows how to specify horizontal and vertical alignment, as well as aligning a label's text and image.
AlignmentDemo.java Fixing Alignment Problems Demonstrates a possible alignment problem when using a label in a vertical box layout. Shows how to solve the problem.
DialogDemo.java How to Use Dialogs Uses a changeable label to display instructions and provide feedback.
SplitPaneDemo.java How to Use Split Panes and How to Use Lists. Displays an image using a label inside of a scroll pane.
SliderDemo2.java How to Use Sliders Uses JLabel to provide labels for a slider.
TextFieldDemo.java How to Use Text Fields Has four rows, each containing a label and the text field it describes.

Previous | Next | Trail Map | Creating a User Interface | Using the JFC/Swing Packages