Xojo Conferences

DynaPDF Manual - Page 466

Previous Page 465   Index   Next Page 467

Function Reference
Page 466 of 750
The new template is not placed on the current open page if any. To make the template visible the
template must be placed on a page or other template with PlaceTemplate() or PlaceTemplateEx().
The template can be used on arbitrary pages and arbitrary positions. It is also possible to scale a
template like an image. See PlaceTemplateEx() for further information.
Imported pages are often called watermark. A watermark is usually a simple text or some kind of
graphics that was imported from a PDF file. Such a graphics can be placed in background or in
foreground of a page. To place a template in background, add the template as first object to the
desired page. If the template should appear in foreground, add it as last object. The background of
an imported page is transparent as long as it doesn't contain any opaque objects which blank out the
entire background. Scanned images which are converted to PDF are often not transparent. Those
pages must be placed in background to avoid overlaying objects.
It is possible to import an external page outside of an open page, and it is also possible to import a
page outside of an open output PDF file. However, all templates will be deleted when CloseFile() is
called the next time. It is not possible to import an external page as template and hold it in memory
for use with more than one PDF file.
Bounding boxes
As mentioned earlier, imported pages are converted to templates by this function. A template has
only one bounding box, but a PDF page has 5 bounding boxes (see SetBBox() for a full explanation).
The most important bounding boxes are the media box and crop box of the original page.
A bounding box is defined as a rectangle giving the coordinates pair of diagonally opposite corners.
The media box of a page is usually expressed in a normalized form where the coordinates of the
lower-left point are set to 0.
However, the normalized form is used in 99% of all available documents but it is also possible that a
document uses a non-normalized form. For instance, the media box can look like this:
= -100.0; // lower-left x
mediabox.Bottom = -100.0; // lower-left y
200.0; // upper-right x
200.0; // upper-right y
The size of the page that uses such a bounding box is 300 x 300 units. The problem is that the
coordinate origin lies at -100, -100. The page can also contain a crop box and the original page can be
rotated. This makes the handling more complicated.
When placing such a template with PlaceTemplate() on a page without further considerations the
result will be wrong because PlaceTemplate() does not consider the coordinate origin or the original
page orientation.
To simplify the work with imported templates PlaceTemplateEx() should be used instead. This
function considers the coordinate origin, crop box, and it preserves the original orientation when the
template is placed on a page. See PlaceTemplateEx() for further information.

Previous topic: ImportPage

Next topic: Calling the function inside of an open page