48
3.2 Page Descriptions 55
coordinates for several common page sizes. Printing the appropriately sized page on
transparent material may provide a useful tool for preparing PDFlib development.
Acrobat 6/7 (full version only, not the free Reader) also has a helpful facility. Simply
choose View, Navigation tabs, Info to display a measurement palette. Note that the coor-
dinates displayed refer to an origin in the top left corner of the page, and not PDF’s de-
fault origin in the lower left corner. To change the display units go to Edit, Preferences,
[General...], Units & Guides [or Page Units] and choose one of Points, Inches, Millimeters,
Picas, Centimeters. You can also go to View, Navigation Tabs, Info and select a unit from
the Options menu.
Don’t be mislead by PDF printouts which seem to experience wrong page dimen-
sions. These may be wrong because of some common reasons:
>The Page Scaling: option in Acrobat’s print dialog has a setting different from None,
resulting in scaled print output.
>Non-PostScript printer drivers are not always able to retain the exact size of printed
objects.
Rotating objects. It is important to understand that objects cannot be modified once
they have been drawn on the page. Although there are PDFlib functions for rotating,
translating, scaling, and skewing the coordinate system, these do not affect existing ob-
jects on the page but only subsequently drawn objects.
Rotating text, images, and imported PDF pages can easily be achieved with the rotate
option of PDF_fit_textline( ), PDF_fit_textflow( ), PDF_fit_image( ), and PDF_fit_pdi_page( ).
Rotating such objects by multiples of 90 degrees inside the respective fitbox can be ac-
complished with the orientate option of these functions. The following example gener-
ates some text at an angle of 45˚ degrees:
p.fit_textline("Rotated text", 50.0, 700.0, "rotate=45");
Cookbook A full code sample can be found in the Cookbook topic text_output/rotated_text.
Rotation for vector graphics can be achieved by applying the general coordinate trans-
formation functions PDF_translate( ) and PDF_rotate( ). The following example creates a
rotated rectangle with lower left corner at (200, 100). It translates the coordinate origin
to the desired corner of the rectangle, rotates the coordinate system, and places the rect-
angle at (0, 0). The save/restore nesting makes it easy to continue placing objects in the
original coordinate system after the rotated rectangle is done:
p.save();
p.translate(200, 100);
/* move origin to corner of rectangle*/
p.rotate(45.0);
/* rotate coordinates */
p.rect(0.0, 0.0, 75.0, 25.0);
/* draw rotated rectangle */
p.stroke();
p.restore();
Using top-down coordinates. Unlike PDF’s bottom-up coordinate system some graph-
ics environments use top-down coordinates which may be preferred by some develop-
ers. Such a coordinate system can easily be established using PDFlib’s transformation
functions. However, since the transformations will also affect text output (text easily
appears bottom-up), additional calls are required in order to avoid text being displayed
in a mirrored sense.
44
56
Chapter 3: PDFlib Programming
In order to facilitate the use of top-down coordinates PDFlib supports a special mode
in which all relevant coordinates will be interpreted differently. The topdown feature
has been designed to make it quite natural for PDFlib users to work in a top-down coor-
dinate system. Instead of working with the default PDF coordinate system with the ori-
gin (0, 0) at the lower left corner of the page and y coordinates increasing upwards, a
modified coordinate system will be used which has its origin at the upper left corner of
the page with y coordinates increasing downwards. This top-down coordinate system
for a page can be activated with the topdown option of PDF_begin_page_ext( ) :
p.begin_page_ext(595.0, 842.0, "topdown");
Alternatively, the topdown parameter can be used, but it must not be set within a page
description (but only between pages). For the sake of completeness we’ll list the detailed
consequences of establishing a top-down coordinate system below.
»Absolute« coordinates will be interpreted in the user coordinate system without
any modification:
>All function parameters which are designated as »coordinates« in the function de-
scriptions. Some examples: x, y in PDF_moveto( ); x, y in PDF_circle( ), x, y (but not width
and height!) in PDF_rect( ); llx, lly, urx, ury in PDF_create_annotation( )).
»Relative« coordinate values will be modified internally to match the top-down system:
>Text (with positive font size) will be oriented towards the top of the page;
>When the manual talks about »lower left« corner of a rectangle, box etc. this will be
interpreted as you see it on the page;
>When a rotation angle is specified the center of the rotation is still the origin (0, 0) of
the user coordinate system. The visual result of a clockwise rotation will still be
clockwise.
Cookbook A full code sample can be found in the Cookbook topic general/metric_topdown_coordinates.
3.2.2 Page Size
Cookbook A full code sample can be found in the Cookbook topic pagination/page_sizes.
Standard page formats. Absolute values and symbolic page size names may be used
for the width and height options in PDF_begin/end_page_ext( ). The latter are called
<format>.width and <format>.height, where <format> is one of the standard page formats
(in lowercase, e.g. a4.width).
Page size limits. Although PDF and PDFlib don’t impose any restrictions on the usable
page size, Acrobat implementations suffer from architectural limits regarding the page
size. Note that other PDF interpreters may well be able to deal with larger or smaller doc-
ument formats. The page size limits for Acrobat are shown in Table 3.2. In PDF 1.6 and
above the userunit option in PDF_begin/end_page_ext( ) can be used to specify a global
scaling factor for the page.
Different page size boxes. While many PDFlib developers only specify the width and
height of a page, some advanced applications (especially for prepress work) may want
to specify one or more of PDF’s additional box entries. PDFlib supports all of PDF’s box
entries. The following entries, which may be useful in certain environments, can be
specified by PDFlib clients (definitions taken from the PDF reference):
VB.NET PDF- HTML5 PDF Viewer for VB.NET Project Create PDF from Text. PDF Export. Convert PDF to Word (.docx Image to PDF. Image: Remove Image from PDF Page. Image Data: Read, Extract Field Data. Data: Auto Fill
how to fill out pdf forms in reader; extract data from pdf to excel online
51
3.2 Page Descriptions 57
>MediaBox: this is used to specify the width and height of a page, and describes what
we usually consider the page size.
>CropBox: the region to which the page contents are to be clipped; Acrobat uses this
size for screen display and printing.
>TrimBox: the intended dimensions of the finished (possibly cropped) page;
>ArtBox: extent of the page’s meaningful content. It is rarely used by application soft-
ware;
>BleedBox: the region to which the page contents are to be clipped when output in a
production environment. It may encompass additional bleed areas to account for in-
accuracies in the production process.
PDFlib will not use any of these values apart from recording it in the output file. By de-
fault PDFlib generates a MediaBox according to the specified width and height of the
page, but does not generate any of the other entries. The following code fragment will
start a new page and set the four values of the CropBox:
/* start a new page with custom CropBox */
p.begin_page_ext(595, 842, "cropbox={10 10 500 800}");
Number of pages in a document. There is no limit in PDFlib regarding the number of
generated pages in a document. PDFlib generates PDF structures which allow Acrobat to
efficiently navigate documents with hundreds of thousands of pages.
3.2.3 Paths
A path is a shape made of an arbitrary number of straight lines, rectangles, or curves. A
path may consist of several disconnected sections, called subpaths. There are several
operations which can be applied to a path:
>Stroking draws a line along the path, using client-supplied parameters (e.g., color,
line width) for drawing.
>Filling paints the entire region enclosed by the path, using client-supplied parame-
ters for filling.
>Clipping reduces the imageable area for subsequent drawing operations by replacing
the current clipping area (which is the page size by default) with the intersection of
the current clipping area and the area enclosed by the path.
>Merely terminating the path results in an invisible path, which will nevertheless be
present in the PDF file. This will only rarely be required.
It is an error to construct a path without applying any of the above operations to it.
PDFlib’s scoping system ensures that clients obey to this restriction. If you want to set
any appearance properties (e.g. color, line width) of a path you must do so before start-
ing any drawing operations. These rules can be summarized as »don’t change the ap-
pearance within a path description«.
Table 3.2 Minimum and maximum page size of Acrobat
PDF viewer
minimum page size
maximum page size
Acrobat 4 and above
1/24" = 3 pt = 0.106 cm
200" = 14400 pt = 508 cm
Acrobat 7 and above with
the userunit option
3 user units
14 400 user units
The maximum value 75 000 for userunit allows page sizes
up to 14 400 * 75 000 = 1 080 000 000 points = 381 km
46
58
Chapter 3: PDFlib Programming
Merely constructing a path doesn’t result in anything showing up on the page; you
must either fill or stroke the path in order to get visible results:
p.moveto(100, 100);
p.lineto(200, 100);
p.stroke();
Most graphics functions make use of the concept of a current point, which can be
thought of as the location of the pen used for drawing.
Cookbook A full code sample can be found in the Cookbook topic graphics/starter_graphics.
3.2.4 Templates
Templates in PDF. PDFlib supports a PDF feature with the technical name form
XObjects. However, since this term conflicts with interactive forms we refer to this fea-
ture as templates. A PDFlib template can be thought of as an off-page buffer into which
text, vector, and image operations are redirected (instead of acting on a regular page).
After the template is finished it can be used much like a raster image, and placed an ar-
bitrary number of times on arbitrary pages. Like images, templates can be subjected to
geometrical transformations such as scaling or skewing. When a template is used on
multiple pages (or multiply on the same page), the actual PDF operators for construct-
ing the template are only included once in the PDF file, thereby saving PDF output file
size. Templates suggest themselves for elements which appear repeatedly on several
pages, such as a constant background, a company logo, or graphical elements emitted
by CAD and geographical mapping software. Other typical examples for template usage
include crop and registration marks or custom Asian glyphs.
Using templates with PDFlib. Templates can only be defined outside of a page descrip-
tion, and can be used within a page description. However, templates may also contain
other templates. Obviously, using a template within its own definition is not possible.
Referring to an already defined template on a page is achieved with the PDF_fit_image( )
function just like images are placed on the page (see Section 7.3, »Placing Images and
Imported PDF Pages«, page 158). The general template idiom in PDFlib looks as follows:
/* define the template */
template = p.begin_template_ext(template_width, template_height, "");
...place marks on the template using text, vector, and image functions...
p.end_template();
...
p.begin_page(page_width, page_height);
/* use the template */
p.fit_image(template, 0.0, 0.0, "");
...more page marking operations...
p.end_page();
...
p.close_image(template);
All text, graphics, and color functions can be used on a template. However, the follow-
ing functions must not be used while constructing a template:
>PDF_load_image( ): this is not a big restriction since images can be opened outside of
a template definition, and freely be used within a template (but not opened).
9
3.2 Page Descriptions 59
>All interactive functions, since these must always be defined on the page where they
should appear in the document, and cannot be generated as part of a template.
Cookbook A full code sample can be found in the Cookbook topic general/repeated_contents.
Template support in third-party software. Templates (form XObjects) are an integral
part of the PDF specification, and can be perfectly viewed and printed with Acrobat.
However, not all PDF consumers are prepared to deal with this construct. For example,
the Acrobat plugin Enfocus PitStop 5.0 can only move templates, but cannot access indi-
vidual elements within a template.
43
60
Chapter 3: PDFlib Programming
3.3 Working with Color
Note The PDFlib Reference contains a detailed list of supported color spaces with descriptions.
Cookbook Code samples regarding color issues can be found in the color category of the PDFlib Cook-
book. For an overview of using color spaces, see the Cookbook topic color/starter_color.
3.3.1 Patterns and Smooth Shadings
As an alternative to solid colors, patterns and shadings are special kinds of colors which
can be used to fill or stroke arbitrary objects.
Patterns. A pattern is defined by an arbitrary number of painting operations which
are grouped into a single entity. This group of objects can be used to fill or stroke arbi-
trary other objects by replicating (or tiling) the group over the entire area to be filled or
the path to be stroked. Working with patterns involves the following steps:
>First, the pattern must be defined between PDF_begin_pattern( ) and PDF_end_
pattern( ). Most graphics operators can be used to define a pattern.
>The pattern handle returned by PDF_begin_pattern( ) can be used to set the pattern as
the current color using PDF_setcolor( ).
Depending on the painttype parameter of PDF_begin_pattern( ) the pattern definition
may or may not include its own color specification. If painttype is 1, the pattern defini-
tion must contain its own color specification and will always look the same; if painttype
is 2, the pattern definition must not include any color specification. Instead, the current
fill or stroke color will be applied when the pattern is used for filling or stroking.
Note Patterns can also be defined based on a smooth shading (see below).
Cookbook Full code samples can be found in the Cookbook topics graphics/fill_pattern and
images/tiling_pattern.
Smooth shadings. Smooth shadings, also called color blends or gradients, provide a
continuous transition from one color to another. Both colors must be specified in the
same color space. PDFlib supports two different kinds of geometry for smooth shadings:
>axial shadings are defined along a line;
>radial shadings are defined between two circles.
Shadings are defined as a transition between two colors. The first color is always taken
to be the current fill color; the second color is provided in the c1, c2, c3, and c4 parameters
of PDF_shading( ). These numerical values will be interpreted in the first color’s color
space according to the description of PDF_setcolor( ).
Calling PDF_shading( ) will return a handle to a shading object which can be used in
two ways:
>Fill an area with PDF_shfill( ). This method can be used when the geometry of the ob-
ject to be filled is the same as the geometry of the shading. Contrary to its name this
function will not only fill the interior of the object, but also affects the exterior. This
behavior can be modified with PDF_clip( ).
>Define a shading pattern to be used for filling more complex objects. This involves
calling PDF_shading_pattern( ) to create a pattern based on the shading, and using
this pattern to fill or stroke arbitrary objects.
Documents you may be interested
Documents you may be interested
