|
|
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:
- display it on the screen in a preview window
- print it directly to the printer
- store it in a file without displaying or printing it
- e-mail the document via mapi mail
- 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.
|