Cleaned up underline, started adding table cell properties

underline module almost done, need to work on tests.

created class for `<w:tcPr>` to handle cell properties like `gridSpan`

Author: onlyjus

docx/enum/text.py

@@ -25,3 +25,50 @@ class WD_BREAK_TYPE(object):
     TEXT_WRAPPING = 11
 
 WD_BREAK = WD_BREAK_TYPE
+
+class WD_UNDERLINE_TYPE(object):
+    """
+    Underline types, corresponding to WdUnderline enumeration
+    http://msdn.microsoft.com/en-us/library/office/ff822388(v=office.15).aspx
+    """
+    DASH = 7 # Dashes.
+    DASH_HEAVY = 23 # Heavy dashes.
+    DASH_LONG = 39 # Long dashes.
+    LONG_HEAVY = 55 # Long heavy dashes.
+    DOT_DASH = 9 # Alternating dots and dashes.
+    DOT_DASH_HEAVY = 25 # Alternating heavy dots and heavy dashes.
+    DOT_DOT_DASH = 10 # An alternating dot-dot-dash pattern.
+    DOT_DOT_DASH_HEAVY = 26 # An alternating heavy dot-dot-dash pattern.
+    DOTTED = 4 # Dots.
+    DOTTED_HEAVY = 20 # Heavy dots.
+    DOUBLE = 3 # A double line.
+    NONE = 0 # No underline.
+    SINGLE = 1 # A single line. default.
+    THICK = 6 # A single thick line.
+    WAVY = 11 #A single wavy line.
+    WAVY_DOUBLE = 43 # A double wavy line.
+    WAVY_HEAVY = 27 # A heavy wavy line.
+    WORDS = 2 # Underline individual words only.
+    
+    stringDict={
+        DASH:'dash',
+        DASH_HEAVY:'dashHeavy',
+        DASH_LONG:'dashLong',
+        LONG_HEAVY:'longHeavy',
+        DOT_DASH:'dotDash',
+        DOT_DASH_HEAVY:'dotDashHeavy',
+        DOT_DOT_DASH:'dotDotDash',
+        DOT_DOT_DASH_HEAVY:'dotDotDashHeavy',
+        DOTTED:'dotted',
+        DOTTED_HEAVY:'dottedHeavy',
+        DOUBLE:'double',
+        NONE:'none',
+        SINGLE:'single',
+        THICK:'thick',
+        WAVY:'wavy',
+        WAVY_DOUBLE:'wavyDouble',
+        WAVY_HEAVY:'wavyHeavy',
+        WORDS:'words',
+    }    
+    
+WD_UNDERLINE = WD_UNDERLINE_TYPE

docx/oxml/__init__.py

@@ -45,13 +45,14 @@
 register_custom_element_class('w:style', CT_Style)
 register_custom_element_class('w:styles', CT_Styles)
 
-from docx.oxml.table import CT_Row, CT_Tbl, CT_TblGrid, CT_TblPr, CT_Tc
+from docx.oxml.table import CT_Row, CT_Tbl, CT_TblGrid, CT_TblPr, CT_Tc, CT_TcPr
 register_custom_element_class('w:tbl', CT_Tbl)
 register_custom_element_class('w:tblGrid', CT_TblGrid)
 register_custom_element_class('w:tblPr', CT_TblPr)
 register_custom_element_class('w:tblStyle', CT_String)
 register_custom_element_class('w:tc', CT_Tc)
 register_custom_element_class('w:tr', CT_Row)
+register_custom_element_class('w:tcPr', CT_TcPr)
 
 from docx.oxml.text import CT_Br, CT_P, CT_PPr, CT_R, CT_RPr, CT_Text
 register_custom_element_class('w:b', CT_OnOff)

docx/oxml/table.py

