java - Apache POI bullet spacing

Question

I am working on a project to generate a word document that has bullets. By default the bullets are followed by a large gap before the text. In Word, under List Indents Follow number with option, you can set this space to be a tab character, space character or none. By default in POI it is set to tab it appears. How can I change this to use space character?

Answer 1

I would highly recommend to use tab stop as this is the default in Word and correctly using this also leads to a proper presentation of multi lined text after the bullet points.

The gap between bullet point and text is determined by the paragraphs indentation settings. The left indentation determines the text position and the hanging indentation determines how much the bullet point hangs before the text.

Example:

import java.io.File;
import java.io.FileOutputStream;

import org.apache.poi.xwpf.usermodel.*;

import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTAbstractNum;
import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTLvl;
import org.openxmlformats.schemas.wordprocessingml.x2006.main.STNumberFormat;

import java.util.ArrayList;
import java.util.Arrays;

import java.math.BigInteger;

public class CreateWordSimplestBulletList {

 public static void main(String[] args) throws Exception {

  ArrayList<String> documentList = new ArrayList<String>(
   Arrays.asList(
    new String[] {
     "One",
     "Two",
     "Three"
    }));

  CTAbstractNum cTAbstractNum = CTAbstractNum.Factory.newInstance();
  //Next we set the AbstractNumId. This requires care.
  //Since we are in a new document we can start numbering from 0.
  //But if we have an existing document, we must determine the next free number first.
  cTAbstractNum.setAbstractNumId(BigInteger.valueOf(0));

  //Bullet list
  CTLvl cTLvl = cTAbstractNum.addNewLvl();
  cTLvl.setIlvl(BigInteger.valueOf(0)); // set indent level 0
  cTLvl.addNewNumFmt().setVal(STNumberFormat.BULLET);
  cTLvl.addNewLvlText().setVal("?");

  XWPFAbstractNum abstractNum = new XWPFAbstractNum(cTAbstractNum);
  XWPFDocument document = new XWPFDocument();
  XWPFNumbering numbering = document.createNumbering();

  BigInteger abstractNumID = numbering.addAbstractNum(abstractNum);
  BigInteger numID = numbering.addNum(abstractNumID);

  XWPFParagraph paragraph = document.createParagraph();
  XWPFRun run=paragraph.createRun();
  run.setText("The default list:");

  for (String string : documentList) {
   paragraph = document.createParagraph();
   paragraph.setNumID(numID);
   // font size for bullet point in half pt
   paragraph.getCTP().getPPr().addNewRPr().addNewSz().setVal(BigInteger.valueOf(48));
   run = paragraph.createRun();
   run.setText(string);
   run.setFontSize(24);
  }

  paragraph = document.createParagraph();

  paragraph = document.createParagraph();
  run=paragraph.createRun();
  run.setText("The list having defined gap between bullet point and text:");

  for (String string : documentList) {
   paragraph = document.createParagraph();
   paragraph.setNumID(numID);
   paragraph.getCTP().getPPr().addNewRPr().addNewSz().setVal(BigInteger.valueOf(48));
   // set indents in Twips (twentieth of an inch point, 1440 Twips = 1 inch 
   paragraph.setIndentFromLeft(1440/4); // indent from left 360 Twips = 1/4 inch
   paragraph.setIndentationHanging(1440/4); // indentation hanging 360 Twips = 1/4 inch
                                            // so bullet point hangs 1/4 inch before the text at indentation 0
   run = paragraph.createRun();
   run.setText(string);
   run.setFontSize(24);
  }

  paragraph = document.createParagraph();

  FileOutputStream out = new FileOutputStream("CreateWordSimplestBulletList.docx");
  document.write(out);
  out.close();
  document.close();

 }
}

---

To additional answer the question about a list having space between bullet point and text, here it is.

That setting must be done in list definition itself by setting level suffix to space in list levels settings.

cTLvl.addNewSuff().setVal(STLevelSuffix.SPACE);

Complete example:

import java.io.File;
import java.io.FileOutputStream;

import org.apache.poi.xwpf.usermodel.*;

import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTAbstractNum;
import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTLvl;
import org.openxmlformats.schemas.wordprocessingml.x2006.main.STNumberFormat;
import org.openxmlformats.schemas.wordprocessingml.x2006.main.STLevelSuffix;

import java.util.ArrayList;
import java.util.Arrays;

import java.math.BigInteger;

public class CreateWordSimplestBulletListSpace {

 public static void main(String[] args) throws Exception {

  ArrayList<String> documentList = new ArrayList<String>(
   Arrays.asList(
    new String[] {
     "One",
     "Two",
     "Three"
    }));

  CTAbstractNum cTAbstractNum = CTAbstractNum.Factory.newInstance();
  //Next we set the AbstractNumId. This requires care.
  //Since we are in a new document we can start numbering from 0.
  //But if we have an existing document, we must determine the next free number first.
  cTAbstractNum.setAbstractNumId(BigInteger.valueOf(0));

  //Bullet list
  CTLvl cTLvl = cTAbstractNum.addNewLvl();
  cTLvl.setIlvl(BigInteger.valueOf(0)); // set indent level 0
  cTLvl.addNewNumFmt().setVal(STNumberFormat.BULLET);
  cTLvl.addNewSuff().setVal(STLevelSuffix.SPACE);
  cTLvl.addNewLvlText().setVal("?");

  XWPFAbstractNum abstractNum = new XWPFAbstractNum(cTAbstractNum);
  XWPFDocument document = new XWPFDocument();
  XWPFNumbering numbering = document.createNumbering();

  BigInteger abstractNumID = numbering.addAbstractNum(abstractNum);
  BigInteger numID = numbering.addNum(abstractNumID);

  XWPFParagraph paragraph = document.createParagraph();
  XWPFRun run=paragraph.createRun();
  run.setText("The list having space between bulltet point and text:");

  for (String string : documentList) {
   paragraph = document.createParagraph();
   paragraph.setNumID(numID);
   // font size for bullet point in half pt
   paragraph.getCTP().getPPr().addNewRPr().addNewSz().setVal(BigInteger.valueOf(48));
   run = paragraph.createRun();
   run.setText(string);
   run.setFontSize(24);
  }

  paragraph = document.createParagraph();

  FileOutputStream out = new FileOutputStream("CreateWordSimplestBulletList.docx");
  document.write(out);
  out.close();
  document.close();

 }
}

But as said, this is not to recommend. Disadvantages are: This affects all lists based on that definition. There is no possibility to determine the gap between bullet point and text. If items contain multiple line of text then the second text line starts immediately under the bullet point, not indented as in the other example.