• Documentation Home
• Tutorial
• Advanced Topics
• Label Generation
• Core Functions
• Label Functions
• Appendix A: Constants
• Appendix B: ddocml.ini

• dpAddGraphic
• dpAngleText
• dpArc
• dpBookmark
• dpChangeWords
• dpCheckAbort
• dpClipText
• dpDuplex
• dpDrawGraphic
• dpEllipse
• dpEmbedGraphic
• dpEndDoc
• dpEndDocInst
• dpFont
• dpFontSpacing
• dpGetFileName
• dpGetMajorVersion
• dpGetMinorVersion
• dpGetPrinter
• dpGetPrinterZ
• dpGraphic
• dpIsPrinter
• dpLine
• dpNewPage
• dpPageCount
• dpPageNo
• dpPageOffset
• dpPaperSize
• dpPie
• dpPrinterCopies
• dpPrinterCount
• dpRect
• dpRoundRect
• dpSelfExtract
• dpSetAttachExt
• dpSetEMailOptions
• dpSetFaxOptions
• dpSetPassword
• dpSetProgress
• dpSetScreenOptions
• dpSetTabs
• dpSpecialText
• dpSpecifyPrinter
• dpSMTPOptions
• dpStartDoc
• dpStretchMode
• dpTabText
• dpText
• dpTextWidth
• dpWrapCount
• dpWrapContinue
• dpWrapText

• 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

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.

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.

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.

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.

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

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.

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.

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).

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.

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)

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.

dpEndDocInst

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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&

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!

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.

dpPrinterCopies (32-bit only)

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