The tabular report
A typical use for the print/preview engine is to print a report from a database. Suppose, for example, we wish to print a list of phone numbers and e-mail addresses for customers. ddoc will help you do this job with ease. For example, the following routine will loop through a database and print the names and phone numbers in it.

If I were to use dpText for all columns of a report, there is a chance that if the text in one column were too long, it would run over into the next column. Remember that dpText doesn't care how long the text is; it prints all the way over to the edge of the page if there is enough text. This is where you would use dpClipText. I use it below for the Name field. The name field is unable to run over into the phone field on the page because is clipped off before it gets that far. dpClipText can be very handy when you don't want to bother wrapping text and you think it might not fit in the column width that you have available.
Note: This is for example purposes only, I don't provide the actual data access routines. Unfortunately, you can't copy this code into vb and run it without providing the GetDBField$(iRecord&, sField$) function.

Sub PrintMailingList()
   
   Dim hPreview%
   Dim cy!     ' This variable keeps track of the Y position on the page.
   Dim lh!     ' This is the line-height or space between lines
   Dim c!(1 to 5) ' This array will contain column positions

   lh! = .1667 ' 6 lines per inch

   '- Define our column positions
   c!(1) = .5
   c!(2) = 1
   c!(3) = 4
   c!(4) = 5
   c!(5) = 6

   '- Start creating the Preview document
   hPreview% = dpStartDoc( . . . )
   if hPreview% < 1 then
      MsgBox "Can't initialize the print engine. Status =" + str$(hPreview)
   else
      '- Print the page header
      gosub print_header

      '- Loop through all records in the database.
      For iLoop& = 1 to NumberOfRecords&
         
         '- Check for the end of a page (if we are printing
         '  more than 10 inches down on the page, we need
         '  a new one).
         '
         if cy! > 10 then
            dpNewPage hPreview%, DDOC_PAPER_LETTER, DDOC_PORTRAIT, _                
                  DDOC_BIN_UPPER
            gosub print_header
         end if
         
         '- Print the columns of text
         dpText c!(1), cy!, DDOC_LEFT, GetDBField$(iLoop&, "ID")
         dpClipText c!(2), cy!, c!(3) - c!(2) - .1, DDOC_LEFT, _
         GetDBField$(iLoop&, "Name")
         dpText c!(3), cy!, DDOC_LEFT, GetDBField$(iLoop&, "Phone")
         dpText c!(4), cy!, DDOC_LEFT, GetDBField$(iLoop&, "Fax")
         dpText c!(5), cy!, DDOC_LEFT, GetDBField$(iLoop&, "E-Mail")
         cy! = cy! + lh!            
      Next iLoop&
   end if
exit sub

print_header:

   '- Print a title on the top of the page
   cy! = .5
   dpFont hPreview, DDOC_FONTBOLD, 12, vbBlack, "Times New Roman"
   dpText hPreview, 4.25, cy!, DDOC_CENTER, "Customer Listing"
   
   '- Print the column headings
   dpFont hPreview, DDOC_FONTUNDERLINE, 10, vbBlack, "Times New Roman"
   cy! = cy! + 2 * lh!
   dpText hPreview, c!(1), cy!, DDOC_LEFT, "ID"
   dpText hPreview, c!(2), cy!, DDOC_LEFT, "Customer Name"
   dpText hPreview, c!(3), cy!, DDOC_LEFT, "Phone"
   dpText hPreview, c!(4), cy!, DDOC_LEFT, "Fax"
   dpText hPreview, c!(5), cy!, DDOC_LEFT, "E-Mail"

   '- Set the font and Y position on the page
   '  so we're ready to print the columns of text.
   '
   cy! = cy! + 1.5 * lh!
   dpFont hPreview, DDOC_FONTNORMAL, 10, vbBlack, "Times New Roman"
   return

End Sub

'- This tells ddoc to set 3 tab stops …
'  The first one is Left aligned at 1" over with a max width of 2 inches
'  The next is right aligned at 4" over with a maximum width of 1 inch
'  The final tab-stop is left aligned 4.1 inches over and will print
'  until it runs out of space on the page (no maximum width)
'
sTabStops = "L1W2 R4W1 L4.1"
dpSetTabs hPrev, sTabStops

'- Printing the text at the tab-stops is a matter of calling
'  the dpTabText call telling it how far down on the page to print,
'  and passing it the columns separated by a tab character. 
'
CurrentY = 3.2  'The Y position on the page
dpTabText hPrev, CurrentY, "Col 1" + chr$(9) + "Col 2" + chr$(9) + "Col 3"

'- The code below will print angled text that prints
'  at 270 degrees (straight down) along the right
'  side of letter sized paper. Note that is will
'  print in a Blue, 10-point Arial font.
'
dpFont hPreview, DDOC_FONTNORMAL, 10, vbBlue, "Arial"
dpAngleText hPreview, 8, .75, 270, "This is some text"

