How to Use Borders

Every JComponent can have one or more borders. Borders are incredibly useful objects that, while not themselves components, know how to draw the edges of Swing components. Borders are useful not only for drawing lines and fancy edges, but also for providing titles and empty space around components.
To put a border around a JComponent, you use its setBorder method. You can use the BorderFactory class to create most of the borders that Swing provides. Here is an example of code that creates a bordered container:
JPanel pane = new JPanel();
pane.setBorder(BorderFactory.createLineBorder(Color.black));
Here's a picture of the container, which contains a label component. The black line drawn by the border marks the edge of the container.
The rest of this page discusses the following topics:

The BorderDemo Example
Using the borders provided by Swing
Adding a border to a bordered Swing component
Creating custom borders
The Border API
Examples of Using Borders

The BorderDemo example

The following pictures show an application called BorderDemo that displays the borders Swing provides. The code for creating these borders is discussed in the next section. The first picture shows some simple borders:
The next picture shows some matte borders. When creating a matte border, you specify how many pixels it occupies at the top, left, bottom, and right of a component. You then specify either a color or an icon for the matte border to draw. You need to be careful when choosing the icon and determining your component's size; otherwise, the icon might get chopped off or have mismatch at the component's corners.
The next picture shows titled borders. Using a titled border, you can convert any border into one that displays a text description. If you don't specify a border, then a look-and-feel-specific border is used. For example, the default titled border in the Java look and feel uses a gray line, and the default titled border in the Windows look and feel uses an etched border. [PENDING: check] By default, the title straddles the upper left of the border, as shown at the top of the following figure.
The next picture shows compound borders. With compound borders, you can combine any two borders, which can themselves be compound borders.

Using the Borders Provided by Swing
The code that follows shows how to create and set the borders you saw in the preceding figures. You can find the program's code in BorderDemo.java.
//Keep references to the next few borders, for use in titles
//and compound borders.
Border blackline, etched, raisedbevel, loweredbevel, empty;

blackline = BorderFactory.createLineBorder(Color.black);
etched = BorderFactory.createEtchedBorder();
raisedbevel = BorderFactory.createRaisedBevelBorder();
loweredbevel = BorderFactory.createLoweredBevelBorder();
empty = BorderFactory.createEmptyBorder();

//Simple borders
jComp2.setBorder(blackline);
jComp3.setBorder(raisedbevel);
jComp4.setBorder(loweredbevel);
jComp5.setBorder(empty);

//Matte borders
ImageIcon icon = new ImageIcon("images/left.gif"); //20x22
jComp6.setBorder(BorderFactory.createMatteBorder(-1, -1, -1, -1, icon));
jComp7.setBorder(BorderFactory.createMatteBorder(1, 5, 1, 1, Color.red));
jComp8.setBorder(BorderFactory.createMatteBorder(0, 20, 0, 0, icon));

//Titled borders
TitledBorder title1, title2, title3, title4, title5;
title1 = BorderFactory.createTitledBorder("title");
jComp9.setBorder(title1);

title2 = BorderFactory.createTitledBorder(
		       blackline, "title");
title2.setTitleJustification(TitledBorder.CENTER);
jComp10.setBorder(title2);

title3 = BorderFactory.createTitledBorder(
		       etched, "title");
title3.setTitleJustification(TitledBorder.RIGHT);
jComp11.setBorder(title3);

title4 = BorderFactory.createTitledBorder(
		       loweredbevel, "title");
title4.setTitlePosition(TitledBorder.ABOVE_TOP);
jComp12.setBorder(title4);

title5 = BorderFactory.createTitledBorder(
		       empty, "title");
title5.setTitlePosition(TitledBorder.BOTTOM);
jComp13.setBorder(title5);

//Compound borders
Border compound1, compound2, compound3;
Border redline = BorderFactory.createLineBorder(Color.red);

//This creates a nice frame.
compound1 = BorderFactory.createCompoundBorder(
			  raisedbevel, loweredbevel);
jComp14.setBorder(compound1);

//Add a red outline to the frame.
compound2 = BorderFactory.createCompoundBorder(
			  redline, compound1);
jComp15.setBorder(compound2);

//Add a title to the red-outlined frame.
compound3 = BorderFactory.createTitledBorder(
			  compound2, "title",
			  TitledBorder.CENTER,
			  TitledBorder.BELOW_BOTTOM);
jComp16.setBorder(compound3);
As you probably noticed, the code uses the BorderFactory class to create each border. [PENDING: The only Swing border not supported by BorderFactory is SoftBevelBorder. Why is that? Should I demonstrate SoftBevelBorder?] The BorderFactory class, which is in the javax.swing package, returns objects that implement the Border interface.
The Border interface, as well as its Swing-provided implementations, is in the javax.swing.border package. You often don't need to directly use anything in the border package, except when specifying constants that are specific to a particular border class or when referring to the Border type.
Creating Custom Borders