@@ -251,3 +251,52 @@ def tcPr(self):
         <w:tcPr> child element or |None| if not present.
         """
         return self.find(qn('w:tcPr'))
+        
+    def get_or_add_tcPr(self):
+        """
+        Return the tcPr child element, newly added if not present.
+        """
+        tcPr = self.tcPr
+        if tcPr is None:
+            tcPr = self._add_tcPr()
+        return tcPr
+        
+    def _add_tcPr(self):
+        """
+        Return a newly added tcPr child element. Assumes one is not present.
+        """
+        tcPr = CT_TcPr.new()
+        self.append(tcPr)
+        return tcPr
+        
+class CT_TcPr(OxmlBaseElement):
+    """
+    ``<w:tcPr>`` element, child of ``<w:tc>``, holds child elements that
+    define cell properties such as gridSpan.
+    """
+    @classmethod
+    def new(cls):
+        """
+        Return a new ``<w:tcPr>`` element.
+        """
+        return OxmlElement('w:tcPr')
+        
+    def add_gridSpan(self, span):
+        """
+        Return a new <w:gridSpan> element newly inserted in sequence among
+        the existing child elements.gridSpan
+        """
+        gridSpan = CT_String.new('w:gridSpan', str(span))
+        self.append(gridSpan) # append or insert?
+        return gridSpan
+
+    @property
+    def gridSpan(self):
+        """
+        Optional <w:gridSpan> child element, or |None| if not present.
+        """
+        return self.find(qn('w:gridSpan'))
+        
+    
+        
+    

docx/oxml/text.py

@@ -299,7 +299,7 @@ def add_underline(self, style):
         """
         Return a newly added <w:u w:val=style/> child element.
         """
-        u = CT_String.new('w:u', style)
+        u = CT_String.new('w:u', str(style))
         self.insert(0, u)
         return u
 

docx/table.py

@@ -113,7 +113,24 @@ def text(self, text):
         p = tc.add_p()
         r = p.add_r()
         r.add_t(text)
-
+        
+    @property
+    def colSpan(self):
+        """
+        Set the column span
+        """
+        span = self._tc.get_or_add_tcPr().gridSpan
+        if span is None:
+            return None
+        return span.val
+        
+    @colSpan.setter
+    def colSpan(self, val):
+        span = self._tc.get_or_add_tcPr().gridSpan
+        if span is None:
+            self._tc.get_or_add_tcPr().add_gridSpan(val)
+        else:
+            span.val = val  
 
 class _Column(object):
     """

docx/text.py

@@ -6,7 +6,7 @@
 
 from __future__ import absolute_import, print_function, unicode_literals
 
-from docx.enum.text import WD_BREAK
+from docx.enum.text import WD_BREAK, WD_UNDERLINE
 
 
 def boolproperty(f):
@@ -215,12 +215,14 @@ def italic(self):
     @property
     def underline(self):
         """
-        String name of underline style to be applied. If "none" or False, then no underline
-        is applied. If True, single underline is applied.
+        Underline text with style of *underline_type*. *underline_type* can
+        take the values `WD_UNDERLINE.SINGLE`, `WD_UNDERLINE.DOUBLE`, etc.
+        where `WD_UNDERLINE` is imported from `docx.enum.text`.
         
-        Valid Values: True, False, 'single', 'words', 'double', 'thick', 'dotted', 'dottedHeavy',
-        'dash', 'dashedHeavy', 'dashLong', 'dashLongHeavy', 'dotDash', 'dashDotHeavy',
-        'dotDotDash', 'dashDotDotHeavy', 'wave', 'wavyHeavy', 'wavyDouble', 'none'
+        Shorthand:
+        setting to True results in `WD_UNDERLINE.SINGLE`.
+        setting to False results in `WD_UNDERLINE.NONE`.
+        setting to None results in `WD_UNDERLINE.NONE`.
         """
         u = self._r.get_or_add_rPr().underline
         if u is None:
@@ -231,16 +233,11 @@ def underline(self):
     def underline(self, style):
         # interperate style
         if style is None:
-            style = 'none'
+            style = WD_UNDERLINE.NONE
         if type(style)==bool:
-            style = 'single' if style else 'none'
-        
-        validStyles = ['single', 'words', 'double', 'thick', 'dotted', 'dottedHeavy', 'dash',
-        'dashedHeavy', 'dashLong', 'dashLongHeavy', 'dotDash', 'dashDotHeavy', 'dotDotDash', 'dashDotDotHeavy',
-        'wave', 'wavyHeavy', 'wavyDouble', 'none']        
-        
-        if style not in validStyles:
-            raise ValueError('"'+style+'" is not valid. Needs to be: '+', '.join(validStyles))
+            style = WD_UNDERLINE.SINGLE if style else WD_UNDERLINE.NONE
+            
+        style = WD_UNDERLINE.stringDict[style]
 
         u = self._r.get_or_add_rPr().underline
         if u is None: