PDFlib 8 Windows COM/.NET Tutorial

3.2 Page Descriptions
3.2.1 Coordinate Systems
PDF’s default coordinate system is used within PDFlib. The default coordinate system
(or default user space) has the origin in the lower left corner of the page, and uses the
DTP point as unit:
1 pt = 1/72 inch = 25.4/72 mm = 0.3528 mm
The first coordinate increases to the right, the second coordinate increases upwards.
PDFlib client programs may change the default user space by rotating, scaling, translating,
or skewing, resulting in new user coordinates. The respective functions for these
transformations are rotate( ), scale( ), translate( ), and skew( ). If the coordinate system has
been transformed, all coordinates in graphics and text functions must be supplied according
to the new coordinate system. The coordinate system is reset to the default coordinate
system at the start of each page.
Using metric coordinates. Metric coordinates can easily be used by scaling the coordinate
system. The scaling factor is derived from the definition of the DTP point given
above:
p.scale(28.3465, 28.3465);
After this call PDFlib will interpret all coordinates (except for interactive features, see
below) in centimeters since 72/2.54 = 28.3465.
As a related feature, the userunit option in begin/end_page_ext( ) (PDF 1.6) can be specified
to supply a scaling factor for the whole page. Note that user units will only affect final
page display in Acrobat, but not any coordinate scaling in PDFlib.
Cookbook A full code sample can be found in the Cookbook topic general/metric_topdown_coordinates.
Coordinates for interactive elements. PDF always expects coordinates for interactive
functions, such as the rectangle coordinates for creating text annotations, links, and file
annotations in the default coordinate system, and not in the (possibly transformed)
user coordinate system. Since this is very cumbersome PDFlib offers automatic conversion
of user coordinates to the format expected by PDF. This automatic conversion is activated
by setting the usercoordinates parameter to true:
p.set_parameter("usercoordinates", "true");
Since PDF supports only link and field rectangles with edges parallel to the page edges,
the supplied rectangles must be modified when the coordinate system has been transformed
by scaling, rotating, translating, or skewing it. In this case PDFlib will calculate
the smallest enclosing rectangle with edges parallel to the page edges, transform it to
default coordinates, and use the resulting values instead of the supplied coordinates.
The overall effect is that you can use the same coordinate systems for both page content
and interactive elements when the usercoordinates parameter has been set to true.
68 Chapter 3: Creating PDF Documents (Edition for COM, .NET, and REALbasic)