If BorderFactory doesn't offer you enough control over a border's form, then you might need to directly use the API in the border package -- or even define your own border. In addition to containing the Border interface, the border package contains the classes that implement the borders you've already seen: LineBorder, EtchedBorder, BevelBorder, EmptyBorder, MatteBorder, TitledBorder, and CompoundBorder. The border package also contains a class named SoftBevelBorder, which produces a result similar to BevelBorder [PENDING: show example of SoftBevelBorder or take it out].
If none of the Swing borders is suitable, you can implement your own border. Generally, you do this by creating a subclass of the AbstractBorder class. In your subclass, you must implement at least one constructor and the following two methods:

paintBorder, which contains the drawing code that a JComponent executes to draw the border.
getBorderInsets, which specifies the amount of space the border needs to draw itself.
In addition, if your border is opaque, you can decrease component drawing time by overriding the border's setOpaque method so that it returns true. For examples of implementing borders, see the source code for the classes in the javax.swing.border package.

Adding a Border to a Bordered Swing Component
Many of the ready-to-use Swing components use borders to draw the outline of the component. If you want to draw an additional border around an already bordered component -- to provide some extra space above a progress bar, for example -- then you need to add the new border to the existing border. Here's an example of adding to an existing border:
aJComponent.setBorder(
    BorderFactory.createCompoundBorder(
                    BorderFactory.createEmptyBorder(20,0,0,0),
                    aJComponent.getBorder())
);
The new border, returned by createEmptyBorder, adds 20 pixels of empty space above any component that uses it. To combine the new border with the existing border (which is returned by getBorder), the code uses the createCompoundBorder method.
The Border API

The following tables list the commonly used border methods. The API for using borders falls into two categories:

Creating a Border with BorderFactory
Setting or Getting a Component's Border

Creating a Border with BorderFactory
Method Purpose
Border createLineBorder(Color) Border createLineBorder(Color, int) Create a line border. The first argument is a java.awt.Color object that specifies the color of the line. The optional second argument specifies the width in pixels of the line.
Border createEtchedBorder() Border createEtchedBorder(Color, Color) Create an etched border. The optional arguments specify the highlight and shadow colors to be used.
Border createLoweredBevelBorder() Create a border that gives the illusion of the component being lower than the surrounding area.

Border createRaisedBevelBorder() Create a border that gives the illusion of the component being higher than the surrounding area.
Border createBevelBorder(int, Color, Color) Border createBevelBorder(int, Color, Color, Color, Color) Create a raised or lowered beveled border, specifying the colors to use. The integer argument can be either RAISED or LOWERED (constants defined in BevelBorder). With the three-argument constructor, you specify the highlight and shadow colors, With the four-argument constructor, you specify the outer highlight, inner highlight, outer shadow, and inner shadow colors, in that order.
Border createEmptyBorder() Border createEmptyBorder(int, int, int, int) Create an invisible border. If you specify no arguments, then the border takes no space, which is useful when creating a titled border with no visible boundary. The optional arguments specify the number of pixels that the border occupies at the top, left, bottom, and right (in that order) of whatever component uses it.
MatteBorder createMatteBorder(int, int, int, int, Color) MatteBorder createMatteBorder(int, int, int, int, Icon) Create a matte border. The integer arguments specify the number of pixels that the border occupies at the top, left, bottom, and right (in that order) of whatever component uses it. The Color argument specifies the color which with the border should fill its area. The Icon argument specifies the icon which with the border should tile its area.
TitledBorder createTitledBorder(String) TitledBorder createTitledBorder(Border) TitledBorder createTitledBorder(Border, String) TitledBorder createTitledBorder(Border, String, int, int) TitledBorder createTitledBorder(Border, String, int, int, Font) TitledBorder createTitledBorder(Border, String, int, int, Font, Color) Create a titled border. The string argument specifies the title to be displayed. The optional font and color arguments specify the font and color to be used for the title's text. The border argument specifies the border that should be displayed along with the title. If no border is specified, then a look-and-feel-specific default border is used.
By default, the title straddles the top of its companion border and is left-justified. The optional integer arguments specify the title's position and justification, in that order. TitledBorder defines these possible positions: ABOVE_TOP. TOP (the default), BELOW_TOP, ABOVE_BOTTOM, BOTTOM, BELOW_BOTTOM. You can specify the justification as LEFT (the default), CENTER, or RIGHT.
CompoundBorder createCompoundBorder(Border, Border) Combine two borders into one. The first argument specifies the outer border; the second, the inner border.

