Advanced Topics

Viewing while building (32-bit only)
If you've ever had sit and watch the computer generate a long, complex report that took 30 minutes to build, you'll appreciate the "View while building option" This is a brand new feature in the 32-bit ddoc interface that allows the user to preview pages of a document as the document is still being created. All you have to do is set the DDOC_VIEWBUILD flag in the iOptions parameter of the dpStartDoc call and ddoc takes care of the rest. Here are some notes about how ddoc behaves when this feature is turned on: 

'- Demonstrates the use of the DDOC_VIEWBUILD flag, dpCheckAbort, 
'  and dpSetProgress. The source code presented here can be compiled 
'  by PB/CC. It requires the ddoc_p32.inc header file to compile.
'
Sub Test_Routine()
Dim hFile%
Dim e#
Dim lh!, cy!
Dim iLoop As Long
Dim iAbort As Long
Dim zText As Asciiz * 100

'- This is the amount of space I allow
'  between lines. It's arbitrary, but I
'  pick it so there will be about 6 lines
'  per inch.
'
lh! = .17
hFile% = dpStartDoc( 0, "ddoc view while building demo", "", %DDOC_INCH, _
      %DDOC_PAPER_LETTER, %DDOC_PORTRAIT, %DDOC_BIN_AUTO, _
      %DDOC_ZOOMFIT Or %DDOC_VIEWBUILD)

If hFile% < 1 Then
   Print "Error:" + Str$(hFile%)
   Print "Hit any key to continue"
   While InKey$ = "": SLEEP 1: Wend

Else

   '- Create a document with 2000 pages
   %MAX_LOOP = 2000
   For iLoop = 1 To %MAX_LOOP
      Locate 10,10
      Print "Creating Page:" + Str$(iLoop)


      '- First establish the font.
      dpFont hFile%, %DDOC_FONTNORMAL, 12, %vbBlack, "Times New Roman"
      
      '- Print some text and then print which page we're on.
      dpText hFile%, 4.25, 1.5, %DDOC_CENTER, _
         "Hello World from ddoc Print and Preview"
      dpText hFile%, 4.25, 1.7, %DDOC_CENTER, "Click the exit button"
      dpText hFile%, 4.25, 1.9, %DDOC_CENTER, "to stop this madness!"
         dpFont hFile%, %DDOC_FONTBOLD, 18, %vbRed, "Arial"
         dpText hFile%, 4.25, 3.5, %DDOC_CENTER, "Page:" + Str$(iLoop)
         
         '- Update the progress bar on the
         '  bottom of the viewer display.
         '
         If iLoop Mod 20 = 0 Then
            dpSetProgress hFile%, iLoop / %MAX_LOOP * 100
         End If
   
         '- Create a new page if we're not on the last one
         If iLoop < %MAX_LOOP Then
            dpNewPage hFile%, %DDOC_PAPER_LETTER, %DDOC_PORTRAIT, _
               %DDOC_BIN_AUTO
         End If
   
         '- See if the user aborted this operation
         If dpCheckAbort(hFile%) Then
            Print "User Aborted Document Creation"
            iAbort = %True
            Exit For
         End If
         
      Next iLoop
   
      '- If we abort, we don't want to show the document,
      '  just close and delete the file. Otherwise,
      '  the document finished creating so we show it.
      '
      If iAbort Then
         dpEndDoc hFile%, %DDOC_END_CLOSE + %DDOC_END_DELETE
      Else
         dpEndDoc hFile%, %DDOC_END_VIEW + %DDOC_END_DELETE
      End If
   End If
End Sub

Creating and calling up a preview document
As you have seen, the dpEndDoc call will end document creation and either print or preview your document. You also may have noticed that I always pass the document file name as a null string ("") in the call to dpStartDoc and add the DDOC_END_DELETE flag to the dpEndDoc function. The former means that the engine will create a temporary file to hold the document and the latter means that that temp file will be deleted after the viewer has closed. But, suppose you wanted to save the document after it has been created. A month-end report, for example, might be useful to store for future use. ddoc lets you pass the name of a file to use in dpStartDoc. As long as it is a valid file name and the file doesn't already exist (see dpStartDoc return codes), this is ok. When it comes time to complete the document and either print or view it, don't add the DDOC_END_DELETE flag. If the flag is omitted, the viewer won't delete it after it closes.

There is one standard that I would like you to follow, however. It would be best that if you name a document, you add the .DDC extension to it. If you know of another program using this extension, let me know, but for now, I've been using it and it may have significance in future versions.

