ddoc Print and Preview v1.9d
abstracted windows printer interface
Programmer's Manual

Version 1.9d
Copyright 1995-2003,
Don Dickinson
All rights reserved.
dickinson.basicguru.com

 

What's Installed
ddoc Print and Preview is installed via an industry standard installation program. Because you're reading this text, I'll assume that it is installed Ok. ddoc makes the following entry in your win.ini file:

[ddoc samples]
ddoc=c:\code\ddoc
It also registers the .ddc extension so that if you double-click on a .ddc file in the explorer, the file will be called up by the ddoc.exe that's located in your windows\system directory. Note that if the .ddc extension is already registered, the installation process will not overwrite what's there. For additional information on the ddoc and the registry, see the Registry section later in this text. Inside the ddoc directory, you'll find the readme.txt file that explains your license and the contents of the sub-directories. In addition, there should be a file called history.txt that contains known bugs, features that may be available in future releases, and revision history. The following sub-directories should have been created:

ddoc\samples
This directory contains one sub-directory per language supported (vb3, vb5, Delphi 16-bit, Delphi 32-bit, pb/dll 16-bit, pb/dll 32-bit, and pbcc 32-bit). Note to pb/dll users, you must provide your own copies of winapi.inc (16-bit) and win32api.inc (32-bit) in order to compile the sample programs, as these files are kind of big and I didn't want to worry about distributing them.

ddoc\lib
This directory contains the ddoc Print and Preview engine:

All 4 files may be freely distributed with your applications.

ddoc\docs
This sub-directory contains the HTML formatted manual for ddoc.

ddoc\include
This directory contains the header files for all programming languages supported:

  • ddoc_vb3.bas for vb3 (and 4-16)
  • ddoc_vb5.bas for vb5, 6 (and 4-32)
  • ddoc_p16.inc for pb/dll 1.x and 2.x
  • ddoc_p32.inc for pb/dll 5, 6, 7 and pbcc 1, 2, 3
  • ddoc_d16.pas for Delphi 1.x
  • ddoc_d32.pas for Delphi 2,3, 4, 5, 6, and 7
It also contains the ddocml.ini mailing label definition file. You will need this file if you are going to take advantage of ddoc's built-in mailing label functions.

ddoc\source
PB/DLL 6 source code for ddoc.exe, ddoc16.dll, and ddoc32.dll. If you need to recompile, please see the source files for instructions. The main files for each of the dll's and the exe are ddoc.bas (for ddoc.exe), ddoc16.bas (ddoc16.dll) and ddoc32.bas (ddoc32.dll). Note that you must own Power Basic DLL compiler v6 or 7 (or v2/1.x for 16-bit) to recompile the source (go to www.powerbasic.com). The source for ddoc_jpg.dll is also included. This source requires Delphi 6 to compile and consists only of ddoc_jpg.dpr and u_jpg.pas. Questions about the source code will be answered (at my discretion and if time permits) via e-mail - don@greatwebdivide.com.
Note: source code is included with the registered version only.

windows\system
The installation process also puts the 4 ddoc library files in your windows\system directory (Win95-98) or in your windows\system32 directory (Win NT).
Note: The vb3 and vb5 sample programs require their respective runtime libraries be present as they are not provided with the demo. If you don't own vb3 or vb5, you won't be able to execute their exe's without obtaining the runtimes.

Distribution and Support
Purchasing ddoc allows you the right to freely distribute ddoc.exe, ddoc_jpg.dll, ddoc16.dll, and ddoc32.dll. If you have a 16-bit program, you need to give out ddoc16.dll, ddoc32.dll, and ddoc.exe. For 32-bit programs, you only need distribute ddoc32.dll and ddoc.exe. ddoc includes source code (see above). You only need to distribute ddoc_jpg.dll if your program needs jpg support (via the dpAddGraphic command). You may not under any circumstances distribute, publish, or sell the source to ddoc. It is for your use only. I provide it for the express purpose of allowing the user to modify and recompile it to suit their needs and distribute the compiled result royalty-free with their applications. Any other use is strictly forbidden.

ddoc header files may not be distributed or published in any form except as part of the tryddoc.exe evaluation package. Support for ddoc is provided via e-mail - don@greatwebdivide.com. I respond as quickly as possible, but if I get stuck out of town it can be a few days before I get back to you. Information on obtaining the latest versions is available on my web-site: dickinson.basicguru.com

More than just print and previewing
ddoc Print and Preview is now much more than just a Print and Preview engine. It is capable of saving out it's preview screen as either a native .ddc file or a self-extracting .exe file. This feature is sort of like Adobe Acrobat®. You can save out the .ddc files and call them up on the screen any time you wish. All you need to call them back up is the viewer - ddoc.exe. Because .ddc files may be distributed to someone who doesn't own ddoc.exe, I allow anyone to download and install ddoc.exe on their computer. You can feel free to link to this program from my web-site.

