diff --git a/src/docx/enum/text.py b/src/docx/enum/text.py index 99e776fea..f93c856d8 100644 --- a/src/docx/enum/text.py +++ b/src/docx/enum/text.py @@ -67,6 +67,42 @@ class WD_PARAGRAPH_ALIGNMENT(BaseXmlEnum): WD_ALIGN_PARAGRAPH = WD_PARAGRAPH_ALIGNMENT +class WD_PARAGRAPH_OUTLINELVL(BaseXmlEnum): + """Alias: **WD_OUTLINELVL_PARAGRAPH** + + Specifies paragraph outline level. + + Example:: + + from docx.enum.text import WD_OUTLINELVL_PARAGRAPH + + paragraph = document.add_paragraph() + paragraph.outlineLvl = WD_OUTLINELVL_PARAGRAPH.LEVEL_1 + """ + + LEVEL_1 = (0, "outline-level 1", "Outline Level 1") + + LEVEL_2 = (1, "outline-level 2", "Outline Level 2") + + LEVEL_3 = (2, "outline-level 3", "Outline Level 3") + + LEVEL_4 = (3, "outline-level 4", "Outline Level 4") + + LEVEL_5 = (4, "outline-level 5", "Outline Level 5") + + LEVEL_6 = (5, "outline-level 6", "Outline Level 6") + + LEVEL_7 = (6, "outline-level 7", "Outline Level 7") + + LEVEL_8 = (7, "outline-level 8", "Outline Level 8") + + LEVEL_9 = (8, "outline-level 9", "Outline Level 9") + + BODY_TEXT = (9, "outline-level Body Text", "Outline Level Body Text") + + +WD_OUTLINELVL_PARAGRAPH = WD_PARAGRAPH_OUTLINELVL + class WD_BREAK_TYPE(enum.Enum): """Corresponds to WdBreakType enumeration. diff --git a/src/docx/oxml/__init__.py b/src/docx/oxml/__init__.py index 621ef279a..21a9a3954 100644 --- a/src/docx/oxml/__init__.py +++ b/src/docx/oxml/__init__.py @@ -220,6 +220,7 @@ from .text.parfmt import ( # noqa CT_Ind, CT_Jc, + CT_OutlineLvl, CT_PPr, CT_Spacing, CT_TabStop, @@ -228,6 +229,7 @@ register_element_cls("w:ind", CT_Ind) register_element_cls("w:jc", CT_Jc) +register_element_cls('w:outlineLvl', CT_OutlineLvl) register_element_cls("w:keepLines", CT_OnOff) register_element_cls("w:keepNext", CT_OnOff) register_element_cls("w:pageBreakBefore", CT_OnOff) diff --git a/src/docx/oxml/text/parfmt.py b/src/docx/oxml/text/parfmt.py index 49ea01003..8152cff9c 100644 --- a/src/docx/oxml/text/parfmt.py +++ b/src/docx/oxml/text/parfmt.py @@ -9,6 +9,7 @@ WD_LINE_SPACING, WD_TAB_ALIGNMENT, WD_TAB_LEADER, + WD_OUTLINELVL_PARAGRAPH, ) from docx.oxml.simpletypes import ST_SignedTwipsMeasure, ST_TwipsMeasure from docx.oxml.xmlchemy import ( @@ -40,6 +41,11 @@ class CT_Jc(BaseOxmlElement): val = RequiredAttribute("w:val", WD_ALIGN_PARAGRAPH) +class CT_OutlineLvl(BaseOxmlElement): + """```` element, specifying paragraph outlineLvl.""" + val = RequiredAttribute('w:val', WD_OUTLINELVL_PARAGRAPH) + + class CT_PPr(BaseOxmlElement): """```` element, containing the properties for a paragraph.""" @@ -98,6 +104,7 @@ class CT_PPr(BaseOxmlElement): spacing = ZeroOrOne("w:spacing", successors=_tag_seq[22:]) ind = ZeroOrOne("w:ind", successors=_tag_seq[23:]) jc = ZeroOrOne("w:jc", successors=_tag_seq[27:]) + outlineLvl = ZeroOrOne('w:outlineLvl', successors=_tag_seq[31:]) sectPr = ZeroOrOne("w:sectPr", successors=_tag_seq[35:]) del _tag_seq @@ -174,6 +181,23 @@ def jc_val(self, value): return self.get_or_add_jc().val = value + @property + def outlineLvl_val(self): + """ + The value of the ```` child element or |None| if not present. + """ + outlineLvl = self.outlineLvl + if outlineLvl is None: + return None + return outlineLvl.val + + @outlineLvl_val.setter + def outlineLvl_val(self, value): + if value is None: + self._remove_outlineLvl() + return + self.get_or_add_outlineLvl().val = value + @property def keepLines_val(self): """The value of `keepLines/@val` or |None| if not present.""" diff --git a/src/docx/text/paragraph.py b/src/docx/text/paragraph.py index 2425f1d6e..57c8ff5da 100644 --- a/src/docx/text/paragraph.py +++ b/src/docx/text/paragraph.py @@ -58,6 +58,21 @@ def alignment(self) -> WD_PARAGRAPH_ALIGNMENT | None: def alignment(self, value: WD_PARAGRAPH_ALIGNMENT): self._p.alignment = value + @property + def outlineLvl(self): + """ + A member of the :ref:`WdParagraphOutlineLevel` enumeration specifying + the outline-level setting for this paragraph. A value of |None| + indicates the paragraph has no directly-applied outline-level value and + will inherit its outline-level value from its style hierarchy. Assigning + |None| to this property removes any directly-applied outline-level value. + """ + return self._p.outlineLvl + + @outlineLvl.setter + def outlineLvl(self, value): + self._p.outlineLvl = value + def clear(self): """Return this same paragraph after removing all its content. diff --git a/src/docx/text/parfmt.py b/src/docx/text/parfmt.py index ea374373b..d20f1fdf6 100644 --- a/src/docx/text/parfmt.py +++ b/src/docx/text/parfmt.py @@ -27,6 +27,23 @@ def alignment(self, value): pPr = self._element.get_or_add_pPr() pPr.jc_val = value + @property + def outlineLvl(self): + """ + A member of the :ref:`WdParagraphOutlineLevel` enumeration specifying + the outline level setting for this paragraph. A value of |None| + indicates paragraph outline level is inherited from the style hierarchy. + """ + pPr = self._element.pPr + if pPr is None: + return None + return pPr.outlineLvl_val + + @outlineLvl.setter + def outlineLvl(self, value): + pPr = self._element.get_or_add_pPr() + pPr.outlineLvl_val = value + @property def first_line_indent(self): """|Length| value specifying the relative difference in indentation for the