Setting or Getting a Component's Border
Method Purpose
void setBorder(Border) Border getBorder() Set or get the border of the receiving JComponent.
void setBorderPainted(boolean) boolean isBorderPainted()
(in AbstractButton, JMenuBar, JPopupMenu, JProgressBar, and JToolBar) Set or get whether the border of the component should be painted.

Creating a Border with `BorderFactory`
Method	Purpose
`Border createLineBorder(Color) Border createLineBorder(Color, int)`	Create a line border. The first argument is a `java.awt.Color` object that specifies the color of the line. The optional second argument specifies the width in pixels of the line.
`Border createEtchedBorder() Border createEtchedBorder(Color, Color)`	Create an etched border. The optional arguments specify the highlight and shadow colors to be used.
`Border createLoweredBevelBorder()`	Create a border that gives the illusion of the component being lower than the surrounding area.
`Border createRaisedBevelBorder()`	Create a border that gives the illusion of the component being higher than the surrounding area.
`Border createBevelBorder(int, Color, Color) Border createBevelBorder(int, Color, Color, Color, Color)`	Create a raised or lowered beveled border, specifying the colors to use. The integer argument can be either `RAISED` or `LOWERED` (constants defined in `BevelBorder`). With the three-argument constructor, you specify the highlight and shadow colors, With the four-argument constructor, you specify the outer highlight, inner highlight, outer shadow, and inner shadow colors, in that order.
`Border createEmptyBorder() Border createEmptyBorder(int, int, int, int)`	Create an invisible border. If you specify no arguments, then the border takes no space, which is useful when creating a titled border with no visible boundary. The optional arguments specify the number of pixels that the border occupies at the top, left, bottom, and right (in that order) of whatever component uses it.
`MatteBorder createMatteBorder(int, int, int, int, Color) MatteBorder createMatteBorder(int, int, int, int, Icon)`	Create a matte border. The integer arguments specify the number of pixels that the border occupies at the top, left, bottom, and right (in that order) of whatever component uses it. The Color argument specifies the color which with the border should fill its area. The Icon argument specifies the icon which with the border should tile its area.
`TitledBorder createTitledBorder(String) TitledBorder createTitledBorder(Border) TitledBorder createTitledBorder(Border, String) TitledBorder createTitledBorder(Border, String, int, int) TitledBorder createTitledBorder(Border, String, int, int, Font) TitledBorder createTitledBorder(Border, String, int, int, Font, Color)`	Create a titled border. The string argument specifies the title to be displayed. The optional font and color arguments specify the font and color to be used for the title's text. The border argument specifies the border that should be displayed along with the title. If no border is specified, then a look-and-feel-specific default border is used. By default, the title straddles the top of its companion border and is left-justified. The optional integer arguments specify the title's position and justification, in that order. `TitledBorder` defines these possible positions: `ABOVE_TOP`. `TOP` (the default), `BELOW_TOP`, `ABOVE_BOTTOM`, `BOTTOM`, `BELOW_BOTTOM`. You can specify the justification as `LEFT` (the default), `CENTER`, or `RIGHT`.
`CompoundBorder createCompoundBorder(Border, Border)`	Combine two borders into one. The first argument specifies the outer border; the second, the inner border.

Setting or Getting a Component's Border
Method	Purpose
`void setBorder(Border) Border getBorder()`	Set or get the border of the receiving `JComponent`.
`void setBorderPainted(boolean) boolean isBorderPainted()` (in `AbstractButton`, `JMenuBar`, `JPopupMenu`, `JProgressBar`, and `JToolBar`)	Set or get whether the border of the component should be painted.

Examples that Use Borders

Many examples in this lesson use borders. The following table lists a few interesting cases.

Example Where Described Notes
BorderDemo.java This page. Shows an example of each type of border that BorderFactory can create. Also uses an empty border to add breathing space between each pane and its contents.
AlignmentDemo.java How to Use BoxLayout Uses titled borders.
BoxLayoutDemo.java How to Use BoxLayout Uses a red line to show where the edge of a container is, so that you can see how the extra space in a box layout is distributed.
ComboBoxDemo.java How to Use Combo Boxes Uses a compound border to combine a line border with an empty border. The empty border provides space between the line and the component's innards.

Example	Where Described	Notes
`BorderDemo.java`	This page.	Shows an example of each type of border that `BorderFactory` can create. Also uses an empty border to add breathing space between each pane and its contents.
`AlignmentDemo.java`	How to Use BoxLayout	Uses titled borders.
`BoxLayoutDemo.java`	How to Use BoxLayout	Uses a red line to show where the edge of a container is, so that you can see how the extra space in a box layout is distributed.
`ComboBoxDemo.java`	How to Use Combo Boxes	Uses a compound border to combine a line border with an empty border. The empty border provides space between the line and the component's innards.

Using the JFC/Swing Packages