This file is an install program that installs ddoc.exe in the user's windows\system directory and registers the file extension, .ddc, in the registry automatically. Your end-users can give this installation to anyone who wishes to print and view .ddc documents.

Summary of features

  • Allow the programmer to write one routine to create a document for either printing or previewing.
  • Drawing calls are provided to print Text, .bmp graphics, Angled Text, Paragraphs of Text, Lines, and Rectangles.
  • Each page can be a different size and orientation. Pages may be printed to different paper bins in the printer.
  • Pages may have one or more "bookmarks" in them. A list of bookmarks will be displayed at the top of the viewer; if the user clicks on the bookmark in the list, the viewer will jump directly to the page the bookmark refers to.
  • Documents can be previewed, printed, stored out and recalled, or deleted automatically after viewing.
  • The ability for a document to stand on its own-creation of a self-extracting document-basically a document with an embedded viewer.
  • ddoc is thread safe-as many as 20 different documents can be created simultaneously by one program.
  • Mailing label generation calls are included for printing mailing labels easily (without calculating page positions) via a preset template. A function is even provided to print a sample sheet of labels from a template.
  • The viewer itself is a 32-bit application so use of this engine requires NT4 or Win9x. But it has both a 16-bit and 32-bit call interface that are identical- the engine can be access from either a 16-bit or a 32-bit program (via ddoc16.dll or ddoc32.dll, respectively).
  • Header files are included for PB/DLL 1x, 2, 5, 6, PB/CC 1, 2, VB 3, 4, 5, 6, and Delphi 1, 2, 3, 4, 5.
  • Faxing and Email of documents on MAPI-compliant system.
  • EMail on an internet enabled PC via SMTP and optionally utilizing RAS dialup.

Getting Started With ddoc Print and Preview
ddoc gives a Windows Programmer an abstracted print and print preview API. This small engine is designed to replace the VB3,4,5 printer object, the Delphi TPrinter object, and any other less powerful print or preview engines provided with programming languages. Power Basic PBDLL programmers will especially benefit because their language provides no printer support save going directly through the Windows API.

The idea of ddoc is to allow the programmer to construct one routine to print or preview a document. Pass one parameter letting the ddoc engine know whether s/he is printing or previewing the document. What happens behind the scenes is akin to creating a Windows Metafile - as you make calls to the ddoc32.dll library, these calls are recorded and stored in a proprietary document file. It is important (especially for those used to printing from DOS) to remember that ddoc is page oriented, not line oriented. This means that the programmer is responsible for telling the engine where to print on the page and maintaining their current position on the page. This is a very powerful concept as it allows the programmer to draw text at any place on the page and in any order. After completing a page, call dpNewPage to start the next page or dpEndDoc to end the document and either preview or print it. The dpEndDoc call initializes the actual print engine which either displays or prints the document. The following is a short VB skeleton program: 

Dim hFile as Integer


'- Initialize the viewer. Give it a title. The third parameter contains the
'  name of the temporary file in which the document will be stored. Since a 
'  null string is passed, the viewer will create a unique temp file for the
'  document. If you have the urge to know what the document is called,
'  see the dpGetFileName function. Other parameters tell the engine that
'  all calls will be made in inches (as opposed to the centimeter option),
'  that the document's first page will be portrait, and that the display 
'  engine should come up and zoom the first page to fit in the viewer's 
'  maximized window.
'
hFile = dpStartDoc (0, "Title", "", DDOC_INCH, DDOC_PAPER_LETTER, _
DDOC_PORTRAIT, DDOC_SYSTEM_DEFAULT, DDOC_ZOOMFIT)
if hFile < 1 then
   MsgBox "Error initializing the document:" + str$(hFile)
else
   '- Document is started, first thing to do is always set
   '  the font specs. (Blue, bold, 11 point, arial).
   '
   dpFont hFile, DDOC_FONTBOLD, 11, vbBlue, "Arial"
   
   '- Now print some text to the viewer

   dpText hFile, .5, .75, DDOC_LEFT, "Left Aligned Text, at (.5, .75)"
   
   '- End the document telling the engine to display the
   '  the document on the screen. Also, the delete flag
   '  is set, telling the display engine to delete the 
   '  temporary file that the document is stored in when
   '  the user exits the document. Note, that the document
   '  can be redisplayed (if not deleted) by passing the
   '  name of the document on the command line to ddoc.exe
   '
   dpEndDoc hFile, DDOC_END_VIEW or DDOC_END_DELETE
end if
Ok, the code above isn't so bad - most of the lines are comments! But, it gives you an idea of how the engine works:
  1. Call dpStartDoc to initialize the document and save it's return value for future reference.
  2. Set the font specs after the initial call.
  3. Draw some text
  4. End the document with dpEndDoc. dpEndDoc tells the engine what you wish to do with the document. Currently, you can view it, print it with or without a dialog box, email with or without the system prompting for recipients, and fax with or without the system prompting for recipients.