Apache POI Word - Paragraph

Overview

In the previous article, we discussed how to create and save documents. In this article, we will continue from where we left off and explain how to add paragraphs and text to the document, as well as how to change the style of the text.

The components of a document

A document typically consists of a title and several subheadings (such as second-level, third-level, fourth-level, fifth-level, and so on, if desired). Each subheading is usually followed by one or more paragraphs, and each paragraph contains multiple pieces of text.

Additionally, a document can also include tables, images, videos, and other elements. However, these topics are not covered in this article and will be explained in subsequent articles.

Adding paragraphs and text to a document

Creating paragraphs and adding text:

XWPFParagraph p = doc.createParagraph();
XWPFRun run = p.createRun();
run.setText("this this the text in paragraph");

Is it simple enough? However, I feel that it could be even more concise. Wouldn't it be simpler if XWPFParagraph had a addText(String text) method directly? Why did the POI API design a Run object to carry the text? What exactly is a Run?

Before answering these questions, let's first create a run.docx document and insert the following text into the document.

Then rename the document as run.zip, extract it, and take a look at the contents of the document.xml file.

A Run is used to carry a portion of text with the same style. Since the sentence "This is red text, but this is becomes green." contains two different styles (different colors), there are two Run objects.

With the groundwork laid out, take another look at the code that generates this piece of text using the POI API. Hopefully, it becomes easier to understand.

package net.verytools.tutorial;

import org.apache.poi.xwpf.usermodel.XWPFDocument;
import org.apache.poi.xwpf.usermodel.XWPFParagraph;
import org.apache.poi.xwpf.usermodel.XWPFRun;

import java.io.FileOutputStream;
import java.io.IOException;

public class CreateDoc {

  public static void main(String[] args) throws IOException {
    XWPFDocument doc = new XWPFDocument();
    XWPFParagraph p = doc.createParagraph();
    
    XWPFRun run1 = p.createRun();
    run1.setColor("FF0000");
    run1.setText("This is red text,");
    
    XWPFRun run2 = p.createRun();
    run2.setColor("00FF00");
    run2.setText("but this is becomes green.");
    // ...
  }
}

In addition to setting the color, a Run object can also be used to set the font, font size, and whether the font should be bold or not.

// set font size
run1.setFontSize(16);
// set font family
run1.setFontFamily("Arial Black");
// set bold style
run1.setBold(true);

Line breaks within a paragraph can also be achieved using Run objects.

XWPFParagraph p = doc.createParagraph();
XWPFRun run = p.createRun();
run.addBreak(BreakType.TEXT_WRAPPING);

Giving a title to the document

What API should we use to generate a title for the document? As mentioned earlier, a docx document is essentially a zip file containing multiple XML and media files. So, if we insert a first-level title in the docx document and then change the file extension to .zip, and extract it, we can inspect the XML to gain some insights.

<w:body>
  <w:p>
    <w:pPr>
      <w:pStyle w:val="2"/>
      <w:bidi w:val="0"/>
      <w:rPr>
        <w:rFonts w:hint="default"/>
        <w:lang w:val="en-US" w:eastAsia="zh-CN"/>
      </w:rPr>
    </w:pPr>
    <w:r>
      <w:rPr>
        <w:rFonts w:hint="eastAsia"/>
        <w:lang w:val="en-US" w:eastAsia="zh-CN"/>
      </w:rPr>
      <w:t>This is the title</w:t>
    </w:r>
  </w:p>
</w:body>

From <w:p>, we can see that the title is also a paragraph. From <w:pStyle w:val="2"/>, we can see that the title applies a style with an ID of "2". By referring to the styles.xml file, we can find the style with an ID of "2".

From the image, it can be seen that the style specifies a font size of 44, bold font, and the style name is "heading 1". <w:basedOn w:val="1"/> indicates that this style is based on the style which has an ID of "1". As for the style with ID "1", we won't include an image here, but it specifies the alignment as center-aligned.

Note: The unit of <w:sz w:val="44"/> in the XML is half-points, so the actual font size is 22pt.

The advantage of styles is their reusability. We can apply the same style to multiple sections of the document. How to generate styles using POI will be explained in future articles. For now, we won't use styles and will simulate the title by setting an appropriate font size and bolding the text.

try (XWPFDocument doc = new XWPFDocument()) {
  try (FileOutputStream out = new FileOutputStream("D:\\tmp\\simpledoc.docx")) {
    XWPFParagraph p = doc.createParagraph();
    // center aligned
    p.setAlignment(ParagraphAlignment.CENTER);
    XWPFRun run = p.createRun();
    // bold
    run.setBold(true);
    // set font size to 44 half-point
    run.setFontSize(22);
    run.setFontFamily("Calibri");
    run.setText("This is title");
    doc.write(out);
  }
}

Although we didn't use styles, the appearance of the title we generated looks similar to a first-level title created using Office software. However, it's important to note that this similarity is only in terms of visual display. The title has another important feature, which is the outline level. We will explain this separately when we discuss styles in the future.

>> Back to Directory