63
6.2 Creating PDFlib Blocks 133
Shared properties. By holding the shift key and using the block tool to select several
blocks you can select an arbitrary number of blocks. The Enter key will display the prop-
erties dialog which now applies to all selected blocks. However, since not all properties
can be shared among multiple blocks, only a subset of all properties will be available for
editing. Section 6.3, »Standard Properties for automated Processing«, page 135, details
which properties can be shared among multiple blocks. Custom properties cannot be
shared.
6.2.4 Converting PDF Form Fields to PDFlib Blocks
As an alternative to creating PDFlib blocks manually you can automatically convert PDF
form fields to blocks. This is especially convenient if you have complicated PDF forms
which you want to fill automatically with PDFlib, or need to convert a large number of
existing PDF forms for automated filling. In order to convert all form fields on a page to
PDFlib blocks choose PDFlib Blocks, Convert Form Fields, Current Page. To convert all form
fields in a document choose All Pages instead. Finally, you can convert only selected
form fields (choose Acrobat’s Form Tool or the Select Object Tool to select form fields)
with Selected Form Fields.
Form field conversion details. Automatic form field conversion will convert form
fields of the types selected in the PDFlib Blocks, Convert Form Fields, Conversion Options...
dialog to blocks of type Text. By default all form field types will be converted. Attributes
of the converted fields will be transformed to the corresponding block properties ac-
cording to Table 6.2.
Table 6.2 Conversion of PDF form fields to PDFlib blocks
PDF form field attribute...
...will be converted to the PDFlib block property
all fields
Position
General, Rect
Name
General, Name
Short Description
General, Description
Appearance, Text, Font
Text, fontname
Appearance, Text, Size
Text, fontsize; »auto« font size will be converted to a fixed font size
of 2/3 of the block height, and the fitmethod will be set to »auto«
Appearance, Text, Text Color
Text, textcolor and Text, fillcolor
Appearance, Border, Border Color
General, bordercolor
Appearance, Border, Background Color
General, backgroundcolor
Appearance, Border, Width
General, linewidth: Thin=1, Medium=2, Thick=3
Appearance, Common Properties, Form
Field is...
General, Status: Visible=active, Hidden=ignore, Visible but doesn’t
print=ignore, Hidden but printable=active
Appearance, Common Prop., Orientation
General, orientate: 0=north, 90=west, 180=south, 270=east
text fields
Options, Default
Text, defaulttext
Options, Alignment
General, position: Left={0 50}, Center={50 50}, Right={100, 50}
radio buttons and check boxes
If »Default is Checked« is selected:
Options, Radio Style and
Options, Check Style
Text, defaulttext: Check=4, Circle=l, Cross=8, Diamond=u,
Square=n, Star=H (these characters represent the respective
symbols in the ZapfDingbats font)
37
134
Chapter 6: Variable Data and Blocks
Binding blocks to the corresponding form fields. In order to keep PDF form fields and
the generated PDFlib blocks synchronized, the generated blocks can be bound to the cor-
responding form fields. This means that the block tool will internally maintain the rela-
tionship of form fields and blocks. When the conversion process is activated again,
bound blocks will be updated to reflect the attributes of the corresponding PDF form
fields. Bound blocks are useful to avoid duplicate work: when a form is updated for in-
teractive use, the corresponding blocks can automatically be updated, too.
If you do not want to keep the converted form fields after blocks have been generat-
ed you can choose the option Delete converted Form Fields in the PDFlib Blocks, Convert
Form Fields, Conversion Options... dialog. This option will permanently remove the form
fields after the conversion process. Any actions (e.g., JavaScript) associated with the af-
fected fields will also be removed from the document.
Batch conversion. If you have many PDF documents with form fields that you want to
convert to PDFlib blocks you can automatically process an arbitrary number of docu-
ments using the batch conversion feature. The batch processing dialog is available via
PDFlib Blocks, Convert Form Fields, Batch conversion...:
>The input files can be selected individually; alternatively the full contents of a folder
can be processed.
>The output files can be written to the same folder where the input files are, or to a
different folder. The output files can receive a prefix to their name in order to distin-
guish them from the input files.
>When processing a large number of documents it is recommended to specify a log
file. After the conversion it will contain a full list of processed files as well as details
regarding the result of each conversion along with possible error messages.
During the conversion process the converted PDF documents will be visible in Acrobat,
but you cannot use any of Acrobat’s menu functions or tools.
List boxes and combo boxes
Options, Selected (default) item
Text, defaulttext
buttons
Options, Button Face Attributes, Text
Text, defaulttext
Table 6.2 Conversion of PDF form fields to PDFlib blocks
PDF form field attribute...
...will be converted to the PDFlib block property
56
6.3 Standard Properties for automated Processing 135
6.3 Standard Properties for automated Processing
PDFlib supports general properties which can be assigned to any type of block. In addi-
tion there are properties which are specific to the block types Text, Image, and PDF. Some
properties are shared, which means that they can be assigned to multiple blocks at once
using the Block plugin.
Properties support the same data types as option lists (see Section 3.1.4, »Option
Lists«, page 44) except handles.
Many block properties have the same name as options for PDF_fit_image( ) (e.g.,
fitmethod) and other functions, or as PDFlib parameters (e.g., charspacing). In these cases
the behavior is exactly the same as the one documented for the respective option or pa-
rameter.
Property processing in PDFlib. The PDFlib Block functions PDF_fill_*block( ) will process
block properties in the following order:
>If the backgroundcolor property is present and contains a color space keyword differ-
ent from None, the block rectangle will be filled with the specified color.
>All other properties except bordercolor and linewidth will be processed.
>If the bordercolor property is present and contains a color space keyword different
from None, the block rectangle will be stroked with the specified color and linewidth.
There will be no clipping; if you want to make sure that the block contents do not ex-
ceed the block rectangle choose fitmethod clip.
If a separation color is used in a block property the specified spot color name must
either be known to PDFlib internally (see Section 3.3.3, »Spot Colors«, page 60), or must
have been specified earlier in the PDFlib client program using PDF_makespotcolor( ). Oth-
erwise the block functions will fail.
General properties. General properties apply to all kinds of blocks (Text, Image, PDF).
They are required for block administration, describe the appearance of the block rectan-
gle itself, and manage how the contents will be placed within block. Required entries
will automatically be generated by the PDFlib Block Plugin. Table 6.3 lists the general
properties.
Table 6.3 General block properties
keyword
type
possible values and explanation
block administration
Name
string
(Required) Name of the block; maximum length is 127 bytes. Block names
must be unique within a page, but not within a document. The three
characters [ ] / are not allowed in block names.
Description
string
Human-readable description of the block’s function, coded in PDFDocEn-
coding or Unicode (in the latter case starting with a BOM). This property is
for user information only, and will be ignored when processing the block.
Locked
boolean
(Shareable) If true, the block and its properties can not be edited with the
Block plugin. This property will be ignored when processing the block.
Default: false.
Rect
float list
(Required) Four coordinates of the block (lower left and upper right
corner). The origin of the coordinate system is in the lower left corner of
the page. However, the Block plugin will display the coordinates in
Acrobat’s notation, i.e., with the origin in the upper left corner of the page.
99
136
Chapter 6: Variable Data and Blocks
Text-related properties. Text-related properties apply to blocks of type Text (in addi-
tion to general properties). All text-related properties can be shared. The encoding for
the text must be specified as an option for PDF_fill_textblock( ) when filling the block. Ta-
ble 6.4 lists the text-related properties.
Status
keyword
Keyword describing how this block will be processed (Default: active):
active
The block will be fully processed according to its properties.
ignore
The block will be ignored.
static
No variable contents will be placed; instead, the block’s default
text, image, or PDF contents will be used if available.
Subtype
keyword
(Required) Depending on the block type, one of Text, Image, or PDF.
Type
keyword
(Required) Always Block
block appearance
backgroundcolor
color
(Shareable) If this property is present and contains a color space keyword
different from None, a rectangle will be drawn and filled with the supplied
color. This may be useful to cover existing page contents. Default: None.
bordercolor
color
(Shareable) If this property is present and contains a color space keyword
different from None, a rectangle will be drawn and stroked with the
supplied color. Default: None
linewidth
float
(Shareable) Stroke width of the line used to draw the block rectangle; only
used if strokecolor is set. Default: 1
content placing
fitmethod
keyword
(Shareable) Strategy to use if the supplied content doesn’t fit into the box.
Possible values are auto, nofit, clip, meet, slice, and entire (see Table 7.23).
Default: nofit
orientate
keyword
(Shareable) Specifies the desired orientation of the content when it is
placed (see Table 7.23). Possible values are north, east, south, west. Default:
north
position
float list
(Shareable) One or two values specifying the position of the reference
point within the content (see Table 7.23). Default: 0
rotate
float
(Shareable) Rotation angle in degrees by which the block will be rotated
counter-clockwise before processing begins. The center of the rotation is
the reference point. Default: 0
Table 6.4 Text-related block properties
keyword
type
possible values and explanation
charspacing
float
The character spacing (see Table 7.9). Default: 0
defaulttext
string
Text which will be used if no substitution text is supplied by the client
1
fillcolor
color
Fill color of the text. Default: gray 0 (=black)
fontname
2
string
Name of the font as required by PDF_load_font( )
fontsize
2
float
Size of the font in points
fontstyle
keyword
Font style, must be one of normal, bold, italic, or bolditalic (see Table 7.7)
horizscaling
float
The horizontal text scaling (see Table 7.9). Default: 100
kerning
boolean
Kerning behavior (see Table 7.9). Default: false
margin
float list
One or two float values describing additional horizontal and vertical
extensions of the text box (see Table 7.10). Default: 0
overline
boolean
Overline mode (see Table 7.9). Default: false
Table 6.3 General block properties
keyword
type
possible values and explanation
76
6.3 Standard Properties for automated Processing 137
Image-related properties. Image-related properties apply to blocks of type Image (in
addition to general properties). All image-related properties can be shared. Table 6.5
lists the image-related properties.
PDF-related properties. PDF-related properties apply to blocks of type PDF (in addition
to general properties). All PDF-related properties can be shared. Table 6.6 lists the PDF-
related properties.
strikeout
boolean
Strikeout mode (see Table 7.9). Default: false
strokecolor
color
Stroke color of the text. Default: gray 0 (=black)
textrendering
int
The text rendering mode (see Table 4.4). Default: 0
textrise
float
The text rise parameter (see Table 7.9). Default: 0
underline
boolean
Underline mode (see Table 7.9). Default: false
wordspacing
float
The word spacing (see Table 7.9). Default: 0
1. The text will be interpreted in winansi encoding or Unicode.
2. This property is required in a text block; it will automatically be enforced by the PDFlib Block plugin.
Table 6.5 Image-related block properties
keyword
type
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 (see Section 3.1.6,
»Resource Configuration and File Searching«, page 47) in the PDFlib client
application. This will make block processing independent from platform
and file system details. When the block will be processed the image must
be supplied in a format which is supported by PDF_load_image( ).
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 otherwise. This
property will be ignored if the fitmethod property has been supplied with
one of the keywords 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 meet, slice, or entire. Default: 1
Table 6.6 PDF-related block properties
keyword
type
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 (see Section 3.1.6,
»Resource Configuration and File Searching«, page 47) in the PDFlib client
application. This will make block processing independent from platform
and file system details.
defaultpdfpage
float
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 meet, slice, or entire. Default: 1
Table 6.4 Text-related block properties
keyword
type
possible values and explanation
18
138
Chapter 6: Variable Data and Blocks
Custom properties. Custom properties apply to blocks of any type of block (in addi-
tion to general and type-specific properties). Custom properties are optional, and can
not be shared. Table 6.7 lists the PDF-related properties.
Table 6.7 Custom block properties
keyword
type
possible values and explanation
any name not
containing the three
characters [ ] /
string,
name,
float,
float list
The interpretation of the values corresponding to custom properties is
completely up to the client application.
40
6.4 Querying Block Names and Properties 139
6.4 Querying Block Names and Properties
In addition to automatic block processing PDFlib supports some features which can be
used to enumerate block names and query standard and custom properties.
Finding the number and names of Blocks. The client code must not even know the
names or number of the blocks on an imported page since these can also be queried. The
following statement returns the number of blocks on the page:
blockcount = PDF_get_pdi_value(p, "vdp/blockcount", doc, page, 0);
The following statement returns the name of block number 5 on the page (block count-
ing starts at 0), or an empty string if no such block exists (however, an exception will be
thrown if the pdiwarning parameter is set to true):
blockname = PDF_get_pdi_parameter(p, "vdp/Blocks[5]/Name", doc, page, 0, &len);
The returned block name can further be used to automatically fill the blocks using
PDFlib’s fill functions, or query block properties, or populate the block with text, image,
or PDF content.
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>:
Blocks[<number>]/
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 = PDF_get_pdi_value(p, "vdp/Blocks/foo/Rect[0]", doc, page, 0);
lly = PDF_get_pdi_value(p, "vdp/Blocks/foo/Rect[1]", doc, page, 0);
urx = PDF_get_pdi_value(p, "vdp/Blocks/foo/Rect[2]", doc, page, 0);
ury = PDF_get_pdi_value(p, "vdp/Blocks/foo/Rect[3]", doc, page, 0);
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 user interface coordinate
system with an origin in the top left corner of the page.
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 6.3, »Standard Properties for automated
Processing«, page 135) will never conflict with custom property names.
66
140
Chapter 6: Variable Data and Blocks
6.5 PDFlib Block Specification
The PDFlib Block syntax is fully compliant with the PDF Reference, which specifies an
extension mechanism which 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.
6.5.1 PDF Object Structure for PDFlib Blocks
The page dictionary contains a /PieceInfo entry, which has a dictionary as value. This dic-
tionary contains the key /PDFlib with an application data dictionary as value. The appli-
cation data dictionary contains two standard keys listed in Table 6.8.
A Block list is a dictionary containing general information about block processing, plus
a list of all blocks on the page. Table 6.9 lists the keys in a block list dictionary.
Block dictionaries may contain the keys in Table 6.10. Only keys from one of the Text,
Image or PDF groups may be present depending on the /Subtype key in the General
group. When a property has type keyword in one of the tables it must be written as a PDF
name.
Table 6.8 Entries in a PDFlib application data dictionary
Key
type
value
LastModified date 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 6.9)
Table 6.9 Entries in a block list dictionary
Key
type
value
Version
number
(Required) The version number of the block specification to which the file
complies. This document describes version x of the block specification.
Blocks
dictionary
(Required) Each key is a name object containing the name of a block; the corres-
ponding value is the block dictionary for this block (see Table 6.10). The /Name key
in the block dictionary must be identical to the block’s name in this dictionary.
PluginVersion
string
(Required unless the pdfmark key is present
1
) A string containing a version identi-
fication 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 generated by use of pdfmarks.
Table 6.10 Entries in a block dictionary
Key
type
value
General block properties
(Some keys are required) General block properties according to Table 6.3
text-related properties
(Optional) Text-related properties according to Table 6.4
image-related properties
(Optional) Image-related properties according to Table 6.5
PDF-related properties
(Optional) PDF-related properties according to Table 6.6
Documents you may be interested
Documents you may be interested
