Borders and Shading

Overview

This guide shows how to add borders and background shading to paragraphs and table cells of a Word document in Java and read them back with Aspose.Words FOSS for Java. Borders and shading are part of the paragraph format and of the cell format. getBorders() returns a BorderCollection with one Border for each side (getBottom(), getTop(), getLeft(), getRight()), and each border has a line style from LineStyle, a width in points and a color. getShading() returns a Shading object whose background pattern color is the fill; the examples only use a solid fill. The examples below were compiled and run on Java 8, 17 and 21 with identical output.


Prerequisites

RequirementDetail
Java8 or later
DependencyThe package from Installation
Importimport com.aspose.words.*;
CodeThe examples are statements. Put them in a method that declares throws Exception.

Borders and Background for a Paragraph

Set the border on builder.getParagraphFormat().getBorders().getBottom() and the fill with getShading().setBackgroundPatternColor, then write the paragraph. clearFormatting() on the paragraph format resets the next paragraph. After a save and reload, the first paragraph had a SINGLE bottom border 1.5 pt wide in the color 255,0,0 and the background 255,250,205. The second paragraph had a NONE bottom border of 0.0 pt.

import com.aspose.words.*;
import java.awt.Color;

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

ParagraphFormat format = builder.getParagraphFormat();
format.getBorders().getBottom().setLineStyle(LineStyle.SINGLE);
format.getBorders().getBottom().setLineWidth(1.5);
format.getBorders().getBottom().setColor(Color.RED);
format.getShading().setBackgroundPatternColor(new Color(255, 250, 205));
builder.writeln("A paragraph with a red bottom border and a pale yellow background.");

format.clearFormatting();
builder.writeln("A plain paragraph.");
doc.save("borders.docx");

Document reloaded = new Document("borders.docx");
NodeCollection paragraphs = reloaded.getChildNodes(NodeType.PARAGRAPH, true);
for (int i = 0; i < paragraphs.getCount(); i++) {
    Paragraph paragraph = (Paragraph) paragraphs.get(i);
    if (paragraph.getText().trim().length() == 0) {
        continue;
    }
    Border bottom = paragraph.getParagraphFormat().getBorders().getBottom();
    Color background = paragraph.getParagraphFormat().getShading().getBackgroundPatternColor();
    System.out.println("\"" + paragraph.getText().trim() + "\"");
    System.out.println("  bottom border: " + LineStyle.getName(bottom.getLineStyle()) + ", " + bottom.getLineWidth() + " pt, color " + bottom.getColor().getRed() + "," + bottom.getColor().getGreen() + "," + bottom.getColor().getBlue());
    System.out.println("  background: " + background.getRed() + "," + background.getGreen() + "," + background.getBlue());
}

The program printed:

"A paragraph with a red bottom border and a pale yellow background."
  bottom border: SINGLE, 1.5 pt, color 255,0,0
  background: 255,250,205
"A plain paragraph."
  bottom border: NONE, 0.0 pt, color 0,0,0
  background: 0,0,0

Shading and Borders in a Table

builder.getCellFormat() has its own getShading() and getBorders() that apply to the cells you insert next. The example shades the header cells, then clears the shading and sets a DOUBLE line style on the borders collection for the body cells. After a reload the first header cell had the background 221,235,247. The top border of the first cell in row 1 was DOUBLE, as set. The top border of the first cell in row 0 read SINGLE although the example did not set any border for the header row, so the first header cell started with a SINGLE top border in this test.

import com.aspose.words.*;
import java.awt.Color;

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Table table = builder.startTable();
builder.getCellFormat().getShading().setBackgroundPatternColor(new Color(221, 235, 247));
builder.insertCell();
builder.write("Header A");
builder.insertCell();
builder.write("Header B");
builder.endRow();

