Core Functions

ddoc Print and Preview Engine Function Reference
Below is a list of routines in ddoc32.dll. All calls are referenced for VB 5 users. If you are using another language, please see below:
  • Power Basic PB/DLL, PB/CC users Mostly, VB5 uses the same type of variables, the only significant difference is that the when passing a string to a dll. In VB, string parameters are usually declared as ByVal myString as String. This should be an ASCIIZ variable in pb/dll or pb/cc. Please see the header files for the exact declarations of specific functions.
  • Delphi users I use vb's suffix identifiers to tell what types my variables are. % indicates a SmallInt (16-bit), & indicates a LongInt, ! indicates a Single, # is a Double, ByVal $ is a PChar. Please see ddoc_d16.pas and ddoc_d32.pas (the delphi header files) for examples of how the various functions are declared.

dpAddGraphic

Declare Function dpAddGraphic Lib "ddoc32.dll" 
   ( ByVal iHandle%, ByVal zFileName$ ) as Long

This function embeds a bitmap (.bmp), jpeg (.jpg/.jpeg), or enhanced metafile (.emf) in the ddoc document. Once embedded, it can be printed to any page with the dpDrawGraphic command. dpDrawGraphic combined with dpAddGraphic provide all of the functionality of dpEmbedGraphic with one huge advantage - with dpAddGraphic the file is stored in the document only once. It can be drawn many times, but is only stored in the file once. This saves a huge amount of file space for documents which print the same graphic over and over (as with logos that are printed on every page). If you plan on allowing emailing documents, this provides the capability of dpEmbedGraphic without taking as much space. I intend this function combined with dpDrawGraphic to replace dpEmbedGraphic. Please use this combination instead of dpEmbedGraphic. To use this function, call it and save it's return value. It's return value can be passed over and over again to the dpDrawGraphic command to print the bitmap/metafile to the page.
IMPORTANT In order to add a .jpeg file to the document, the file ddoc_jpg.dll must be available! This file is not required by ddoc32.dll to function, but any attempt to add a jpeg file will fail unless ddoc32.dll can find this file. I recommend putting ddoc_jpg.dll in the same directory as ddoc32.dll. Note that if you're not using jpeg files, then you do not need to distribute ddoc_jpg.dll

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
zFileName$ The name of a bitmap or metafile to embed in the document. This must be a windows bmp.

Return Value Description
>0 This is a handle or reference to the graphic that can be passed to dpDrawGraphic (used to display the bitmap/metafile)
0 The graphic file was invalid, couldn't be opened, or doesn't exist.

dpAngleText

Declare Sub dpAngleText Lib "ddoc32.dll" 
   ( ByVal iHandle%, ByVal x!, ByVal y!, _
     ByVal iAngle%, ByVal zText$ )

This function outputs text on an angle from 0 to 360 degrees at the specified coordinates. For example, printing at 90deg prints the text straight up from the coordinates, 180deg prints upside-down, etc.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
x!, y! The x and y coordinates in either inches or cm (see dpStartDoc iUOM parameter)
iAngle% The angle to print the text (0 = normal, 90 = straight up, etc counter-clock-wise)
zText$ The text to print

dpArc

Declare Sub dpArc Lib "ddoc32.dll"  _
      ( ByVal iHandle%, _
        ByVal x!, ByVal y!, _
        ByVal x2!, ByVal y2!, _
        ByVal aStart!, ByVal aEnd!, _
        ByVal w!, ByVal iColor&)

This functions draws an arc that is part of an imaginary circle bounded by the rectangle defined as (x, y) (x2, y2). The line used to draw it is w! inches/cm wide and is iColor& color. The arc starts at an angle of aStart! degrees and ends aEnd! degrees counter-clockwise from where it starts.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
x!, y! The x and y coordinates of the upper left corner of the arc's circle's bounding rectangel
x2!, y2! The x and y coordinates of the lower right corner of the arc's circle's bounding rectangel
aStart!, aEnd! aStart! is the angle that determines the start of the arc. The arc ends aEnd! degrees from where it starts. If you want to print an arc from 45-180 degrees, start=45deg and end=135.
w! Width of the arc's pen.
iColor& Color of the pen used to draw the arc's line.

dpBookmark

Declare Sub dpBookmark Lib "ddoc32.dll" _
   ( ByVal iHandle%, ByVal zBookmark$ )

dpBookmark tells the preview engine to add the zBookmark text to a list of "bookmarks" referencing the current page. These bookmarks are displayed in a drop-down list at the top of the print-preview screen. If the user clicks on an item in the bookmark list, the preview engine jumps to the page referred to by the bookmark. Bookmarks are completely optional - if your document contains none, the viewer even hides the drop-down list. Every page doesn't have to be referenced by a bookmark and more than one bookmark can be assigned to one page.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
zBookmark$ The name of the bookmark - this will be displayed in a drop-down list by the display engine.

dpChangeWords

Declare Sub dpChangeWords Lib "ddoc32.dll" _
   ( ByVal iHandle%, ByVal iWhich%, ByVal sText$ )

