parfmt: add ParagraphFormat.widow_control getter

Steve Canny · Steve Canny · commit 86741a133904 · 2015-02-08T00:01:44.000-08:00
diff --git a/docx/oxml/__init__.py b/docx/oxml/__init__.py
@@ -146,6 +146,7 @@ def OxmlElement(nsptag_str, attrs=None, nsdecls=None):
 register_element_cls('w:pPr',             CT_PPr)
 register_element_cls('w:pStyle',          CT_String)
 register_element_cls('w:spacing',         CT_Spacing)
+register_element_cls('w:widowControl',    CT_OnOff)
 
 from .text.run import (
     CT_Br, CT_Fonts, CT_HpsMeasure, CT_R, CT_RPr, CT_Text, CT_Underline,
diff --git a/docx/oxml/text/paragraph.py b/docx/oxml/text/paragraph.py
@@ -120,6 +120,7 @@ class CT_PPr(BaseOxmlElement):
     keepNext = ZeroOrOne('w:keepNext', successors=_tag_seq[2:])
     keepLines = ZeroOrOne('w:keepLines', successors=_tag_seq[3:])
     pageBreakBefore = ZeroOrOne('w:pageBreakBefore', successors=_tag_seq[4:])
+    widowControl = ZeroOrOne('w:widowControl', successors=_tag_seq[6:])
     numPr = ZeroOrOne('w:numPr', successors=_tag_seq[7:])
     spacing = ZeroOrOne('w:spacing', successors=_tag_seq[22:])
     ind = ZeroOrOne('w:ind', successors=_tag_seq[23:])
@@ -334,6 +335,16 @@ def style(self, style):
         pStyle = self.get_or_add_pStyle()
         pStyle.val = style
 
+    @property
+    def widowControl_val(self):
+        """
+        The value of `widowControl/@val` or |None| if not present.
+        """
+        widowControl = self.widowControl
+        if widowControl is None:
+            return None
+        return widowControl.val
+
 
 class CT_Spacing(BaseOxmlElement):
     """
diff --git a/docx/text/paragraph.py b/docx/text/paragraph.py
@@ -351,6 +351,19 @@ def space_before(self):
     def space_before(self, value):
         self._element.get_or_add_pPr().spacing_before = value
 
+    @property
+    def widow_control(self):
+        """
+        |True| if the first and last lines in the paragraph remain on the
+        same page as the rest of the paragraph when Word repaginates the
+        document. |None| indicates its effective value is inherited from the
+        style hierarchy.
+        """
+        pPr = self._element.pPr
+        if pPr is None:
+            return None
+        return pPr.widowControl_val
+
     @staticmethod
     def _line_spacing(spacing_line, spacing_lineRule):
         """
diff --git a/features/txt-parfmt-props.feature b/features/txt-parfmt-props.feature
@@ -128,7 +128,6 @@ Feature: Get or set paragraph formatting properties
       | right      | 17.3 pt  | None      | None    |
 
 
-  @wip
   Scenario Outline: Get On/Off paragraph property
     Given a paragraph format having <prop-name> set <state>
      Then paragraph_format.<prop-name> is <value>
diff --git a/tests/text/test_paragraph.py b/tests/text/test_paragraph.py
@@ -537,6 +537,9 @@ def line_spacing_rule_set_fixture(self, request):
         ('w:p',                                  'page_break_before', None),
         ('w:p/w:pPr/w:pageBreakBefore',          'page_break_before', True),
         ('w:p/w:pPr/w:pageBreakBefore{w:val=0}', 'page_break_before', False),
+        ('w:p',                                  'widow_control',     None),
+        ('w:p/w:pPr/w:widowControl{w:val=true}', 'widow_control',     True),
+        ('w:p/w:pPr/w:widowControl{w:val=off}',  'widow_control',     False),
     ])
     def on_off_get_fixture(self, request):
         p_cxml, prop_name, expected_value = request.param