builder.getCellFormat().getShading().clearFormatting();
builder.getCellFormat().getBorders().setLineStyle(LineStyle.DOUBLE);
builder.insertCell();
builder.write("Body 1");
builder.insertCell();
builder.write("Body 2");
builder.endRow();
builder.endTable();
doc.save("cells.docx");

Document reloaded = new Document("cells.docx");
Table loaded = (Table) reloaded.getChildNodes(NodeType.TABLE, true).get(0);
Cell header = loaded.getRows().get(0).getCells().get(0);
Color shade = header.getCellFormat().getShading().getBackgroundPatternColor();
System.out.println("Header cell background: " + shade.getRed() + "," + shade.getGreen() + "," + shade.getBlue());
for (int r = 0; r < loaded.getRows().getCount(); r++) {
    Cell cell = loaded.getRows().get(r).getCells().get(0);
    System.out.println("Row " + r + ", first cell: top border " + LineStyle.getName(cell.getCellFormat().getBorders().getTop().getLineStyle()));
}

The program printed:

Header cell background: 221,235,247
Row 0, first cell: top border SINGLE
Row 1, first cell: top border DOUBLE

Tips and Best Practices

  • A paragraph without shading or border returned the color 0,0,0 for both in the test (the plain paragraph in the first example). In the test that value was transparent, not black: the alpha of an unset color was 0, so check getAlpha() and getLineStyle() before you read a border color.
  • A border width is in points and must be between 0 and 31: in a test setLineWidth accepted 0, 0.25 and 31 and threw an IllegalArgumentException for -0.5, 31.5, 32 and 100.
  • getBorders() holds 6 borders for a paragraph in the test, so loop with getCount() and get(index) if you need all of them. For the four sides use getTop, getBottom, getLeft and getRight.
  • Set the cell format before insertCell, as the second example does, because it applies to the cells you insert afterwards.

Common Issues

IssueCauseFix
The compiler reports cannot find symbol for Document.The com.aspose.words package is not imported.Add import com.aspose.words.*;.
The compiler reports an unreported exception.The Document constructors, Document.save and some other methods declare throws Exception.Declare it on the calling method or catch it.
The compiler reports cannot find symbol for Color.Color is java.awt.Color and it is not imported.Add import java.awt.Color;.
An unshaded paragraph reports the background 0,0,0.An unset color read as 0,0,0 with alpha 0 in the test.Check getAlpha(): it was 0 for an unset color in the test.
setLineWidth throws IllegalArgumentException.The width was outside 0 to 31 points (-0.5, 31.5, 32 and 100 threw in the test).Use a width from 0 to 31 points.

FAQ

How do I put a border around one side of a paragraph?

Call setLineStyle, setLineWidth and setColor on getBorders().getBottom() (or getTop, getLeft, getRight) of the paragraph format, as the first example does.

How do I shade a table cell?

Call builder.getCellFormat().getShading().setBackgroundPatternColor(color) before insertCell, as the second example does.

How do I remove a border?

In the first example clearFormatting() on the paragraph format gave the next paragraph a NONE border of 0.0 pt. A paragraph border that was never set read the same in the test. Removing a border from an existing paragraph was not tested.

Which formats were tested?

Only DOCX: the examples save a DOCX file and reload it.


API Reference Summary

Class / MethodDescription
BorderCollectionA collection of Border objects.
BorderRepresents a border of an object.
ShadingContains shading attributes for an object.
LineStyleSpecifies line style of a Border.
ParagraphFormat.getBorders()Gets collection of borders of the paragraph.
ParagraphFormat.getShading()Returns a Shading object that refers to the shading formatting for the paragraph.
CellFormat.getBorders()Gets collection of borders of the cell.
CellFormat.getShading()Returns a Shading object that refers to the shading formatting for the cell.
Border.setLineStyle(value)Sets the line style value.
Border.setLineWidth(value)Sets the line width value.
Shading.setBackgroundPatternColor(value)Sets the background pattern color value.

Related Guides