If you create a document with the method above, you'll probably want to call it back up at some point. To do this, simply shell to ddoc.exe and pass it the file name on the command line. There are two command line switches that have special meaning to ddoc

  1. /P or -P tells ddoc to print the document instead of viewing it.
  2. /PA or -PA tells ddoc to print the document without showing the printer dialog box. The output will automatically go to the default printer in this case.
  3. /F tells ddoc to fax the document instead of viewing.
  4. /E tells ddoc to view the document instead of viewing.

Neither switch is case sensitive, but both must precede the file name.

E.G.
Shell "ddoc.exe /P MyDoc.ddc" Shell "ddoc.exe /PA MyDoc.ddc"

Again, the parameters must precede the file name; putting the switch at the end will not work. A final note; I provide the dpGetFileName function to obtain the name of the temp file being used if you passed the FileName parameter in dpStartDoc as a null string (""). It will fill the buffer passed with the file name being used. Remember that you must allocate space for this buffer before calling (vb and pb dynamic string users should use Space$ or String$ to get memory. Delphi users should use GetMem or an equivalent on their PChars before calling. Another way to call up a document is to run ddoc.exe without a command line. ddoc will present the user with a standard open common dialog box and allow the user to open up any .ddc file.

Creating a self-extracting document
The previous section describes how to save and then call up a ddoc document by calling ddoc.exe and passing the document on the command line. There is another way to save a document and call it up again: creating a self-viewing or self-extracting document. The dpSelfExtract function tells ddoc to take a document and append it to the ddoc.exe file. The resulting file, when executed, will display itself on the screen - without requiring the presence of ddoc.exe, ddoc16.dll, or ddoc32.dll. This document (actually an .exe file now) can be put on a floppy or emailed to anyone with a 32-bit Windows machine and they will be able to run it, thus calling up the preview window and allowing viewing/printing of the document.

You may also want to allow the user to create a self-extracting document. If you pass the DDOC_ENABLESAVE constant as part of the iOptions parameter of dpStartDoc, ddoc will turn on the Save button. This allows the user to save the current preview screen as either a self-extracting document or a .ddc document.

SMTP and MAPI E-Mail
Version 1.3 of ddoc introduced a new constant to be Or'd into the Options% parameter or dpStartDoc. This constant (DDOC_ALLOWMAPI = 4) tells the viewer to display an e-mail button right next to the Print button in the viewer's toolbar (a corresponding menu item also appears). When the user clicks this button, a MAPI e-mail window will pop up with a self-extracting version of the document as an attachment, thus making any ddoc preview document "self-emailing". All the user has to do is click the email button, fill in the recipient's email address, and click the send button. Because the attachment is a self-extracting version of the document, the recipient needs only to open the attachment (execute it because it's an .exe file) and the preview will popup on the recipient's screen - no run-time or installation required. Version 1.6 of ddoc also allows the programmer to enable SMTP (internet) email in place of MAPI email. Use the DDOC_ALLOWSMTP constant instead of DDOC_ALLOWMAPI in the iOptions% parameter of dpStartDoc to turn on this feature.

Version 1.4 of ddoc has given the programmer far more control over e-mailing documents. There is a new command-dpSetEMailOptions that allows the programmer to specify:

  • A list of e-mail recipients
  • Specify a subject and note for the e-mail.
  • Whether to show a MAPI/SMTP dialog allowing the user to add or remove recipients and change the subject/note text.
  • Whether the attached document should be in .ddc or .exe format.

A few notes about the MAPI and SMTP e-mail features are in order:

  1. The lists of recipients and their addresses are delimited by a semi-colon. You must precede each address with a transport specifier if the recipient is not a member of your local post office. For example, if I want to e-mail Dave and Troy in my office and ddickinson@usinternet.com via the internet, I would specify a list of names like this: "Dave,Troy,Don" and the list of addresses like this "Dave,Troy,SMTP:ddickinson@usinternet.com". The SMTP: is the transport specifier. You have to include this for any e-mail sent anywhere other than your local post office. SMTP: specifies the SMTP transport that is installed if you enable internet e-mail in MS Outlook. If you specify an invalid transport or forget the transport for an address that needs on, MS Outlook or Exchange will tell you there is no transport available for the address that you requested.
  2. If you call dpSetEMailOptions, the E-Mail button will be turned on even if you didn't specify DDOC_ALLOWMAPI or DDOC_ALLOWSMTP in the dpStartDoc call.
  3. Currently there is not a way to change the wording of any MAPI or FAX related messages via the dpChangeWords call. This will be available in future releases.
  4. If you e-mail a self-extracting document to someone - that document is referred to as a Second Generation Document. This means that the document isn't being viewed on the computer that created it. When you e-mail a document, it is flagged so that the e-mail, save, and fax buttons are turned off. This is to prevent people from trying to e-mail or fax a document from a system that you, the programmer are not familiar with.
  5. I have found that with MAPI email, it is best to configure your MAPI client to send attachements UUEncoded instead of mime encoded as some (notably older versions of GroupWise) have problems with some Microsoft implementations of Mime. If you use SMTP, ddoc's email client sends with a standard MIME encoding scheme. I have not run into any email clients that can't interpret this mime encoding.