dpChangeWords allows the program to customize the text in the ddoc viewer window (Handy for changing the text on applications that aren't being used in English speaking countries). All words displayed by the viewer can be displayed. These include all button hints, menu items, zoom fit settings, password dialog text, jump dialog text, etc. This call should be made during the construction of the first page. I suggest calling it right after dpStartDoc.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
iWhich% The constant that tells the viewer which words you are going to change. E.g. DDOC_BTN_OK, DDOC_WORD_ZOOMFIT, DDOC_MENU_FILE, etc. (See Appendix A for a full list of constants)
sText$ The word's new text

dpCheckAbort (32-bit only)

Declare Function dpCheckAbort Lib "ddoc32.dll" ( ByVal iHandle% ) as Long

This function is available on in the 32-bit version of the ddoc interface. When the DDOC_VIEWBUILD flag is set, that is, when you are allowing the user to preview the document while it is still being built, this function can be used to see if the user closed the viewer. If the user has closed the viewer, this will return non-zero otherwise it will return zero. If you use DDOC_VIEWBUILD, you should check this frequently. If you don't, your document will continue to build and will be displayed again when it finished creation. If dpCheckAbort is non-zero, you should jump out of your document creation routine and call

dpEndDoc iHandle, DDOC_END_CLOSE + DDOC_END_DELETE
to terminate the document.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc

Return Value Description
0 The view is still opened.
<>0 The viewer has been closed so you should cancel the document build.

dpClipText

Declare Sub dpClipText Lib "ddoc32.dll" _
   ( ByVal iHandle%, ByVal x!, ByVal y!, _
     ByVal w!, ByVal iAlign%, ByVal sText$)

This function words like dpText, except that it allows the programmer to specify a maximum width for the text (w!). It crops the text so that it fits within the specified maximum width.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
x!, y! The starting point for the text
w! The maximum width for the text
iAlign% How to align the text (DDOC_LEFT, etc.)
sText$ The text to print

dpDuplex

Declare Sub dpDuplex Lib "ddoc32.dll" _
   ( ByVal iHandle%, ByVal iHow& )

This sub specifies that the program should duplex when printing. Only turn this on if you know the output device had duplex ability. If it is set, the user will not be able to override it and turn it off (like the orientation) so use with care.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
iHow& Either DDOC_DUPLEX_HORIZONTAL or DDOC_DUPLEX_VERTICAL

dpDrawGraphic

Declare Function dpDrawGraphic Lib "ddoc32.dll" 
   ( ByVal iHandle%, ByVal hGraphic&, _
     ByVal x!, ByVal y!, ByVal x2!, ByVal y2! ) as Long

This function draws a graphic that was embedded in the document with dpAddGraphic. The hGraphic& parameter is a handle to an already embedded graphic as returned by dpAddGraphic. Like dpEmbedGraphic and dpGraphic, this command draws a bitmap or metafile to the page and fits it in the rectangle defined by the coordinates (x!, y!) and (x2!, y2!). The function returns True (non-zero) if the hGraphic& and iHandle% handles are valid; otherwise it returns False (zero).

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
hGraphic& A handle to a graphic embedded in a document with the dpAddGraphic command. dpAddGraphic returns this handle.
x!, y! The coordinates of the upper-left corner of the bounding rectangle in which to print the bitmap/metafile.
x2!, y2! The coordinates of the lower-right corner of the bounding rectangle in which to print the bitmap/metafile.

Return Value Description
<>0 Success
0 Failure. Either the iHandle% or hGraphic& parameter is invalid.

dpEllipse

Declare Sub dpEllipse Lib "ddoc32.dll" _
   ( ByVal iHandle%, ByVal x!, ByVal y!, _
     ByVal x2!, ByVal y2!, ByVal w!, _
     ByVal iFillColor&, ByVal iBorderColor& )

This function prints an ellipse/circle filling the coordinates (x,y) - (x2,y2). W refers to the width of the bordering line and may be passed as -1 if you don't want a bordering line (in that case, the iBorderColor& parameter will be ignored.) iFillColor indicates the color with which to fill the rectangle. Note that in some sample programs I define a constant LIGHT_SHADE. This is a very light shade of grey suitable for printing text upon. If you want to print text on top of a ellipse, make sure that you print the ellipse first, and then print the text. If you print the text first, the ellipse will draw over the top of the text. At this time, there is no way to print a transparent ellipse.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
x!, y! The starting coordinate of the rectangle (upper-right) that bounds the ellipse in inches or cm
x2!, y2! The ending coordinate of the rectangle(lower left) that bounds the ellipse in inches or cm
w! The width of the bordering line given in Points. 0 means a hairline - printed as the thinnest line possible on the output device. -1 means don't draw a line around the ellipse.
iFillColor& The color with which to fill the background of the ellipse.
iBorderColor& The color of the border. This is ignored it w! is passed as -1.

dpEmbedGraphic

Declare Function dpEmbedGraphic Lib "ddoc32.dll" _
   ( ByVal iHandle%, ByVal x!, ByVal y!, _
     ByVal x2!, ByVal y2!, ByVal zFileName$  ) as Integer

This routine tells the display engine to draw the graphic file passed inside of the rectangle defined by (x,y)-(x2,y2). It will squish the graphic proportionally so it fits inside of the rectangle. The graphic file must be a bitmap (mono, 16, 256, 16million, etc. all supported) or enhanced metafile (.emf). The difference between this function and dpGraphic is that dpEmbedGraphic creates a copy of the graphic file in your temp file. If you are enabling MAPI e-mail or are not deleting the temp file after creation (see dpEndDoc), you should use this function for all graphic work instead of dpGraphic. Since this method consumes more disk space and is slower than dpGraphic, you should try to use RLE encoded bitmaps instead of regular bitmaps wherever possible. This will decrease document size and speed up the display of the graphic file.

This function returns True (-1) if the file was embedded or false if an error occurs (couldn't find / open / append the .bmp file specified)

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
x!, y! The coordinates of the upper-left corner of the bounding rectangle in which to print the bitmap/metafile.
x2!, y2! The coordinates of the lower-right corner of the bounding rectangle in which to print the bitmap/metafile.
zFileName$ The name of the graphic to embed and display

Return Value Description
<>0 Success
0 Failure. Couldn't find / open / append the .bmp file specified.

dpEndDoc

Declare Sub dpEndDoc Lib "ddoc32.dll" _
   ( ByVal iHandle%, ByVal iOptions% )

This routine tells the display engine that you are done creating your document. The iOptions% parameter lets the engine know what you want to do with the document. You can:

  1. display it on the screen in a preview window
  2. print it directly to the printer
  3. store it in a file without displaying or printing it
  4. e-mail the document via mapi mail
  5. fax the document via mapi fax

Also, the DDOC_END_DELETE flag may be set. This tells the viewer to delete the document after the viewer closes. To abort a document (if the user presses your "cancel" button) pass DDOC_END_DELETE + DDOC_END_CLOSE. This tells the display engine not to print or view the document and to delete it immediately.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
iOptions One of the following constants:
  • DDOC_END_PRINT
  • DDOC_END_VIEW
  • DDOC_END_CLOSE
  • DDOC_END_EMAIL
  • DDOC_END_FAX
  • DDOC_END_PRINT_NODIALOG
  • DDOC_END_SPECIFIC_PRINTER
Optionally, add in DDOC_END_DELETE to kill the document after viewing, printing, e-mailing, faxing, or closing

dpEndDoc

Declare Sub dpEndDocInst Lib "ddoc32.dll" as long

This function returns the PID (process id as returned by the shell to ddoc.exe via the pbdll "shell" command) of the last call to dpEndDoc. Note that this function is not thread-safe as it does not take an hFile% parameter. If you're using it in a multi-threaded app, it would be safest to place this together with it's associated dpEndDoc call inside a critical section or mutex.

dpFont

Declare Sub dpFont Lib "ddoc32.dll" _
   ( ByVal iHandle%, ByVal iStyle%, _
     ByVal Size!, ByVal iColor&, _
     ByVal zFontName$  )

dpFont tells the print engine which font you want to use with subsequent calls to dpText, dpClipText, dpAngleText,and dpWrapText. The font information must be specified immediately after each call to dpNewPage and dpStartDoc. The style flag DDOC_FONTBASELINE tells the viewer to align subsequent text calls to the baseline of the text instead of the top of the text.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
iStyle% Font Style constant - can be combined bit-wise (or'ed) - DDOC_FONTNORMAL, DDOC_FONTBOLD, DDOC_FONTITALIC, DDOC_FONTUNDERLINE, DDOC_FONTSTRIKEOUT, DDOC_FONTBASELINE
size! The size of the font in Points
color&! The color of the font
zFontName$ Name of the font

dpFontSpacing

Declare Sub dpFontSpacing Lib "ddoc32.dll" 
   ( ByVal iHandle%, ByVal dblSpacing# )

This function allows the user to control the spacing of individual letters in all text calls following it on the page. After each call to dpNewPage, this is reset to zero. The dblSpacing# parameter is expressed in Points. 72 points equals one inch. To add a little extra space to text, add .5 points or so. To condense the font, pass the parameter as negative. Note that the text will not be very readable if you pass a negative number smaller than -.5. E.g. dpFontSpacing hPrev, -3 will cause the letters to run severly on top of each other at 10 point. Note: dpWrapText and dpWrapContinue reset the extra font spacing to zero. You cannot print wrapped text with extra spacing at this time.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
dblSpacing# The amount of extra space to put after each letter; expressed in points.

dpGetMajorVersion

Declare Function dpGetMajorVersion Lib "ddoc32.dll" as Long

This function returns the major version of ddoc. E.G. if ddoc is version 1.4, this call will return 1

dpGetMinorVersion

Declare Function dpGetMinorVersion Lib "ddoc32.dll" as Long

This function returns the minor version of ddoc. E.G. if ddoc is version 1.4, this call will return 4

dpGetPrinter (32-bit only)

Declare Function dpGetPrinter Lib "ddoc32.dll" _
   ( ByVal iIndex as Long ) as String

Pass this routine the number of the printer (from 1 to dpPrinterCount) and it returns the name of the printer. The name of the printer can then be passed to dpSpecifyPrinter to specify an output printer. VB and PB users should call this function. Delphi and C programmers will probably want to use dpGetPrinterZ as it returns a string pointer instead of an Ole string.

Parameter Description
iIndex The index of the printer (from 1 to dpPrinterCount)

Return Value Description
string value Printer corresponding to index. Empty string if invalid index.

dpGetPrinterZ (32-bit only)

'- PB declaration
Declare Function dpGetPrinterZ Lib "ddoc32.dll" Alias "dpGetPrinterZ" _
   ( ByVal iIndex as Long ) as DWORD

Pass this routine the number of the printer (from 1 to dpPrinterCount) and it returns the name of the printer as a null-string pointer. The name of the printer can then be passed to dpSpecifyPrinter to specify an output printer. VB and PB users should use dpGetPrinter instead because it returns a native string. Delphi and C users should use this function as it returns a pointer to the printer name.

Parameter Description
iIndex The index of the printer (from 1 to dpPrinterCount)

Return Value Description
zero terminated string Printer corresponding to index. Nul if invalid index passed.

dpGraphic

Declare Sub dpGraphic Lib "ddoc32.dll" _
   ( ByVal iHandle%, ByVal x!, ByVal y!, _
     ByVal x2!, ByVal y2!, ByVal zFileName$ )

This routine tells the display engine to draw the graphic file passed inside of the rectangle defined by (x,y)-(x2,y2). It will squish the graphic proportionally so it fits inside of the rectangle. The graphic file must be a bitmap (mono, 16, 256, 16million, etc. all supported) or an enhanced metafile.

Unlike dpEmbedGraphic, this routine simply tells the print engine where to find the bitmap/metafile. You should not use this function is you have MAPI email enabled or if you aren't deleting the temp file when you're done with it. If you're simply printing or previewing, use this function as is faster and consumes less disk space than dpEmbedGraphic does.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
x!, y! The starting coordinate of the bounding rectangle (upper-right) in inches or cm
x2!, y2! The ending coordinate of the bounding rectangle(lower left) in inches or cm
zFileName$ The file name (including path) of the graphic to print

dpIsPrinter (32-bit only)

Declare Function dpIsPrinter Lib "ddoc32.dll" _
   ( ByVal sPrinter as String ) as Long

This function takes the name of a printer and returns non-zero if the printer is installed on the system. If not, it returns zero.

Parameter Description
sPrinter Name of the printer as returned by dpGetPrinter or dpGetPrinterZ

Return Value Description
<> 0 The printer name is valid on this computer.
0 The printer name is not valid on this computer.

dpLine

Declare Sub dpLine Lib "ddoc32.dll"  _
   ( ByVal iHandle%, ByVal x!, ByVal y!, _
     ByVal x2!, ByVal y2!, ByVal w!, _
     ByVal c As Long   )

This function prints a line connecting the given coordinates (upper left, lower right). The w parameter, specifies how wide the line should be in Points. If it is passed as 0, the line printed will be a hairline - the smallest line the output device can print. The color of the line is specified in the c parameter.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
x!, y! The starting coordinate of the line (upper-right) in inches or cm
x2!, y2! The ending coordinate of the line (lower left) in inches or cm
w! The width of the line given in Points. 0 means a hairline - printed as the thinnest line possible on the output device
c& The color of the line

dpNewPage

Declare Sub dpNewPage Lib "ddoc32.dll"
   ( ByVal iHandle%, ByVal iPaper%, _
     ByVal iOrient%, ByVal iBin% )

dpNewPage is called any time that you wish to start a new page. It takes parameters to tell the print/preview engine (ddoc.exe) what the paper size, orientation, and preferred printer bin of the next page should be. ddoc allows each page to be a different size and orientation and also allows printing each page to a different printer bin. Remember that the size, orientation, and bin of the first page is set by parameters in dpStartDoc.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
iPaper% Paper size constant - see the DDOC_PAPER_xxx constants. This can also be DDOC_SYSTEM_DEFAULT to leave the paper size unspecified. It can be DDOC_PAPER_CUSTOM, but you must call dpPaperSize to specify the size of the paper. And it may be DDOC_SAME_AS_FIRST, indicating that the paper should be the same as that specified in dpStartDoc.
iOrient% Paper orientation: DDOC_PORTRAIT, DDOC_LANDSCAPE, DDOC_SYSTEM_DEFAULT, or DDOC_SAME_AS_FIRST
iBin% Paper bin to print to - see the DDOC_BIN_xxx constants, DDOC_SYSTEM_DEFAULT, or DDOC_SAME_AS_FIRST

dpPageCount

Declare Sub dpPageCount Lib "ddoc32.dll"  _
   ( ByVal iHandle%, ByVal x!, ByVal y!, _
     ByVal iAlign%, ByVal iAngle% )

This function automatically prints the number of pages in the document at the specified position on the page. It is useful because the programmer will not usually know how long the document will be when printing the first pages of a lengthy report.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
x!, y! The x and y coordinates in either inches or cm (see dpStartDoc iUOM parameter)
iAlign% How to align the text (see alignment constants). This is ignored (and assumed DDOC_LEFT), if an angle is specified.
iAngle% The angle to print the text (0 = normal, 90 = straight up, etc counter-clock-wise)

dpPageNo

Declare Sub dpPageNo Lib "ddoc32.dll"  _
   ( ByVal iHandle%, ByVal x!, ByVal y!, _
     ByVal iAlign%, ByVal iAngle% )

This function automatically prints the current page number at the specified position on the page. It is a number one thru the number of pages in the document.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
x!, y! The x and y coordinates in either inches or cm (see dpStartDoc iUOM parameter)
iAlign% How to align the text (see alignment constants). This is ignored (and assumed DDOC_LEFT), if an angle is specified.
iAngle% The angle to print the text (0 = normal, 90 = straight up, etc counter-clock-wise)

dpPageOffset

Declare Sub dpPageOffset Lib "ddoc32.dll"  _
   ( ByVal iHandle%, ByVal iPage& )

If you call this function and pass it a value > 0 for iPage&, then the value passed will be added to the current page. This makes it possible, for example by calling dpPageOffset(iHandle%, 49), start page numbering at page 50 instead of page 1. This is a global settings. You can call it anywhere between dpStartDoc and dpEndDoc. All calls to dpPageNo will have the page number incremented by the value specified in iPage&

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
iPage& The number of pages to add to the current page number. A starting page offset, if you will.

dpPaperSize

Declare Sub dpPaperSize Lib "ddoc32.dll"  _
   ( ByVal iHandle%, ByVal pageWidth!, ByVal pageHeight! )

If you specify DDOC_PAPER_CUSTOM on any page, the width and height parameters here (expressed in inches) will specify the dimensions of the custom paper size. Note that only one custom paper size can be used in a document. You may call this function once anywhere between dpStartDoc and dpEndDoc. Passing an invalid value ( must be greater than zero and less than 22) will cause undefined results. Don't do it!

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
pageWidth!, pageHeight! The width and height of the page expressed in inches (regardless of the unit of measure being used).

dpPie

Declare Sub dpPie Lib "ddoc32.dll"  _
      ( ByVal iHandle%, _
        ByVal x!, ByVal y!, _
        ByVal x2!, ByVal y2!, _
        ByVal aStart!, ByVal aEnd!, _
        ByVal w!, ByVal lineColor&, _
        ByVal fillColor&)

This functions draws pie that is part of an imaginary circle bounded by the rectangle defined as (x, y) (x2, y2). The bounding line is w! inches/cm wide and is lineColor& color. The pie starts at an angle of aStart! degrees and ends aEnd! degrees counter-clockwise from where it starts. fillColor determines the flood-fill color. Pass w! as -1 if you don't want a line drawn around the filled pie.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
x!, y! The x and y coordinates of the upper left corner of the pie's circle's bounding rectangel
x2!, y2! The x and y coordinates of the lower right corner of the pie's circle's bounding rectangel
aStart!, aEnd! aStart! is the angle that determines the start of the pie. The pie ends aEnd! degrees from where it starts. If you want to print an arc from 45-180 degrees, start=45deg and end=135.
w! Width of the pie's border line.
lineColor& Color of the pen used to draw the pie's line.
fillColor& Color used to fill the pie slice.

dpPrinterCopies (32-bit only)

Declare Function dpPrinterCopies Lib "ddoc32.dll" (ByVal iHandle%, ByVal iCopies&) as Long

This sub sets the number of copies to be printed if dpSpecifyPrinter is called and if it is utilized by calling dpEndDoc with the DDOC_END_SPECIFIC_PRINTER or the DDOC_END_PRINT_NODIALOG flags set. In all other cases, copies will be 1 and must be changed manually by the user.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
iCopies& Number of copies to print when ending without a print dialog. This number must be an integer from 1 thru 2000. 2000 is an arbitrary number and is a constant in ddoc.inc (part of source) If you need to raise this, you must recompile ddoc.exe with this constant increased.

dpPrinterCount (32-bit only)

Declare Function dpPrinterCount Lib "ddoc32.dll" () as Long

Returns the number of printers installed on the machine. Call this to retrieve the count and then call dpGetPrinter or dpGetPrinterZ passing it a number from 1 to dpPrinterCount() to retrieve the name of an installed printer.

dpRect

Declare Sub dpRect Lib "ddoc32.dll" _
   ( ByVal iHandle%, ByVal x!, ByVal y!, _
     ByVal x2!, ByVal y2!, ByVal w!, _
     ByVal iFillColor&, ByVal iBorderColor& )

This function prints a rectangle filling the coordinates (x,y) - (x2,y2). W refers to the width of the bordering line and may be passed as -1 if you don't want a bordering line (in that case, the iBorderColor& parameter will be ignored.) iFillColor indicates the color with which to fill the rectangle. Note that in some sample programs I define a constant LIGHT_SHADE. This is a very light shade of grey suitable for printing text upon. If you want to print text on top of a rectangle, make sure that you print the rectangle first, and then print the text. If you print the text first, the rectangle will draw over the top of the text. At this time, there is no way to print a transparent rectangle.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
x!, y! The starting coordinate of the rectangle (upper-right) in inches cm
x2!, y2! The ending coordinate of the rectangle(lower left) in inches or cm
w! The width of the bordering line given in Points. 0 means a hairline - printed as the thinnest line possible on the output device. -1 means don't draw a line around the rectangle.
iFillColor& The color with which to fill the background of the rectangle.
iBorderColor& The color of the border. This is ignored it w! is passed as -1.

dpSelfExtract

Declare Function dpSelfExtract% Lib "ddoc32.dll" _
   ( ByVal sInFile$, ByVal sDdocStub$, _
     ByVal sOutFile$ )

dpSelfExtract allows the programmer to create an .exe file that, when run will display a ddoc document. It wraps the document into a viewer so that the sOutFile$ .exe file may be distributed to people who don't have ddoc on their computer - just like a self-extracting zip file can be unzipped by people who don't own pkzip.

Parameter Description
sInFile$ Name of a ddoc file as returned by dpGetFileName or passed in dpStartDoc
sDdocSub$ The full path and file name of ddoc.exe (e.g. c:\windows\system\ddoc.exe)
sOutFile$ The file to create. This file must not already exist (see return constants below)

Return Value Description
DDOC_INPUT_NOT_FOUND The sInFile$ file can't be found.
DDOC_OUTPUT_EXISTS sOutFile$ already exists on the system
DDOC_ERR_OPEN_INPUT Unable to open sInFile$ in binary mode
DDOC_ERROR_OPEN_OUTPUT Can't open / create the output file
DDOC_ERROR_OPEN_STUB Can't open ddoc.exe specified by sDdocStub$
0 Success

dpSetAttachExt (32-bit only)

Declare Sub dpSetAttachExt Lib "ddoc32.dll" _
   ( ByVal iHandle%, zExt as asciiz ) _

dpSetAttachExt allows the programmer to change the default file extension for exe attachments from .exe to .XXX where XXX is the desired extension. This function allows you to get around the common practice of email providers that block all attached files with the .exe extension. Note that the file extension is limited to 3 characters. Any more than 3 characters will be ignored.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
zExt 1-3 characters that will be the new file extension. Do not include the period, just the three letters.

dpSetEMailOptions (32-bit only)

Declare Sub dpSetEMailOptions Lib "ddoc32.dll" _
   ( ByVal iHandle%, zLogon as asciiz, _
     zPassword as asciiz, zNames as Asciiz, _
     zAddr as Asciiz, zSubject as asciiz, _
     zNote as asciiz, ByVal iShowDialog as Integer, _
     ByVal iMailSelfExtract as Integer )

dpSetEMailOptions is used to tell the system how to handle E-Mailing via SMTP or MAPI should the user press the Email button on the ddoc toolbar. Calling this function will ensure that the button and menu item are turned on. It is very important to specify the MAPI transport in the list of addresses (zAddr) if you're using MAPI instead of SMTP to send email. The transport is a string of characters followed by a colon placed before each address. The addresses themselves are delimited by semi-colons. A transport is necessary for all e-mail going to people not getting mail via your local workgroup MAPI post office. An example of a transport would be SMTP: This is the default internet transport if you install the internet e-mail transport that comes with MS Outlook. Remember, you don't specify the transport if you're doing SMTP email, just MAPI email.

e.g.

'- Sending to Troy and Bill in my local postoffice, the others
'  are via the internet.
'
zNames="Don;Troy;Joe;Bill"
zAddr="SMTP:ddickinson@usinternet.com;Troy;SMTP:joe@blow.com;Bill"

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
zLogon Leave blank to let the user logon to MAPI or specify a valid profile name to have ddoc logon without a dialog.
zPassword Password for MAPI profile. Leave blank if none or zLogon is blank.
zNames A list of ; delimited names of recipients. These can be anything you want, but they must correspond 1 to 1 with the zAddr list of addresses
zaddr A list of ; delimited address corresponding one to one with the list of names (zNames). Each address must be preceded by the transport specifer (e.g.SMTP) if the recipient isn't in the local post office.
zSubject The subject of the e-mail
zNote A body of the e-mail
iShowDialog If non-zero, the system will present the user with a standard MAPI send mail dialog. This allows the user to change the recipient list, subject, and note of the email.
iMailSelfExtract If non-zero, the system will create a self-extracting document to attach to the e-mail. If zero, the system will attach a .ddc file instead. Note that if you set this to zero, the recipient must have ddoc installed on their system in order to view the document.

dpSetFaxOptions (32-bit only)

Declare Procedure dpSetFaxOptions Lib "ddoc32.dll" _
   ( ByVal iHandle%, zLogon as asciiz, _
     zPassword as asciiz, zRecips as asciiz, _
     zSubject as asciiz, zNote as asciiz, _
     ByVal iShowDialog as Integer )

dpSetFaxOptions is very similar to dpSetEMail options. The notable difference is that you only have to include one list of recipients instead of their names and addresses separately. This list is delimited by a ; and the recipient is separated from their fax number by the @ sign. Like dpSetEmailOptions, calling this function tells the system to turn on the Fax button and menu item.

e.g.

'- Formatting the recipients list
'
zRecips="Don@612-555-0425;Troy@612-555-1212"

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
zLogon Leave blank to let the user logon to MAPI or specify a valid profile name to have ddoc logon without a dialog.
zPassword Password for MAPI profile. Leave blank if none or zLogon is blank.
zRecip A list of recipients. Each recipient is delimited from the other by a semi-colon. The recipient's name is separated from the fax number with the @ symbol (see above).
zSubject Subject of the fax
zNote Note for the fax
iShowDialog If non-zero, the system will present the user with a standard MAPI send mail dialog. This allows the user to change the recipient list, subject, and note of the email.

dpSetPassword

Declare Function dpSetPassword% Lib "ddoc32.dll" _
   ( ByVal iHandle%, ByVal zPassword$ )

dpSetPassword is used to password protect a document. Before the preview window or the print dialog (if printing instead of previewing) comes up on the screen, a dialog will appear and prompt the user for a password. The screen will try to get a valid password from the user up to 3 times. After the 3rd failure, a message box will inform the user that the document can't be viewed / printed. Note that the password is case sensitive. Also, although the document has password protection, the document will not (at lease not yet) have any sort of encryption and is not terribly hard to defeat. Use for light protection only. In the future, there may be an option to encrypt all text in a document. This feature will provide significantly better protection. Note that documents spawned directly from dpEndDoc will not prompt for a password. Only docs that are saved or emailed will ask for the password. This is a behavior change as of ddoc v1.9.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
zPassword A password with which to protect the document.

dpSetProgress (32-bit only)

Declare Sub dpSetProgress Lib "ddoc32.dll" _
   ( ByVal iHandle%, ByVal iProgress% )

This function is available on in the 32-bit version of the ddoc interface. When the DDOC_VIEWBUILD flag is set, that is, when you are allowing the user to preview the document while it is still being build, this function can be used to set the progress bar at the bottom of the page. Set the iProgress% parameter to an integer from 0 through 100 and the progress bar at the bottom of the viewer will reflect this percentage. If you don't call this, the progress bar in the viewer won't be visible - it is turned on when you first call this routine.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
iProgress% Pass a percentage complete as an integer between 0 and 100.

dpSetScreenOptions

Declare Sub dpSetScreenOptions Lib "ddoc32.dll" _
   ( ByVal iHandle%, Byval x&, byval y&, byval x2&, byval y2&, byval iMax& )

dpSetScreenOptions allows the programmer to either specify the location of the print preview window, or to have it maximized. Note that maximizing is the default behavior, so if you're setting this flag, you don't really have to make this call at all. Also note that the screen options do not apply (they are ignored) if the document is not launched via dpEndDoc. The reason for this is that an existing document (one not immediately viewed by the creator, aka. a second generation document) may be viewed on a variety of screen sizes. To ensure that the document is visible, it I maximize the window for such documents.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
x&, y& Coordinates of the upper left hand corner of the window position in pixels.
x2&, y2& Coordinates of the lower right hand corner of the window position in pixels.
iMax& If this is non-zero the window will be maximized. Otherwise (x,y), (x2, y2) will be used to position the window

dpSetTabs

Declare Sub dpSetTabs Lib "ddoc32.dll" _
   ( ByVal iHandle%, ByVal zTabStops as String )

This function tells ddoc where to place tab stops on subsequent calls to dpTabText. It allows the programmer to easily print tables of text. The tab-stops are defined by a string variable. The string contains a description of each tab stop (delimited by a space). For example:

'- This tells ddoc to set tabs as follows 
'  Left aligned, .5 inches over with a max width of 2 inches
'  Right aligned, 4 inches over with a max width of 1 inch
'  Right aligned, 5.1 inches over with a max width of 1 inch
'  Left aligned, 5.2 inches with no maximum width
'
zTabStops = "L.5W2 R4W1 R5.1W1 L5.2"
If the width designator is a number smaller than .1, it will be ignored and be treated as though you didn't pass a width designator (the width won't be restricted).

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
zTabStops A string describing the positions of the tab-stops.

dpSpecifyPrinter (32-bit only)

Declare Function dpSpecifyPrinter Lib "ddoc32.dll" _
   ( ByVal iHandle%, ByVal zPrinter as String) as Long

This function tells ddoc which printer to use if the programmer tells the engine to printer without a preview and without a dialog box. If the programmer chooses either a dialog box or a preview, this function is ignored. In order for this to work, you must call end doc in one of the following two methods:

  dpEndDoc hPrev, DDOC_END_DELETE + DDOC_END_SPECIFIC_PRINTER
    * or *
  dpEndDoc hPrev, DDOC_END_SPECIFIC_PRINTER
Do not try to mix other constants in - DDOC_END_PRINT_NODIALOG must not be added. It is implied by DDOC_END_SPECIFIC_PRINTER. It returns zero if the printer is invalid. It returns non-zero if it is a valid printer installed printer.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
sPrinter The name of a printer installed on the machine. Use dpIsPrinter to verify that the printer is installed and dpPrinterCount/dpGetPrinter to retrieve a list of installed printers.

dpSMTPOptions (32-bit only)

Declare Sub dpSMTPOptios Lib "ddoc32.dll" _
   ( ByVal hParent& )

This function calls up a Modal window that allows the user to configure the SMTP options used by ddoc's smtp interface. It returns True(non-zero) if the user Clicks Ok or False (zero) if the user cancels.

Parameter Description
hParent Handle of the parent window for the modal setup dialog that is created with this call.

Return Value Description
<> 0 The user clicked Ok
0 The user clicked Cancel

dpSpecialText

Declare Sub dpSpecialText Lib "ddoc32.dll" 
   ( ByVal iHandle%, ByVal x!, ByVal y!, _
     ByVal iAlign%, ByVal zText$   )

Prints text on the page just like dpText does; except, it searches and replaces all instances of ##pageno## with the current page number and all instances of ##pagecount## with the total page count. Other "tokens" may be added in the future.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
x!, y! The x and y coordinates in either inches or cm (see dpStartDoc iUOM parameter)
iAlign A text alignment constant - DDOC_LEFT, DDOC_CENTER, DDOC_RIGHT
zText The text to print

dpStartDoc

Declare Function dpStartDoc% Lib "ddoc32.dll" _
   ( ByVal hParent%, ByVal zTitle$, _
     ByVal zFile$, ByVal iUOM%, _
     ByVal iPaper%, ByVal iOrient%, _
     ByVal iBin%, ByVal iOptions% )

dpStartDoc is the first call made when printing or previewing a document. It initializes the print engine and returns a handle to the document that you are creating. This handle is passed on all future calls that regard this document. The handle is freed and invalidated when the programmer calls dpEndDoc.

Parameter Description
hParent Reserved for future use. Please put a Zero here
zTitle Title of the document, displayed in the title bar of the viewer and identifies the print job
zFile Name of the document to create. This parameter may be passed as "" if you want the viewer to determine a unique temp file and use that. Note: If you pass "" and want to find out what the file name is, you can to call dpGetFileName.to fill a buffer with the name.
iUOM Either DDOC_INCH or DDOC_CM indicating whether you are referencing positions in inches or cm
iPaper Paper size for the first page - see the DDOC_PAPER_xxx constants. This can also be DDOC_SYSTEM_DEFAULT to leave the paper size unspecified. Finally, it may be DDOC_PAPER_CUSTOM indicating a user defined paper size (needed for dot matrix labels). If you set it to DDOC_PAPER_CUSTOM, then a subsequent call to dpPaperSize will be assumed. If you don't make a call to dpPaperSize, then the preview and printout may show up empty. Only one custom paper size may be used per document. The last call to dpPaperSize is the only one that is observed.
iOrient Page orientation for the first page - either DDOC_PORTRAIT, DDOC_LANDSCAPE, or DDOC_SYSTEM_DEFAULT
iBin Paper Bin for the first page - see the DDOC_BIN_xxx constants or DDOC_SYSTEM_DEFAULT
iOptions Other document options, currently this is just the initial zoom setting and turn on optional features (E-Mail button, etc) (DDOC_ZOOMFIT, DDOC_ALLOWMAPI etc - see constants below)

Return Value Description
DDOC_NOHANDLES There is a limit of 20 simultaneous documents being built by an application. This error occurs if more that 20 are being built simultaneously. If you get this and you don't think it should be happening, make sure your program is calling dpEndDoc properly as this is the call that frees up a handle.
DDOC_BADFILE A bad file name was passed in the zFile parameter - look for invalid file names.
DDOC_FILEEXISTS The file specified by zFile already exists on your system, ddoc must receive the name of a file that doesn't exist.
> 0 Success ! - Store out the number returned (document handle) for reference by other calls.

Note: After calling dpStartDoc, the next call made should be to dpFont to establish the font used on this page. If you forget to initialize the font at the beginning of a page, the page will default to 10 point Arial - so all calls made to dpText, dpAngleText, or dpWrapText will be in this font. The same thing applies to the dpNewPage call. Remember that every document is randomly accessed, no page must be dependent on pages before or after it for display information - such as the font style to use. Therefore, ddoc requires that you initialize this information when starting each page.

The following are flags that can be or'd into the iOptions Parameter
iOptions Constant Value Meaning
DDOC_VIEWBUILD 1 If a 32-bit programming language is used, this turns on the "View While Building" feature that allows the user to see the document while it's being generated
DDOC_ALLOWFAX 2 Turns on the MAPI fax button
DDOC_ALLOWMAPI 4 Turns on the MAPI email button
DDOC_ALLOWSAVE 8 Turns on the document save button
DDOC_ZOOMWIDTH, DDOC_ZOOMFIT, DDOC_ZOOM75, DDOC_ZOOM100, DDOC_ZOOM125 64, 128, 256, 512, 1024 Sets the initial zoom ratio for the viewer
DDOC_SCALETEXT 2048 Tells ddoc to display text with the best possible accuracy at different zoom levels. This leads to greatly slower display speeds and is not recommended.
DDOC_FASTTEXT 0 The default way of drawing text. Text at some zoom levels might take up more or less space than it should. You don't have to specify this flag as ddoc defaults to this.
DDOC_SAVE_EXE_ONLY 4096 If DDOC_ALLOWSAVE is on, this setting specifies that the user can only save out the document as an .exe file - it disallows saving .ddc files.
DDOC_ALLOWSMTP 8192 This flag turns on the email button and tells ddoc to send email via SMTP instead of MAPI.

dpStretchMode

Declare Sub dpStretchMode% Lib "ddoc32.dll" _
   ( ByVal hParent%, ByVal iStretch& )

If iStretch is set to non-zero (the default is zero) all subsequent calls to graphic drawing routines will stretch the image to fit inside the defined box. If it is zero, the image will be shrunk to fit (and stay proportional) inside the box.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
iStretch If zero, stretching is off. If non-zero images will be stretched

dpTabText

Declare Sub dpTabText Lib "ddoc32.dll" 
   ( ByVal iHandle%, ByVal y!, ByVal zText$ )

dpTabText prints a line of tab-delimited text and prints it to the screen at positions specified by the last call made to dpSetTabs. The intent of this call is to allow the program to easily print rows in a table containing data. Separate each column of the row with a tab character.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
y! How far down on the page to print the text
zText The tab-delimited text to print

dpText

Declare Sub dpText Lib "ddoc32.dll" 
   ( ByVal iHandle%, ByVal x!, ByVal y!, _
     ByVal iAlign%, ByVal zText$   )

dpText is the most basic of text commands. It prints text at the coordinates and alignment specified using the font referenced by the last call to dpFont. It does not clip or wrap text. That is, if you print a very long line of text, it will not wrap, but continue printing right off the page. To wrap text use dpWrapText and to clip the text use dpClipText

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
x!, y! The x and y coordinates in either inches or cm (see dpStartDoc iUOM parameter)
iAlign A text alignment constant - DDOC_LEFT, DDOC_CENTER, DDOC_RIGHT
zText The text to print

dpTextWidth

Declare Function dpTextWidth Lib "ddoc32.dll" 
   ( ByVal iHandle%, ByVal zText$ ) as Single

dpTextWidth returns the width of the text passed with respect to the unit of measure for the document (either cm or inches). It uses the current font settings to determine the width of the text. dpTextWidth requires that a default printer be installed on the system. The width of the text string is dependent upon the drawing surface, since the resolution of output devices can differ. Because, generally, a printer provides finer resolution than the screen, this call determines how wide the text would be if output to the default printer. A message box will appear on the screen if no default printer is installed.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
zText The text whose width is in question.

Return Value Description
Single Precision Float The width of the text passed in zText in the units of measure for the document (either cm or inches).

dpWrapCount

Declare Function dpWrapCount Lib "ddoc32.dll" _
   ( ByVal iHandle% ) As Long

This function returns the number of lines actually printed by the last call to dpWrapText

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc

Return Value Description
Long Integer The number of lines printed by the last call to dpWrapText

dpWrapContinue

Declare Function dpWrapContinue Lib "ddoc32.dll" 
   ( ByVal iHandle%, _
     ByVal x!, ByVal y!, ByVal x2!, ByVal y2!, _
     ByVal leading!  ) As Long

dpWrapContinue continues printing the unprinted text from a previous call to dpWrapText or dpWrapContinue. As long as there is text that hasn't been printed, it will return non-zero. Once all of the text has been printed it will return 0.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
x!, y! The upper-left coordinates of the bounding rectangle in inches or cm
x2!, y2! The lower-right coordinates of the bounding rectangle in inches or cm
leading! The "line height" or vertical distance between wrapped lines from the top of one line to the top of the next.

Return Value Description
Long Integer The number of characters actually printed.

dpWrapText

Declare Function dpWrapText Lib "ddoc32.dll" 
   ( ByVal iHandle%, _
     ByVal x!, ByVal y!, ByVal x2!, ByVal y2!, _
     ByVal leading!, ByVal zText$  ) As Long

dpWrapText will wrap the text string passed so it fits in the rectangle defined. The word (and parameter) leading refers to the distance between lines. In my case, I am using it to refer to the amount of space between the top of the current line and the top of the line directly above it. If you wish your wrapped text to be 6 lines per inch, for instance, set the leading parameter to be 1/6 of an inch or .167 inches. This function returns the number of characters actually printed, so you can keep calling it with the text left over until there is no text left over to ensure that all text is printed. Also, note the dpWrapCount call (see above) may be called directly after dpWrap text to tell you how many lines were printed. This lets you calculate the amount of vertical space taken up by the paragraph (leading * dpWrapCount = how high the paragraph is). As of ddoc v1.8, you can call the dpWrapContinue function to continue printing the text not printed by the last dpWrapText call. When dpWrapContinue returns zero, then there is no more text to print.

Parameter Description
iHandle% Handle to the document as returned by dpStartDoc
x!, y! The upper-left coordinates of the bounding rectangle in inches or cm
x2!, y2! The lower-right coordinates of the bounding rectangle in inches or cm
leading! The "line height" or vertical distance between wrapped lines from the top of one line to the top of the next.
zText The text to print

Return Value Description
Long Integer The number of characters actually printed.