This is the third in a 4-part series concerning creating MS Word documents in LotusScript. In the first tip, we talked about the basics of creating a Word document and adding text to it. In the second tip, we got a bit more advanced with some formatting options. In the third tip we talked about updating headers and footers and some other advanced topics. In this last tip we'll talk about even more advanced topics like adding tables to your document.

A generic function to create a table should take in the document object and integers for the number of rows and columns. The function should return a handle to the table object that was created. In Word, there's all kinds of settings that can be applied to tables - the width, border information, etc. It's better from a generic function standpoint to make the assumption that the table is going to be 100% of the screen width and every column is the same width. Other functions can be written to make adjustments later on.

Function CreateTable(doc As Variant, numRows As Integer, numCols As Integer) As Variant
   Dim lastParagraph As Variant
   Dim range As Variant
   Dim table As Variant
   Set lastParagraph = doc.Paragraphs(doc.Paragraphs.Count).Range
   Set range = doc.Range(lastParagraph.Start, lastParagraph.End)
   Call doc.Tables.Add(range, numRows, numCols)
   Set table = doc.Tables(doc.Tables.Count)
   table.PreferredWidthType = 2
   table.PreferredWidth = 100
   Set CreateTable = table
End Function

The table is inserted at the end of the document. The "PreferredWidthType" is set to 2, which means percentage. The "PreferredWidth" is set to 100, which means 100% based on the previous statement. The table that was inserted is returned.

A subroutine can be written to set the column widths. Again, since we want these to be generic, we should have this function take in a pointer to the table and an array of percentages. The function should check that the passed-in array has the same number of values as there are columns in the table. Then the percentage is set for each of the columns.

Sub SetTableColumnWidths(table As Variant, widths As Variant)
   Dim i As Integer
   Dim columns As Variant
   Dim totalColumns As Integer
   Dim column As Variant
   Dim columnNumber As Integer
   If Isarray(widths) Then
      Set columns = table.Columns
      totalColumns = Ubound(widths)-Lbound(widths)+1
      If columns.Count = totalColumns Then
         For i = Lbound(widths) To Ubound(widths)
            columnNumber = i-Lbound(widths)+1
            If widths(i) > 0 And widths(i) < 100 Then
               Set column = table.Columns(columnNumber)
               column.PreferredWidthType = 2
               column.PreferredWidth = widths(i)
            End If
         Next
      End If
   End If
End Sub

Thinking about the things that you could do with a table cell, I came up with a lot of ideas - setting background colors, changing borders, etc. All we're going to talk about here is setting text. But in order to make this as reusable as possible, it makes sense to write a private function called GetTableCell that will return a handle to a certain table cell. This function takes in a handle to the table and row number of column number parameters. Again, this is a private function in the script library - it is only used internally within the script library.

Private Function GetTableCell(table As Variant, rowNum As Integer, colNum As Integer) As Variant
   Dim cell As Variant
   Dim columns As Variant
   Dim rows As Variant
   Set cell = Nothing
   If Not table Is Nothing Then
      Set columns = table.Columns
      If colNum > 0 And colNum <= columns.Count Then
         Set rows = table.Rows
         If rowNum > 0 And rowNum <= rows.Count Then
            Set cell = table.Cell(rowNum, colNum)
         End If
      End If
   End If
   Set GetTableCell = cell
End Function

This function makes sure that the parameters are not out of bounds, and then returns a handle to the actual cell. So now, adding text to a table cell becomes a matter of getting that table cell and updating the paragraph. It's very similar to the AppendTextToDoc function described in part 1.

Function AppendTextToTableCell(table As Variant, text As String, rowNum As Integer, colNum As Integer) As Variant
   Dim cell As Variant
   Dim lastParagraph As Variant
   Dim newRangeStart As Long
   Set cell = GetTableCell(table, rowNum, colNum)
   Set lastParagraph = Nothing
   If Not cell Is Nothing Then
      Set lastParagraph = cell.Range.Paragraphs(cell.Range.Paragraphs.Count).Range
      newRangeStart = lastParagraph.End-1
      Call lastParagraph.InsertAfter(text)
      Set lastParagraph = cell.Range.Paragraphs(cell.Range.Paragraphs.Count).Range
      Call lastParagraph.SetRange(newRangeStart, lastParagraph.End)
   End If
   Set AppendTextToTableCell = lastParagraph
End Function

This function returns a handle to the text that was inserted, just like AppendTextToDoc, so you can use functions already built to do things like bold the text in the table cell.

There are all kinds of possibilities for expanding this script library. You can set font colors (one thing I'll point out is that Word uses Blue/Green/Red for the colors instead of Red/Green/Blue) or make bullet lists or numbered lists. The way we add new features to our internal script library is by recording a macro and figuring out what Word does internally, or looking at the MSDN documentation to find out the code needed to do what we want.

Hopefully these series of tips helps you get going with a MS Word script library of your own.