60
12.6 Block Properties 375
12.6.6 Object Fitting Properties
Fitting properties are available for all Block types, although some properties are specific
to a certain Block type. They control how the contents will be placed in the Block:
>Table 12.10 lists fitting properties for Textline, Image, PDF, and Graphics Blocks
>Table 12.11 lists fitting properties for Textflow Blocks (mostly related to aspects of
vertical fitting).
The object fitting algorithm uses the Block rectangle as fitbox. Except for fitmethod=clip
there will be no clipping; if you want to make sure that the Block contents do not exceed
the Block rectangle avoid fitmethod=nofit.
Table 12.10 Fitting properties for Textline, Image, PDF, and Graphics Blocks
keyword
possible values and explanation
alignchar
(Unichar or keyword; only for Textline Blocks) If the specified character is found in the text, its lower left
corner will be aligned at the lower left corner of the Block rectangle. For horizontal text with
orientate=north or south the first value supplied in the position option defines the position. For hori-
zontal text with orientate=west or east the second value supplied in the position option defines the
position. This option will be ignored if the specified alignment character is not present in the text. The
value 0 and the keyword none suppress alignment characters. The specified fitmethod will be applied, al-
though the text cannot be placed within the Block rectangle because of the forced positioning of
alignchar. Default: none
dpi
(Float list; only for image Blocks) 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 otherwise. This property will be ignored if the fitmethod property has been supplied
with one of the keywords auto, meet, slice, or entire. Default: 0
fitmethod
(Keyword) Strategy to use if the supplied content doesn’t fit into the Block rectangle. Possible values are
auto, nofit, clip, meet, slice, and entire. For Textline Blocks, image, PDF, and graphics Blocks this prop-
erty will be interpreted according to the standard interpretation (default: meet). For Textflow Blocks
where the Block is too small for the text the interpretation is as follows:
auto
fontsize and leading will be decreased until the text fits.
nofit
Text will run beyond the bottom margin of the Block.
clip
Text will be clipped at the Block margin.
margin
(Float list; only for Textline Blocks) One or two float values describing additional horizontal and vertical
reduction of the Block rectangle. Default: 0
orientate
(Keyword) Specifies the desired orientation of the content when it is placed. Possible values are north,
east, south, west. Default: north
position
(Float list) One or two values specifying the position of the reference point within the content. The posi-
tion is specified as a percentage within the Block. Only for Textline Blocks: the keyword auto can be used
for the first value in the list. It indicates right if the writing direction of the text is from right to left (e.g.
for Arabic and Hebrew text), and left otherwise (e.g. for Latin text).
Default: {0 0}, i.e. the lower left corner
rotate
(Float) Rotation angle in degrees by which the Block will be rotated counter-clockwise before processing
begins. The reference point is center of the rotation. Default: 0
scale
(Float list; only for image, PDF, and Graphics Blocks) One or two values specifying the desired scaling fac-
tor(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
shrinklimit
(Float or percentage; only for Textline Blocks) The lower limit of the shrinkage factor which will be ap-
plied to fit text with fitmethod=auto. Default: 0.75
61
376
Chapter 12: PPS and the PDFlib Block Plugin
Table 12.11 Fitting properties for Textflow Blocks
keyword
possible values and explanation
firstlinedist
(Float, percentage, or keyword) The distance between the top of the Block rectangle 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.
fitmethod
(Keyword) Strategy to use if the supplied content doesn’t fit into the box. Possible values are auto, nofit,
clip. Default: auto. For Textflow Blocks where the Block is too small for the text the interpretation is as
follows:
auto
fontsize and leading will be decreased until the text fits.
nofit
Text will run beyond the bottom margin of the Block.
clip
Text will be clipped at the Block margin.
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 Block rectangle.
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.
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.
minfontsize
(Float or percentage) Minimum allowed font size when text is scaled down to fit into the Block rectangle
with fitmethod=auto when shrinklimit is exceeded. The limit is specified in user coordinates or as a
percentage of the height of the Block. If the limit is reached the text will be created with the specified
minfontsize as fontsize. Default: 0.1%
orientate
(Keyword) Specifies the desired orientation of the text when it is placed. Possible values are north, east,
south, west. Default: north
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
18
12.6 Block Properties 377
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.
Table 12.11 Fitting properties for Textflow Blocks
keyword
possible values and explanation
42
378
Chapter 12: PPS and the PDFlib Block Plugin
12.6.7 Properties for default Contents
Properties for default contents specify how to fill the Block if no specific contents are
provided. They are especially useful for the Preview feature since it will fill the Blocks
with their default contents. Table 12.12 lists properties for default contents.
12.6.8 Custom Properties
Custom properties apply to Blocks of any type of Block, and will be ignored by PPS and
the Preview feature. Table 12.13 lists the naming rules for custom properties.
Table 12.12 Properties for default contents
keyword
possible values and explanation
default-
graphics
(String; only for graphics Blocks) Path name of a graphics file which will be used if no graphics is supplied
by the client application.
1
1. It is recommended to use file names without absolute paths, and use the SearchPath feature in the PPS client application. This makes
Block processing independent from platform and file system details.
defaultimage
(String; only for image Blocks) Path name of an image which will be used if no image is supplied by the
client application.
1
defaultpdf
(String; only for PDF Blocks) Path name of a PDF document which will be used if no substitution PDF is
supplied by the client application.
1
default-
pdfpage
(Integer; only for PDF Blocks) Page number of the page in the default PDF document. Default: 1
defaulttext
(String; only for Textline and Textflow Blocks) Text which will be used if no variable text is supplied by the
client application
2
2. The text will be interpreted in winansi encoding or Unicode.
Table 12.13 Custom Block properties for all Block types
keyword
possible values and explanation
any name not containing
the three characters [ ] /
(String, name, float, or float list) The interpretation of the values of custom properties is
completely up to the client application; they will be ignored by PPS.
41
12.7 Querying Block Names and Properties with pCOS 379
12.7 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 number and names of Blocks. The client code must not even know the
names or number of 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
fill the Block with text, image, PDF or graphics contents. If the specified Block doesn’t
exist an exception will be thrown. You can avoid this by using the length prefix to deter-
mine the number of Blocks and therefore the maximum index in the blocks array (keep
in mind that the Block count will be one higher than the highest possible index since ar-
ray indexing 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>
Querying 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 coordinate system (with the ori-
gin 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. The values queried with the pCOS
pseudo object rect (all lowercase) take into account any relevant CropBox/MediaBox and
Rotate entries and normalize the order of the coordinates. In contrast, the values que-
ried with the native PDF key Rect cannot be directly used as new coordinates if a Crop-
Box is present.
Note that the topdown option is not taken into account when querying Block coordi-
nates.
25
380
Chapter 12: PPS and the PDFlib Block Plugin
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 predefined 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 PPS
property names (as defined in Section 12.6, »Block Properties«, page 367) will never con-
flict with custom property names.
Documents you may be interested
Documents you may be interested
