IPDF methods reference

Close()

Closes the PDF file. If changes were made but not saved, they are silently lost. All IPage objects must be released before closing a PDF.

Syntax

VOID Close ()

Note: Before using Close() in Javascript, you should call the CollectGarbage() global method to ensure all references to pages are properly discarded. This additional statement is not required with other languages. For instance:

var objPDF = Watch.GetPDFEditObject();
objPDF.Open(Watch.GetJobFileName(), false);
var objPages = objPDF.Pages();
var objPage = null;
for(var i=0; i<objPages.Count(); i++) {
	objPage = objPages.Item(i);
}
objPage=null;
objPages=null;
CollectGarbage();
objPDF.Close();

If you run the above code without calling the CollectGarbage() method, the Close() method will error out.

Create(filename)

Creates a new empty PDF file. See also: Save().

Syntax

VOID Create (STRING filename)

filename

Name of the file to create. The file is not physically written to disk until IPDF.Save() is called.

ConvertToVDX(pdfFilename, ppmlFilename)

Converts a PDF file to a VDX file by adding the necessary entries in the catalog and root dictionaries as well as embedding a PPML file as a stream object in the PDF. The validity of the PPML is left to the caller.

This method opens, modifies, saves and closes the specified PDF file. This means that, contrary to the other methods of the IPDF interface, this method works on - and only on - the PDF file specified by the first argument; IPDF.Open() or .Create() do not need to be called beforehand. If they were called, the file opened or created by these methods is untouched (unless of course pdfFilename specifies the same filename as Open()).

Syntax

VOID ConvertToVDX (STRING pdfFilename, STRING ppmlFilename)

pdfFilename

Name of the file to convert.

ppmlFilename

Name of the PPML file to embed.

GetInfos()

Retrieves the contents of the Document Information Dictionary from the PDF.

Syntax

IPdfInfos GetInfos ()

Return value

An IPdfInfos structure containing the PDF properties. Cannot be NULL.

GetVersion(major, minor)

Returns the version of the underlying PDF file format.

Note: This method is not available in all scripting environments.

Syntax

GetVersion(LONG *major, LONG *minor)

major

Pointer to a LONG that receives the major version number.

minor

Pointer to a LONG that receives the minor version number.

GetXMP()

Retrieves the XMP attachment embedded in the PDF.

Syntax

STRING GetXMP ()

Return value

String containing the complete text of the PDF's XMP attachment.

GetXYML()

Retrieves the entire extractable text from the PDF in XYML format.

Syntax

STRING GetXYML ()

Return value

A string containing the complete text of the PDF in XYML format.

IsProtected(filename)

Returns True if the PDF file is password-protected. When a file is password-protected, the OpenEx() method must be used instead of the Open() method. See also: OpenEx(filename, password, doRepair).

Syntax

BOOL IsProtected (STRING filename)

filename

Name of the file to check for password-protection.

Return value

True if the file is password-protected, False otherwise.

MergeWith(pdfFilename)

Merges the pages of pdfFilename (the source) onto the pages of the current PDF (the destination ). Each page of the source is overlaid transparently onto the corresponding destination page, 1 on 1, 2 on 2, 3 on 3, etc. The source must have the same number of pages than the destination and each pair of pages should have the same size. The resulting file is not optimized.

This method is the same as calling: PDF.MergeWith2(pdfFilename, 1, 1, 0, 0, 1.0); (see MergeWith2(pdfFilename, xnum, ynum, xoffset, yoffset, scaleFactor)).

Syntax

VOID MergeWith (STRING pdfFilename)

pdfFilename

Name of the source PDF from which pages are taken to be overlaid on the pages of the destination PDF.

MergeWith2(pdfFilename, xnum, ynum, xoffset, yoffset, scaleFactor)

Merges the pages of pdfFilename (the source) onto the pages of the current PDF (the destination). Each page of the source is overlaid transparently onto a destination page in a grid whose size is specified by xnum and ynum. The pages are laid from left to right and then from top to bottom. The resulting file is not optimized.

In PlanetPress Suite, this method is useful for n-Up imposition. For example, (xnum=1, ynum=1, scaleFactor=1.0) means that each source is overlaid on the corresponding destination page, 1 on 1, 2 on 2, 3 on 3, etc. Having (xnum=3, ynum=2) with xoffset, yoffset and scaleFactor set accordingly results in a 3x2 mosaic looking like this:

1	2	3
4	5	6

There is no separator between the source pages on the destination page. A space can be obtained by using an offset bigger than the size of the scaled source page.

Syntax

VOID MergeWith2 (STRING pdfFilename, LONG xnum, LONG ynum, LONG xoffset, LONG yoffset, FLOAT scaleFactor)

pdfFilename

Name of the source PDF from which pages are taken.

xnum

Number of columns.

ynum

Number of rows.

xoffset

Horizontal space to put between the top left corner of each source page, in points.

yoffset

Vertical space to put between the top left corner of each source page, in points.

scaleFactor

Scale at which to draw on source pages on the destination. Use 1.0 to draw the page at its nominal size.

