74
244
Chapter 10: Variable Data and Blocks
firstlinedist
(Float, percentage, or keyword) The distance between the top of the fitbox and the baseline for the first
line of text, specified in user coordinates, as a percentage of the relevant font size (the first font size in
the line if fixedleading=true, and the maximum of all font sizes in the line otherwise), or as a keyword.
Default: leading.
leading
The leading value determined for the first line; typical diacritical characters such as À will
touch the top of the fitbox.
ascender The ascender value determined for the first line; typical characters with larger ascenders, such
as d and h will touch the top of the fitbox.
capheight The capheight value determined for the first line; typical capital uppercase characters such as
H will touch the top of the fitbox.
xheight
The xheight value determined for the first line; typical lowercase characters such as x will
touch the top of the fitbox.
If fixedleading=false the maximum of all leading, ascender, xheight, or capheight values found in
the first line will be used.
fixedleading
(Boolean) If true, the first leading value found in each line will be used. Otherwise the maximum of all
leading values in the line will be used. Default: false
hortabsize
(Float or percentage) Width of a horizontal tab
1
. The interpretation depends on the hortabmethod op-
tion. Default: 7.5%
hortab-
method
(Keyword) Treatment of horizontal tabs in the text. If the calculated position is to the left of the current
text position, the tab will be ignored. Default: relative.
relative
The position will be advanced by the amount specified in hortabsize.
typewriter The position will be advanced to the next multiple of hortabsize.
ruler
The position will be advanced to the n-th tab value in the ruler option, where n is the number
of tabs found in the line so far. If n is larger than the number of tab positions the relative
method will be applied.
lastalignment
(Keyword) Formatting for the last line in a paragraph. All keywords of the alignment option are support-
ed, plus the following. Default: auto.
auto
Use the value of the alignment option unless it is justify. In the latter case left will be used.
lastlinedist
(Float, percentage, or keyword) Will be ignored for fitmethod=nofit) The minimum distance between
the baseline for the last line of text and the bottom of the fitbox, specified in user coordinates, as a per-
centage of the font size (the first font size in the line if fixedleading= true, and the maximum of all
font sizes in the line otherwise), or as a keyword. Default: 0, i.e. the bottom of the fitbox will be used as
baseline, and typical descenders will extend below the fitbox.
descender The descender value determined for the last line; typical characters with descenders, such as g
and j will touch the bottom of the fitbox.
If fixedleading=false the maximum of all descender values found in the last line will be used.
leading
(Float or percentage) Distance between adjacent text baselines in user coordinates, or as a percentage of
the font size. Default: 100%
parindent
(Float or percentage) Left indent of the first line of a paragraph
1
. The amount will be added to
leftindent. Specifying this option within a line will act like a tab. Default: 0
rightindent
leftindent
(Float or percentage) Right or left indent of all text lines
1
. If leftindent is specified within a line and the
determined position is to the left of the current text position, this option will be ignored for the current
line. Default: 0
rotate
(Float) Rotate the coordinate system, using the lower left corner of the fitbox as center and the specified
value as rotation angle in degrees. This results in the box and the text being rotated. The rotation will be
reset when the text has been placed. Default: 0
Table 10.6 Textflow block properties
keyword
possible values and explanation
Process Multipage TIFF Images in Web Image Viewer| Online Export multi-page TIFF image to a PDF; More image viewing & multipage TIFF files in Web Document Viewer, make sure that Load, Save an Editable Multi-page TIFF.
how to fill out pdf forms in reader; how to fill out a pdf form with reader
76
10.5 Standard Properties for Automated Processing 245
ruler
2
(List of floats or percentages) List of absolute tab positions for hortabmethod=ruler
1
. The list may con-
tain up to 32 non-negative entries in ascending order. Default: integer multiples of hortabsize
tabalignment
(List of keywords) Alignment for tab stops. Each entry in the list defines the alignment for the corre-
sponding entry in the ruler option. Default: left.
center
Text will be centered at the tab position.
decimal The first instance of tabalignchar will be left-aligned at the tab position. If no tabalignchar
is found, right alignment will be used instead.
left
Text will be left-aligned at the tab position.
right
Text will be right-aligned at the tab position.
verticalalign (Keyword) Vertical alignment of the text in the fitbox. Default: top.
top
Formatting will start at the first line, and continue downwards. If the text doesn’t fill the
fitbox there may be whitespace below the text.
center
The text will be vertically centered in the fitbox. If the text doesn’t fill the fitbox there may be
whitespace both above and below the text.
bottom
Formatting will start at the last line, and continue upwards. If the text doesn’t fill the fitbox
there may be whitespace above the text.
justify
The text will be aligned with top and bottom of the fitbox. In order to achieve this the leading
will be increased up to the limit specified by linespreadlimit. The height of the first line will
only be increased if firstlinedist=leading.
properties for controlling the line-breaking algorithm
adjust-
method
(Keyword) Method used to adjust a line when a text portion doesn’t fit into a line after compressing or
expanding the distance between words subject to the limits specified by the minspacing and maxspacing
options. Default: auto.
auto
The following methods are applied in order: shrink, spread, nofit, split.
clip
Same as nofit, except that the long part at the right edge of the fit box (taking into account
the rightindent option) will be clipped.
nofit
The last word will be moved to the next line provided the remaining (short) line will not be
shorter than the percentage specified in the nofitlimit option. Even justified paragraphs
may look slightly ragged.
shrink
If a word doesn’t fit in the line the text will be compressed subject to shrinklimit. If it still
doesn’t fit the nofit method will be applied.
split
The last word will not be moved to the next line, but will forcefully be hyphenated. For text
fonts a hyphen character will be inserted, but not for symbol fonts.
spread
The last word will be moved to the next line and the remaining (short) line will be justified by
increasing the distance between characters in a word, subject to spreadlimit. If justification
still cannot be achieved the nofit method will be applied.
linespread-
limit
(Float or percentage; only for verticalalign=justify) Maximum amount in user coordinates or as per-
centage of the leading for increasing the leading for vertical justification. Default: 200%
maxlines
(Integer or keyword) The maximum number of lines in the fitbox, or the keyword auto which means that
as many lines as possible will be placed in the fitbox. When the maximum number of lines has been
placed PDF_fit_textflow( ) will return the string _boxfull.
maxspacing
minspacing
(Float or percentage) The maximum or minimum distance between words (in user coordinates, or as a
percentage of the width of the space character). The calculated word spacing is limited by the provided
values (but the wordspacing option will still be added). Defaults: minspacing=50%, maxspacing=500%
nofitlimit
(Float or percentage) Lower limit for the length of a line with the nofit method (in user coordinates or as
a percentage of the width of the fitbox). Default: 75%.
Table 10.6 Textflow block properties
keyword
possible values and explanation
55
246
Chapter 10: Variable Data and Blocks
10.5.3 Image Properties
Image-related properties apply to blocks of type Image (in addition to general proper-
ties). All image-related properties can be shared. Table 10.7 lists image-related proper-
ties.
10.5.4 PDF Properties
PDF-related properties apply to blocks of type PDF (in addition to general properties). All
PDF-related properties can be shared. Table 10.8 lists PDF-related properties.
shrinklimit
(Percentage) Lower limit for compressing text with the shrink method; the calculated shrinking factor is
limited by the provided value, but will be multiplied with the value of the horizscaling option. Default:
85%
spreadlimit
(Float or percentage) Upper limit for the distance between two characters for the spread method (in user
coordinates or as a percentage of the font size); the calculated character distance will be added to the
value of the charspacing option. Default: 0
1. In user coordinates, or as a percentage of the width of the fit box
2. Rulers can be edited in the »Tabs« section of the Block properties dialog.
Table 10.7 Image block properties
keyword
possible values and explanation
defaultimage
(String) Path name of an image which will be used if no substitution image is supplied by the client. It is
recommended to use file names without absolute paths, and use the SearchPath feature in the PPS client
application. This will make block processing independent from platform and file system details.
dpi
(Float list) One or two values specifying the desired image resolution in pixels per inch in horizontal and
vertical direction. With the value o the image’s internal resolution will be used if available, or 72 dpi oth-
erwise. This property will be ignored if the fitmethod property has been supplied with one of the key-
words auto, meet, slice, or entire. Default: 0
scale
(Float list) One or two values specifying the desired scaling factor(s) in horizontal and vertical direction.
This option will be ignored if the fitmethod property has been supplied with one of the keywords auto,
meet, slice, or entire. Default: 1
Table 10.8 PDF block properties
keyword
possible values and explanation
defaultpdf
(String) Path name of a PDF document which will be used if no substitution PDF is supplied by the client.
It is recommended to use file names without absolute paths, and use the SearchPath feature in the PPS
client application. This will make block processing independent from platform and file system details.
default-
pdfpage
(Integer) Page number of the page in the default PDF document. Default: 1
scale
(Float list) One or two values specifying the desired scaling factor(s) in horizontal and vertical direction.
This option will be ignored if the fitmethod property has been supplied with one of the keywords auto,
meet, slice, or entire. Default: 1
pdiusebox
(Keyword; possible values: media, crop, bleed, trim, art) Use the placed page’s MediaBox, CropBox,
BleedBox, TrimBox, or ArtBox for determining its size. Default: crop
Table 10.6 Textflow block properties
keyword
possible values and explanation
12
10.5 Standard Properties for Automated Processing 247
10.5.5 Custom Properties
Custom properties apply to blocks of any type of block (in addition to general and type-
specific properties). Custom properties are optional, and can not be shared. Table 10.9
lists the naming rules for custom properties.
Table 10.9 Custom block properties
keyword
possible values and explanation
any name not containing
the three characters [ ] /
(String, name, float, or float list) The interpretation of the values corresponding to cus-
tom properties is completely up to the client application.
42
248
Chapter 10: Variable Data and Blocks
10.6 Querying Block Names and Properties with pCOS
In addition to automatic block processing with PPS, the integrated pCOS facility can be
used to enumerate block names and query standard or custom properties.
Cookbook A full code sample for querying the properties of blocks contained in an imported PDF can be
found in the Cookbook topic blocks/query_block_properties.
Finding the numbers and names of blocks. The client code must not even know the
names or numbers of the blocks on an imported page since these can also be queried.
The following statement returns the number of blocks on page with number pagenum:
blockcount = (int) p.pcos_get_number(doc, "length:pages[" + pagenum + "]/blocks");
The following statement returns the name of block number blocknum on page pagenum
(block and page counting start at 0):
blockname = p.pcos_get_string(doc,
"pages[" + pagenum + "]/blocks[" + blocknum + "]/Name");
The returned block name can subsequently be used to query the block’s properties or
populate the block with text, image, or PDF content. If the specified block doesn’t exist
an exception will be thrown. You can avoid this by using the length prefix to determine
the number of blocks and therefore the maximum index in the Blocks array (remember
that the block count will be 1 higher than the highest possible index since array index-
ing starts at 0).
In the path syntax for addressing block properties the following expressions are
equivalent, assuming that the block with the sequential <number> has its Name proper-
ty set to <blockname>:
pages[...]/blocks[<number>]
pages[...]/blocks/<blockname>
Finding block coordinates. The two coordinate pairs (llx, lly) and (urx, ury) describing
the lower left and upper right corner of a block named foo can be queried as follows:
llx = p.pcos_get_number(doc, "pages[" + pagenum + "]/blocks/foo/Rect[0]");
lly = p.pcos_get_number(doc, "pages[" + pagenum + "]/blocks/foo/Rect[1]");
urx = p.pcos_get_number(doc, "pages[" + pagenum + "]/blocks/foo/Rect[2]");
ury = p.pcos_get_number(doc, "pages[" + pagenum + "]/blocks/foo/Rect[3]");
Note that these coordinates are provided in the default user coordinate system (with
the origin in the bottom left corner, possibly modified by the page’s CropBox), while the
Block plugin displays the coordinates according to Acrobat’s user interface coordinate
system with an origin in the upper left corner of the page. Since the Rect option for over-
riding block coordinates does not take into account any modifications applied by the
CropBox entry, the coordinates queried from the original block cannot be directly used
as new coordinates if a CropBox is present. As a workaround you can use the refpoint
and boxsize options.
Also note that the topdown parameter is not taken into account when querying block
coordinates.
24
10.6 Querying Block Names and Properties with pCOS 249
Querying custom properties. Custom properties can be queried as in the following ex-
ample, where the property zipcode is queried from a block named b1 on page pagenum:
zip = p.pcos_get_string(doc, "pages[" + pagenum + "]/blocks/b1/Custom/zipcode");
If you don’t know which custom properties are actually present in a block, you can de-
termine the names at runtime. In order to find the name of the first custom property in
a block named b1 use the following:
propname = p.pcos_get_string(doc, "pages[" + pagenum + "]/blocks/b1/Custom[0].key");
Use increasing indexes instead of 0 in order to determine the names of all custom prop-
erties. Use the length prefix to determine the number of custom properties.
Non-existing block properties and default values. Use the type prefix to determine
whether a block or property is actually present. If the type for a path is 0 or null the re-
spective object is not present in the PDF document. Note that for standard properties
this means that the default value of the property will be used.
Name space for custom properties. In order to avoid confusion when PDF documents
from different sources are exchanged, it is recommended to use an Internet domain
name as a company-specific prefix in all custom property names, followed by a colon ’:’
and the actual property name. For example, ACME corporation would use the following
property names:
acme.com:digits
acme.com:refnumber
Since standard and custom properties are stored differently in the block, standard
PDFlib property names (as defined in Section 10.5, »Standard Properties for Automated
Processing«, page 240) will never conflict with custom property names.
55
250
Chapter 10: Variable Data and Blocks
10.7 PDFlib Block Specification
The PDFlib Block syntax is fully compliant with the PDF Reference, which specifies an
extension mechanism that allows applications to store private data attached to the data
structures comprising a PDF page. A detailed description of the PDFlib block syntax is
provided here for the benefit of users who wish to create PDFlib blocks by other means
than the PDFlib block plugin. Plugin users can safely skip this section.
10.7.1 PDF Object Structure for PDFlib Blocks
The page dictionary contains a /PieceInfo entry, which has another dictionary as value.
This dictionary contains the key /PDFlib with an application data dictionary as value.
The application data dictionary contains two standard keys listed in Table 10.10.
A Block list is a dictionary containing general information about block processing, plus
a list of all blocks on the page. Table 10.11 lists the keys in a block list dictionary.
Data types for block properties. Properties support the same data types as option lists
except handles and specialized lists such as action lists. Table 10.12 details how these
types are mapped to PDF data types.
Table 10.10 Entries in a PDFlib application data dictionary
key
value
LastModified (Data string; required) The date and time when the blocks on the page were created or most recently
modified.
Private
(Dictionary; required) A block list (see Table 10.11)
Table 10.11 Entries in a block list dictionary
key
value
Version
(Number; required) The version number of the block specification to which the file complies. This docu-
ment describes version 7 of the block specification.
Blocks
(Dictionary; required) Each key is a name object containing the name of a block; the corresponding value
is the block dictionary for this block (see Table 10.13). The /Name key in the block dictionary must be iden-
tical to the block’s name in this dictionary.
PluginVersion
(String; required unless the pdfmark key is present
1
) A string containing a version identification of the
PDFlib Block plugin which has been used to create the blocks.
1. Exactly one of the PluginVersion and pdfmark keys must be present.
pdfmark
(Boolean; required unless the PluginVersion key is present
1
) Must be true if the block list has been gen-
erated by use of pdfmarks.
Table 10.12 Data types for block properties
block type
PDF type and remarks
boolean
(Boolean)
string
(String)
keyword
(name)
(Name) It is an error to provide keywords outside the list of keywords supported by a particular property.
Documents you may be interested
Documents you may be interested
