Text
Text in a Word document is nested three deep. A Document holds paragraphs, a
Paragraph holds runs, and a Run holds the actual characters. Which level you
reach for decides what you can change.
para := doc.AddParagraph()
para.Properties().SetAlignment(wml.ST_JcCenter)
run := para.AddRun()
run.Properties().SetBold(true)
run.AddText("Hello")A run is the smallest span that carries uniform character formatting: font,
size, weight, color, highlight, underline, superscript. Anything that varies
mid-sentence needs a second run. A paragraph owns everything that applies to the
block as a whole, which is alignment, indentation, spacing, borders, outline
level and list membership. Properties() on either one creates the underlying
property element on first call and returns the same object afterwards, so it is
safe to call repeatedly.
Where the same setter lives three times
Most paragraph settings exist in three places, and they are not interchangeable.
| Type | Reached from | Applies to |
|---|---|---|
Paragraph | doc.AddParagraph() | That paragraph. Convenience methods such as SetLeftIndent write straight through to its properties. |
ParagraphProperties | para.Properties() | The same paragraph, with the fuller API including Spacing(), AddTabStop and AddSection. |
ParagraphStyleProperties | style.ParagraphProperties() or numberingLevel.Properties() | Every paragraph carrying that style, or every item at that list level. |
They also differ in how they treat zero. The style-level setters and the
paragraph indent setters treat measurement.Zero as “remove this attribute”, so
a paragraph cannot use SetLeftIndent(0) to cancel an indent it inherited. Only
ParagraphProperties.SetSpacing, which is deprecated in favor of Spacing(),
writes a literal zero.
Direct formatting against styles
Named styles are the third way to format. doc.Styles.AddStyle defines one and
para.SetStyle("Heading1") applies it, which is what you want when the same
formatting recurs across a document. Direct properties set on the paragraph or
run override the style.
SetStyle takes the style ID, and the built-in IDs have no spaces:
Normal, Title, Heading1 through Heading9. An ID that does not exist is
written into the file without complaint and renders as unstyled text, which is
the most common reason a style appears to do nothing.
Units
Every distance argument in this section is a measurement.Distance. The
constants are all defined in points, so measurement.Inch, measurement.Point,
measurement.Millimeter, measurement.Centimeter and measurement.Twips
compose freely: 2*measurement.Inch, 144*measurement.Point and
2880*measurement.Twips are the same length. Values are truncated to twips, or
to eighths of a point for border thickness, on the way into the file, so a
length arrived at through a metric constant can land one twip short of the
round number you expected.
Font sizes are the exception worth remembering, since RunProperties.SetSize
stores half-points. Pass a Distance such as 14*measurement.Point and the
conversion is handled for you.
Where to look
| Guide | Covers |
|---|---|
| Bullets and Numbering | Numbering definitions, levels, and applying them to paragraphs. |
| HTML Formatting | Supplying formatted text as HTML tags rather than run by run. |
| Line Spacing | Space between lines within a paragraph, and the three spacing rules. |
| Paragraph Borders | Rules and boxes around a paragraph. |
| Paragraph Styles | Defining named styles, the built-in ones, and applying them. |
| Right-to-Left Text | Hebrew and Arabic runs, and direction-relative alignment. |
| Run Properties | Reading text and character formatting back out of an existing document. |
| Spacing and Indentation | Space before and after a paragraph, and left, right, first-line and hanging indents. |