Sub PrintTextFile (fileName$)
   
   Dim hFile%, hPreview%
   Dim iLeft&, iPrinted&
   Dim Start!
   Dim sInput$

   '- The code below opens a file for
   '  sequential access. If there's an
   '  error, we bail.
   '
   On Error Resume Next
   hFile% = FreeFile
   Open fileName$ For Input As #hFile%
   
   If Err Then
      MsgBox "Unable to open the text file: " + fileName$
      Exit Sub
   End If
   On Error GoTo 0

   '- Init the ddoc print engine, bail if failed
   hPreview% = dpStartDoc(0, "Test file printing", "", DDOC_INCH, _
  DDOC_PAPER_LETTER, DDOC_PORTRAIT, _
               DDOC_BIN_UPPER, DDOC_ZOOMFIT)
   If hPreview% < 1 Then
      MsgBox "Can't initialize the print engine. Status =" + Str$(hPreview%)
      Exit Sub
   End If

   '- Loop through the text file
   Start! = 1  ' we start printing at 1" down on the page
   Do Until EOF(hFile%)
      
      '- Get the first paragraph
      Line Input #hFile%, sInput$
      iLeft& = Len(sInput$)
      Debug.Print sInput$
   
      Do
         dpFont hPreview%, DDOC_FONTNORMAL, 10, vbBlack, "Times New Roman"
         
         '- Tell the engine to print the current paragraph within
         '  the boundaries of the page (1 inch margins on 8.5x11 paper).
         '  Also, the .1667 parameter tells the engine to print each line
         '  .1667 inches apart (6 lines per inch). Remember, it returns
         '  the actual number of characters printed. By subtracting the
         '  number printed from the number in sInput$, we know when all
         '  text has been printed. The variable Start! Keeps track of
         '  where we are on the page.
         '
         iPrinted& = dpWrapText(hPreview%, 1, Start!, 7.5, 10, .1667, sInput$)
         sInput$ = Mid$(sInput$, iPrinted& + 1)
         iLeft& = iLeft& - iPrinted&
    
         '- If there are characters left to print, it means that we need
         '  to go on to the next page. Otherwise, we need to keep track
         '  of where we left off so we can continue printing the next
         '  paragraph.
         '
         If iLeft& > 1 Then
            dpNewPage hPreview%, DDOC_PAPER_LETTER, DDOC_PORTRAIT, _
                  DDOC_BIN_UPPER
            Start! = 1
         Else 
            
            '- The new starting position is the last one
            '  plus the total height of the lines that
            '  we just printed.
            '
            Start! = Start! + dpWrapCount(hPreview%) * .1667
            Exit Do
         End If
      Loop
      
      '- Get the next paragraph if we're not at the end of the file.
   Loop
   Close #hFile%
   dpEndDoc hPreview%, DDOC_END_VIEW + DDOC_END_DELETE

End Sub

'- This prints a 1 point horizontal line in the color red.
'  The line is one inch down on the page and runs from
'  one inch over to 7.5 inches over on the page.
'
dpLine hPreview%, 1, 1, 7.5, 1, 1, vbRed

'- The following prints a rectangle with a blue 
'  border filled with the color red. The border is 
'  three points wide. The rectangle fills a rectangle 
'  defined by upper-left = (1,1) and lower-right = (3,2)
'
dpRect hPreview%, 1, 1, 3, 2, 3, vbRed, vbBlue

'- The following prints an ellipse a shaded background with no border.
dpEllipse hPreview%, 1, 1, 3, 2, -1, &hE0E0E0, 0

'- The following prints a pie with a blue 
'  border filled with the color red. The border is 
'  three points wide. The bounding rectangle is (1,1)(3, 2)
'  It starts at 45 degrees and ends at 180 degrees
'
dpPie hPreview%, 1, 1, 3, 2, 45, 135, 3, vbRed, vbBlue

'- This prints an arc shaped like a U. 
'  the line will be as thin as possible (w = 0)
'  and will be black.
'
dpArc hPreview%, 1, 1, 3, 2, 180, 180, 0, vbBlack

'- The following will print logo.bmp in the upper-left 
'  corner of the viewer window in a box defined by the 
'  points (1,1) and (3,2).
'
dpGraphic hPreview, 1, 1, 3, 2, "c:\mygraph.bmp"

'- or using embedding the graphic
dpEmbedGraphic hPreview, 1, 1, 3, 2, "c:\mygraph.bmp"

'- or using a referenced bitmap.
hGraphic = dpAddGraphic(hPreview, "c:\mygraph.bmp")
if hGraphic then
  dpDrawGraphic(hPreview, hGraphic, 1,1,3,2)
end if