Disclaimer: It is completely up to the programmer to ensure that MAPI is installed on your customer's computer correctly. I cannot take any responsibility if ddoc does not e-mail or fax correctly for your systems. It works fine on mine, but MAPI is at times a difficult thing to get working correctly.

Configuring SMTP
The new (and still officially beta) support for SMTP is self-configuring. That is, the first time the user clicks the email button, they will get a setup screen that asks them for their mail server (e.g. mail.usinternet.com), optionally allows them to change the port (defaults to the standard SMTP port - 25), and set their reply address. This information is then stored in the win.ini file. If you display the standard email dialog, there is a setup button that allows them to change their setup information. If you want to put a button in your software to display the ddoc SMTP email setup screen, see the dpSMTPOptions call in the function declarations section of this manual. This call will display the screen.

SMTP RAS Dialing
Additionally, the SMTP setup screen allows the user to specify a RAS dialer entry to connect to the internet. If they're not permanently connected to the Internet, this setting tells ddoc to first connect to the internet (if not already connected) with the Windows RAS dialer before trying to send the email. If ddoc has to dial the connection, it will also hang it up. If they're already connected, ddoc will leave them connected after sending the email.

MAPI Faxing
Faxing is almost exactly the same as MAPI e-mailing. The call to dpSetFaxOptions allows you to specify the same type of options as dpSetEMailOptoins does. You only have to provide the fax call with a list of recipients instead of names and recipients. This list needs to be delimited by semi-colons and the Name/Fax number must be separated by the @ symbol. 

dpSetFaxOptions iHandle,"Don@555-555-1212", "", "Subject", "Some Note", False
The above will tell ddoc to fax the current document without prompting the user. If you include the DDOC_END_FAX option in the call to dpEndDoc, the engine will fax the document without displaying it on the screen first. Otherwise, if you pass DDOC_END_VIEW, ddoc will turn on the fax button. When the user clicks this button, the document will be sent without prompting the user. There is one catch, however, the system will prompt the user to log into MAPI because I left the profile specification field blank. Because of this, the system will ask what profile to use. To avoid this problem, pass the profile name parameter. In my case, I would pass "Microsoft Outlook" as the profile name and it would fax without using a dialog box.

The same disclaimer that applied to e-mailing also applies to faxing. If your fax transport isn't set up correctly, the fax option might not function. To prevent problems with ddoc on a system that isn't running your software, I disable the Fax button on all e-mailed or self-extracting documents (ditto the save and e-mail buttons as explained above).

About the Sample Programs
ddoc ships with a comprehensive example program for each programming language. These examples are installed in the \ddoc\samples directory. There is a sample for each of the following languages:

  • vb 16-bit
  • vb 32-bit
  • pb/dll 1,2 16-bit
  • pb/dll 32-bit
  • pb/cc 32-bit
  • delphi 16-bit
  • delphi 32-bit

The programs are all very similar and cover most features of ddoc. Each has a selection of 6 ddoc topics. The Basics demonstrates how to initialize a preview screen and print basic text. Fancy Text demonstrates how to print text in various fonts, styles, colors, and angles. Wrapping Text demonstrates how to print paragraphs of text. Lines, Rectangles, and Bitmaps demonstrates creation of each of these graphic elements. Bookmarks and Other Fun demonstrates the use of bookmarks and page counters. Mailing Labels demonstrates the automatic creation of mailing label documents. If you have trouble following any examples in the tutorial section of this text, try looking at the code in these samples. I have also included compiled versions of all of the samples so that you can see what the output looks like right away, without having to compile them for yourself.