Open(filename, doRepair)

Opens an existing PDF, optionally repairing it.

Syntax

VOID Open (STRING filename, BOOL doRepair)

filename

Name of the file to open.

doRepair

Boolean. If true, the software automatically attempts to repair the file if it is found to be damaged or corrupt. Otherwise, the operation fails if the file is damaged.

OpenEx(filename, password, doRepair)

Opens an existing, password-protected PDF, optionally repairing it. See also: IsProtected(filename).

Syntax

VOID OpenEx (STRING filename, STRING password, BOOL doRepair)

filename

Name of the file to open.

password

Password to open the file.

doRepair

Boolean. If true, the software automatically attempts to repair the file if it is found to be damaged or corrupt. Otherwise, the operation fails if the file is damaged.

Pages()

Provides access to the Pages collection of the PDF.

Syntax

IPages Pages ()

Return value

An IPages collection object. Each page in the zero-based collection can be accessed through the IPages.Item() method. Note that since Item() is the collection's default method, it can be omitted altogether (e.g. IPages(0) is the same as IPages.Item(0)).

Print(printername)

Prints a range of PDF pages to the specified Windows printer with default options. See also: PrintEx(printername, *PdfPrintParams).

Syntax

VOID Print (
STRING printerName,
LONG fromPage,
LONG toPage
)

printerName (optional)

Name of the printer to print to. The default options of the printer will be used. If NULL, the default printer is used.

fromPage

0-based index of the first page to print.

toPage

0-based index of the last page to print. To print all pages from fromPage to the end, use -1.

PrintEx(printername, *PdfPrintParams)

Prints a range of PDF pages to the specified Windows printer with specific printer options stored in an IPdfPrintParams structure. See also: Print(printername).

Syntax

VOID PrintEx (
STRING printerName,
IPdfPrintParams * PdfPrintParams
)

printerName (optional)

Name of the printer to print to. The default options of the printer will be used. PdfPrintParams , if non-NULL, may override some of them. If NULL, the default printer is used.

PdfPrintParams (optional)

Pointer to an IPdfPrintParams structure that specifies various print options. If NULL , default values are used.

Save()

Saves changes to the PDF file. The version of the PDF file format is the highest possible for a newly created file and is unchanged when saving an existing file, unless the SetVersion method was called in which case the file format used will be the one set by SetVersion. See also: SetVersion (major, minor).

Syntax

VOID Save (BOOL optimize)

optimize

If true, the file is optimized before being written to disk, i.e. objects are garbage-collected and/or regenerated, the PDF is linearized, etc.

SetInfos(Infos)

Sets the contents for the PDF's Document Information Dictionary.

Syntax

VOID SetInfos ( IPdfInfos Infos )

Infos

IPdfInfos structure containing the new values.

setPageCacheSize(cacheSize)

Sets the maximum number of IPage objects in the cache. Calling this method flushes the cache.

Syntax

VOID setPageCacheSize ( UNSIGNED LONG cacheSize )

cacheSize

Maximum number of IPage pointers that the cache can hold, between 1 and 1000.

setTolerances(tolerableDeltaWidth, tolerableDeltaHeight, tolerableDeltaFontHeight, tolerableGap)

Sets the floating point values for the tolerable factors.

Syntax

VOID setTolerances (
FLOAT tolerableDeltaWidth,
FLOAT tolerableDeltaHeight,
FLOAT tolerableDeltaFontHeight,
FLOAT tolerableGap
)

tolerableDeltaWidth

Tolerable delta width factor value.

tolerableDeltaHeight

Tolerable delta height factor value.

tolerableDeltaFontHeight

Tolerable delta font height factor value.

tolerableGap

Tolerable delta gap between words factor value.

SetVersion (major, minor)

Sets the version of the underlying PDF file format. This is applied when the file is saved. See also: Save().

Syntax

VOID SetVersion ( LONG major, LONG minor )

major

Major version number.

minor

Minor version number.

SetXMP(xmpPacket)

Sets the XMP attachment by replacing the existing one with xmpPacket.

Syntax

VOID SetXMP ( STRING xmpPacket )

xmpPacket

New XMP attachment to use instead of the existing one.

IPDF methods reference

Close()

Create(filename)

ConvertToVDX(pdfFilename, ppmlFilename)

GetInfos()

Return value

GetVersion(*major, *minor)

GetXMP()

Return value

GetXYML()

Return value

IsProtected(filename)

Return value

MergeWith(pdfFilename)

MergeWith2(pdfFilename, xnum, ynum, xoffset, yoffset, scaleFactor)

Open(filename, doRepair)

OpenEx(filename, password, doRepair)

Pages()

Return value

Print(printername)

PrintEx(printername, *PdfPrintParams)

Save()

SetInfos(Infos)

setPageCacheSize(cacheSize)

setTolerances(tolerableDeltaWidth, tolerableDeltaHeight, tolerableDeltaFontHeight, tolerableGap)

SetVersion (major, minor)

SetXMP(xmpPacket)

GetVersion(major, minor)