DynaPDF Manual - Page 189

Previous Page 188   Index   Next Page 190

Function Reference
Page 189 of 860
BeginTemplate
Syntax:
SI32 pdfBeginTemplate(
const PPDF* IPDF, // Instance pointer
double Width,
// Width of the template
double Height)
// Height of the template
The function creates a template and opens it so that arbitrary contents can be drawn into it. After the
objects of the template are drawn, it must be finished with EndTemplate(). To insert the template on
a page use PlaceTemplate().
A template is a PDF object (Form XObject in PDF syntax) that can contain vector graphics, images,
and text, but no interactive objects like annotations or form fields.
The difference between a normal page and a template is that a template can be used arbitrary often
and scaled to different sizes without increasing the file size since a template is stored only once in
the PDF file. Templates are used for repeating contents, such as static page backgrounds and so on,
simply anything that must be drawn multiple times.
The initial background of a template is transparent.
When creating a template the function saves the graphics state and initializes all members of the
new state to their default values.
EndTemplate() closes the template and restores the graphics state so that no changes made during
creation of the template affect the parent object, if the template was created in an open page or other
template.
A template can automatically be inserted to new pages. This can be achieved by adding the template
to the list of auto-templates (see AutoTemplate() for further information). This can be useful if a
template represents a fixed page background that must appear on all pages.
Remarks:
A template remains invisible until it was placed on a page with PlaceTemplate(). Unused templates
are deleted when CloseFile() is called, they are not added to the PDF file.
Templates can be created outside of an open page and it is also possible to create a template outside
of on open PDF file. But note: it is not possible to create a persistent template that can be used with
multiple PDF files. All objects will be deleted when CloseFile() or FreePDF() is called.
Return values:
If the function succeeds the return value is the template handle, a value greater or equal zero. If the
function fails the return value is a negative error code.
 

Previous topic: BeginPattern, Colored Tiling Patterns, Uncolored Tiling Patterns

Next topic: BeginTransparencyGroup, The Group's Bounding Box