Paragraph formatting ==================== WordprocessingML supports a variety of paragraph formatting attributes to control layout characteristics such as justification, indentation, line spacing, space before and after, and widow/orphan control. Alignment (justification) ------------------------- In Word, each paragraph has an `alignment` attribute that specifies how to justify the lines of the paragraph when the paragraph is laid out on the page. Common values are left, right, centered, and justified. Protocol ~~~~~~~~ Getting and setting paragraph alignment:: >>> paragraph = body.add_paragraph() >>> paragraph.alignment None >>> paragraph.alignment = WD_ALIGN_PARAGRAPH.RIGHT >>> paragraph.alignment RIGHT (2) >>> paragraph.alignment = None >>> paragraph.alignment None XML Semantics ~~~~~~~~~~~~~ If the ```` element is not present on a paragraph, the alignment value for that paragraph is inherited from its style hierarchy. If the element is present, its value overrides any inherited value. From the API, a value of |None| on the ``Paragraph.alignment`` property corresponds to no ```` element being present. If |None| is assigned to ``Paragraph.alignment``, the ```` element is removed. Paragraph spacing ----------------- Spacing between subsequent paragraphs is controlled by the paragraph spacing attributes. Spacing can be applied either before the paragraph, after it, or both. The concept is similar to that of `padding` or `margin` in CSS. WordprocessingML supports paragraph spacing specified as either a length value or as a multiple of the line height; however only a length value is supported via the Word UI. Inter-paragraph spacing "overlaps", such that the rendered spacing between two paragraphs is the maximum of the space after the first paragraph and the space before the second. Protocol ~~~~~~~~ Getting and setting paragraph spacing:: >>> paragraph_format = document.styles['Normal'].paragraph_format >>> paragraph_format.space_before None >>> paragraph_format.space_before = Pt(12) >>> paragraph_format.space_before.pt 12.0 XML Semantics ~~~~~~~~~~~~~ * Paragraph spacing is specified using the `w:pPr/w:spacing` element, which also controls line spacing. Spacing is specified in twips. * If the `w:spacing` element is not present, paragraph spacing is inherited from the style hierarchy. * If not present in the style hierarchy, the paragraph will have no spacing. * If the `w:spacing` element is present but the specific attribute (e.g. `w:before`) is not, its value is inherited. Specimen XML ~~~~~~~~~~~~ .. highlight:: xml 12 pt space before, 0 after:: Line spacing ------------ Line spacing can be specified either as a specific length or as a multiple of the line height (font size). Line spacing is specified by the combination of values in `w:spacing/@w:line` and `w:spacing/@w:lineRule`. The :attr:`.ParagraphFormat.line_spacing` property determines which method to use based on whether the assigned value is an instance of |Length|. Protocol ~~~~~~~~ .. highlight:: python Getting and setting line spacing:: >>> paragraph_format.line_spacing, paragraph_format.line_spacing_rule (None, None) >>> paragraph_format.line_spacing = Pt(18) >>> paragraph_format.line_spacing, paragraph_format.line_spacing_rule (228600, WD_LINE_SPACING.EXACTLY (4)) >>> paragraph_format.line_spacing = 1 >>> paragraph_format.line_spacing, paragraph_format.line_spacing_rule (152400, WD_LINE_SPACING.SINGLE (0)) >>> paragraph_format.line_spacing = 0.9 >>> paragraph_format.line_spacing, paragraph_format.line_spacing_rule (137160, WD_LINE_SPACING.MULTIPLE (5)) XML Semantics ~~~~~~~~~~~~~ * Line spacing is specified by the combination of the values in `w:spacing/@w:line` and `w:spacing/@w:lineRule`. * `w:spacing/@w:line` is specified in twips. If `@w:lineRule` is 'auto' (or missing), `@w:line` is interpreted as 240ths of a line. For all other values of `@w:lineRule`, the value of `@w:line` is interpreted as a specific length in twips. * If the `w:spacing` element is not present, line spacing is inherited. * If `@w:line` is not present, line spacing is inherited. * If not present, `@w:lineRule` defaults to 'auto'. * If not present in the style hierarchy, line spacing defaults to single spaced. * The 'atLeast' value for `@w:lineRule` indicates the line spacing will be `@w:line` twips or single spaced, whichever is greater. Specimen XML ~~~~~~~~~~~~ .. highlight:: xml 14 points:: double-spaced:: Indentation ----------- Paragraph indentation is specified using the `w:pPr/w:ind` element. Left, right, first line, and hanging indent can be specified. Indentation can be specified as a length or in hundredths of a character width. Only length is supported by |docx|. Both first line indent and hanging indent are specified using the :attr:`.ParagraphFormat.first_line_indent` property. Assigning a positive value produces an indented first line. A negative value produces a hanging indent. Protocol ~~~~~~~~ .. highlight:: python Getting and setting indentation:: >>> paragraph_format.left_indent None >>> paragraph_format.right_indent None >>> paragraph_format.first_line_indent None >>> paragraph_format.left_indent = Pt(36) >>> paragraph_format.left_indent.pt 36.0 >>> paragraph_format.right_indent = Inches(0.25) >>> paragraph_format.right_indent.pt 18.0 >>> paragraph_format.first_line_indent = Pt(-18) >>> paragraph_format.first_line_indent.pt -18.0 XML Semantics ~~~~~~~~~~~~~ * Indentation is specified by `w:ind/@w:start`, `w:ind/@w:end`, `w:ind/@w:firstLine`, and `w:ind/@w:hanging`. * `w:firstLine` and `w:hanging` are mutually exclusive, if both are specified, `w:firstLine` is ignored. * All four attributes are specified in twips. * `w:start` controls left indent for a left-to-right paragraph or right indent for a right-to-left paragraph. `w:end` controls the other side. If mirrorIndents is specified, `w:start` controls the inside margin and `w:end` the outside. Negative values are permitted and cause the text to move past the text margin. * If `w:ind` is not present, indentation is inherited. * Any omitted attributes are inherited. * If not present in the style hierarchy, indentation values default to zero. Specimen XML ~~~~~~~~~~~~ .. highlight:: xml 1 inch left, 0.5 inch (additional) first line, 0.5 inch right:: 0.5 inch left, 0.5 inch hanging indent:: Page placement -------------- There are a handful of page placement properties that control such things as keeping the lines of a paragraph together on the same page, keeing a paragraph (such as a heading) on the same page as the subsequent paragraph, and placing the paragraph at the top of a new page. Each of these are tri-state boolean properties where |None| indicates "inherit". Protocol ~~~~~~~~ .. highlight:: python Getting and setting indentation:: >>> paragraph_format.keep_with_next None >>> paragraph_format.keep_together None >>> paragraph_format.page_break_before None >>> paragraph_format.widow_control None >>> paragraph_format.keep_with_next = True >>> paragraph_format.keep_with_next True >>> paragraph_format.keep_together = False >>> paragraph_format.keep_together False >>> paragraph_format.page_break_before = True >>> paragraph_format.widow_control = None XML Semantics ~~~~~~~~~~~~~ * All four elements have "On/Off" semantics. * If not present, their value is inherited. * If not present in the style hierarchy, values default to False. Specimen XML ~~~~~~~~~~~~ .. highlight:: xml keep with next, keep together, no page break before, and widow/orphan control:: Enumerations ------------ * :ref:`WdLineSpacing` * :ref:`WdParagraphAlignment` Specimen XML ------------ .. highlight:: xml A paragraph with inherited alignment:: Inherited paragraph alignment. A right-aligned paragraph:: Right-aligned paragraph. Schema excerpt -------------- ::