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
| Requirement | Detail |
|---|---|
| Java | 8 or later |
| Dependency | The package from Installation |
| Import | import com.aspose.words.*; |
| Code | The 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,0Shading 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 DOUBLETips 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()andgetLineStyle()before you read a border color. - A border width is in points and must be between 0 and 31: in a test
setLineWidthaccepted 0, 0.25 and 31 and threw anIllegalArgumentExceptionfor -0.5, 31.5, 32 and 100. getBorders()holds 6 borders for a paragraph in the test, so loop withgetCount()andget(index)if you need all of them. For the four sides usegetTop,getBottom,getLeftandgetRight.- Set the cell format before
insertCell, as the second example does, because it applies to the cells you insert afterwards.
Common Issues
| Issue | Cause | Fix |
|---|---|---|
| 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 / Method | Description |
|---|---|
BorderCollection | A collection of Border objects. |
Border | Represents a border of an object. |
Shading | Contains shading attributes for an object. |
LineStyle | Specifies 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. |