CIB pdf toolbox technical guide (EN)
15. Stationary function, overly of texts, graphics and barcodes
15.2. Overlay function
GeneralText
Graphic
Barcode
Releaseplan
General
The overlay function for the CIB pdf toolbox allows the insertion of graphics and text at any position in PDF files. In the following, the entire range of functions is specified in more detail.
By specifying the "Overlay" property when calling PDF-Join, instructions for the overlay function can be specified. The "Overlay" property contains the following information:
- A plane and position indication with optional size indication. For graphics, it is possible to specify their height and width, for texts this specification is omitted.
- A font specification (for texts) with optional rotation.
- A page selection with and without priorities.
- Additional data, consisting alternatively of:
- A filename.
- A text string, which can optionally contain {PAGE}, {NUMPAGES} or {DATE} in the middle.
- A barcode specification, starting with „BARCODE:“
<Overlay>:= <TextOverlay>*;<GrafikOverlay>*;<BarcodeOverlay>*
<TextOverlay>:=
POS:Plane|X-Position;Y-Position;PageReference;FONT:Font;Font-Size;Font-Style;Font-Color;[Orientation] (since Toolbox 1.2.56);Text
<GrafikOverlay>:= (since Toolbox 1.2.56) :=
POS:Plane|X-Position,Width;Y-Position,Height;PageReference;Graphic
<BarcodeOverlay>:= (since Toolbox 1.4.84):=
POS:Plane;X-Position;Y-Position;PageReference;BARCODE:Type;Value;Orientation;Width;Height;CheckNumber
These property specifications are specified in more detail below, divided into text, graphics and barcodes. These can be specified in the "Overlay" property as often as required, separated by ";". Please note that the keyword specification is case-sensitive.Text
The texts specified in the "Overlay" property are placed at the desired position in the result document of the join.
The priorities are regulated here in the same way as described in the Stationery section.
The keyword POS: identifies the position part of the specification and the keyword FONT: the part containing the font information.
Name |
Value |
Effect |
Plane |
Negative number |
Arrangement behind all elements that are already in the document. The smaller the number, the further back the text is inserted. (To arrange several texts in the background) |
Positive Number (including 0) |
0 indicates the text that is inserted first. The larger the number, the further ahead the text is inserted. A positive number means that the text will be placed in front of all elements already in the document.
|
|
“Top” |
Right in the front. If several texts are marked by "Top", they are inserted in the call sequence, i.e. the text mentioned last is placed at the very front of the document. |
|
not specified (The separator must still be specified). |
Corresponds to „-1“
Note: As separators "|" or "/" are possible. |
|
X-Position |
„Center“ |
Center on page in horizontal direction. |
0 or not specified |
Left margin |
|
Number > 0 |
Distance from left in mm |
|
Y-Position |
„Center“ |
Center on page in vertical direction. |
0 or not specified |
Upper margin |
|
Number > 0 |
Distance from top in mm |
|
Font |
Helvetica Courier Times |
The font can be specified here. Possible are the Type1 standard fonts from Pdf. |
Font-Size |
Positive number Half steps also possible e.g. 3.5 Alternatively, by specifying <width>,<height> a dynamic font size is possible. (since CIB pdf toolbox 1.4.78) |
Font size in pt or width and height in mm.
The text is enlarged proportionally until it reaches the smaller value of width or height. Possible rotations only take place after scaling. |
Font-Style |
bold |
Text is printed bold |
italic |
Text is printed in italics |
|
Font-Color |
RGB code, components separated by dots. (R.G.B) Example: 0.0.0 = Black 255.0.0 = Red 0.128.0 = Green 0.0.255 = Blue Default: black (the separator ";" must still be specified) |
The text is displayed in the specified color. The colour components must be indicated separated by dots. |
Orientation (since CIB pdf toolbox 1.2.56) |
Angle > 0 |
The text is rotated clockwise by this angle |
Page number(s) |
Not specified or “All” |
Distribute on all pages |
“Odd” |
Distribute on odd pages |
|
“Even” |
Distribute on even pages |
|
“First” |
Only on the first page |
|
“Last” |
Only on the last page |
|
“NoFirst” |
All pages except the first |
|
“NoLast” |
All pages except the last |
|
Number1-Number2 |
From page Number1 to Number2 |
|
Number1-Number2,Number3, ...,NumberN-NumberM |
Distribute on several pages or page areas (comma as separator) |
|
Text (at this time any text and {PAGE},{DATE},{NUMPAGES} is supported (without start number and number type), since CIB pdf toolbox 1.2.56) |
Any text (can also contain the following Word fields) |
The specified text is inserted into the document. If several Word fields are entered consecutively, they must be separated by at least one blank. |
{PAGE \* start number \* number type} The following values are possible for "numbertype": Arabic = 1,2,3.... ArabicDash = -1-,-2-,-3-... alphabetic = a,b,c.... ALPHABETIC = A,B,C… roman = i,ii,iii…. ROMAN = I,II,III.... |
Inserts the current page number, the options allow you to specify start number and type of numbering. |
|
{NUMPAGES \*numbertype} |
Inserts the number of pages in the document. |
|
{DATE \@ dd.MM.yyyy hh:mm:ss} |
Inserts the current date in the desired format. |
The page specifications have different priorities, so that lower priorities can be overwritten by higher ones. The priorities are distributed as follows:
Priority None: All, Odd, Even, NoLast, NoFirst
Priority DIRECT: Last, First, Number
Priority RANGE: Number1 – Number2
The following order of priority applies: Priority None < RANGE < DIRECT
If two indications concerning a particular page have the same priority, both apply, otherwise the one with the higher priority applies and the lower priority indication is not applied.
The examples show possible calls via the CIB runshell.
The command line of the examples reads as follows:
- Property Overlay
- Runshellcommand PDF-Join = cibrsh.exe –fj
- input output
- cibrsh.exe Overlay=“POS:-1|Center;20;All;FONT:Helvetica;12;bold;0.0.0;;Infoblatt” –fj inhalt.pdf output.pdf
Here the text "Info sheet" is inserted
on the backmost level (-1), centered in horizontal direction (Center), 2 cm
from the top edge (20), in Helvetica font and font size 12, bold, on all pages
(All) of the document content.pdf with the font color black. The
result is returned in output.pdf.
- cibrsh.exe Overlay=“POS:Top|180;280;All;FONT:Helvetica;10;italic;255.0.0;;{PAGE}“–fj inhalt.pdf output.pdf
Here, on the front level (Top) 18 cm from the left and 28 cm from the top in Helvetica font and font size 10 italics, the current page number is inserted on each page of the document input.pdf in Arabic with font colour red (1,2,3...). The result is returned in output.pdf.
- cibrsh.exe Overlay=“
POS:2|20;20;First,Last;FONT:Helvetica;24;;0.0.255;;TextVorn;
POS:1|30;30;First,Last;FONT:Helvetica;24;;255.0.0;;TextMitte;
POS:0|40;40;First,Last;FONT:Helvetica;24;;0.128.0;;TextHinten;
“ –fj inhalt.pdf output.pdf
Here, first 4cm left and right from the edge are removed, the text " TextBack" is inserted in Helvetica font and font size 24 with font color green on the first and last page of the document input.pdf.
Before this (1) 3cm from both edges are removed. The text "TextMiddle" with font colour red and again in front of (2) 2cm from the edge "TextFront" "with font colour blue is inserted. This allows the effect that several texts are written offset one above the other. The result is returned in output.pdf.
Graphic
This functionality is supported since Toolbox 1.2.56. The formats allowed so far are bmp, jpg, gif and png.
The graphics specified in the "Overlay" property are placed at the desired position in the result document of the join.
The priorities are regulated here in the same way as described in the Stationery section.
The "Overlay" property is assigned as follows:
[POS:Layer|X-Position,Width;Y-Position,Height;]Page Specifications;Graphic
Name |
Value |
Effect |
Layer Same as Text |
|
|
X-Position Same as Text |
|
|
Width |
“ScaleToPage” |
Adjust to page width. |
0 or not specified |
Original width of the graphic(1 pixel=1 pt=1/72in) |
|
Number > 0 |
Width of the graphic in mm. |
|
Y-Position Same as Text |
|
|
Height |
“ScaleToPage” |
Auf Adjust to page height. |
0 or not specified |
Original height of the graphic(1 pixel=1 pt=1/72in) |
|
Number > 0 |
Height of the graphic in mm. |
|
Page number(s) Same as Text |
|
|
Graphic |
Path to graphic file |
The graphic from this file is inserted |
(since version 1.4.83) MEMORYBLOCK: <memoryblock-Delimiter>;<memoryblocks> <memoryblocks> ::= memoryblock::=
|
The graphic can also be transferred in memory. For this purpose the memory addresses are transferred to the CIB pdf toolbox. A <memory block delimiter> is a single character unequal to ";", which if possible does not occur in a file name, e.g. "#", "?". Address and length are decimal numbers. |
Instead of a file name, you can specify that a colored rectangle, line or Bezier curve is to be placed at the specified location. The file name must then be replaced as follows:
RECT:Color[;Orientation;Transparency]
LINETO:Color;X2,Y2
BEZIERTO:Color;SX1,SY1,SX2,SY2,X2,Y2
Lines and Bezier curves have no width and height indication. They cannot be centered using the "Center" value for X and Y position. The specification of this value is interpreted as "-1".
Name |
Value |
Effect |
RECT: Color (since CIB pdf toolbox 1.2.56) LINETO: Color BEZIERTO: Color (since CIB pdf toolbox 1.4.75) |
RGB code, components separated by dots. [R.G.B.] Examples: 0.0.0 = black 255.0.0 = red 0.128.0 = green 0.0.255 = blue |
The rectangle or line or Bezier curve is displayed in the specified color. The colour components are to be indicated separated by dots. |
Orientation |
> 0 |
Rectangle is rotated clockwise by the specified angle. |
Transparency |
> 0 |
Degree of transparency for the rectangle Example: 75 means that the rectangle is 75% transparent. A transparency of 100% means that the rectangle becomes invisible. |
X2 (X coordinate for the end point of the line or Bezier curve)) |
0 |
Left margin |
|
Number > 0 |
Distance from left in mm. |
Y2 (Y-coordinate for the end point of the line or Bezier curve) |
0 |
Upper edge. |
|
Number > 0 |
Distance from top in mm. |
SX1, SX2 (X-coordinates for the first and second point of the Bezier curve) |
0 |
Left edge. |
|
Number > 0 |
Distance from left in mm. |
SY1, SY2 (Y-coordinates for the first and second point of the Bezier curve) |
0 |
Upper edge. |
|
Number > 0 |
Distance from top in mm. |
The examples show possible calls via the CIB runshell.
The command line of the examples reads as follows:
- Property Overlay
- Runshellkommando PDF-Join = cibrsh.exe –fj
- input output
1) cibrsh.exe Overlay=“POS:-1|Center,100;Center,100;Odd;Graphic.jpg“ –fj content.pdf output.pdf
Here, on the backmost level (-1), centered in X-direction and Y-direction (Center), the image Graphic.pdf is inserted on all odd pages (Odd) of the document content.pdf. This will be scaled to the dimensions 10x10 cm. The result is returned in output.pdf.
2) cibrsh.exe Overlay=“POS:Top|20,0;Center,0;2-8;Graphic.jpg“ –fj content.pdf output.pdf
Here, the image Graphic.jpg in original size is inserted on the front level (Top) 2 cm from the left and centered in Y-direction on pages 2-8 of the document Input.pdf The result is returned in output.pdf.cibrsh.exe Overlay=“POS:Top|Center,ScaleToPage;Center,ScaleToPage;First;Grafik.jpg“ –fj inhalt.pdf output.pdf
Here, the image Graphic.jpg is inserted on the top level (Top), page-centered in both X and Y direction, on the first page of the document input.pdf. The image is scaled to the dimensions of the page. The result is returned in output.pdf.
3) cibrsh.exe Overlay=“POS: Top|180,10;280,10;All;RECT: 255.255.255;POS:Top|180;280;All;FONT:Helvetica;10;italic;0.0.0;;{PAGE}“ –fj content.pdf output.pdf
Here, a white rectangle measuring 1cm x 1cm is first inserted on the front level (top) 18 cm from the left and 28 cm from the top. Then, in Helvetica font and font size 10 italics, the current page number is inserted in Arabic at this point on each page of the document input.pdf (1,2,3...) The result is returned in output.pdf.
4) cibrsh.exe Overlay=“POS:Top|0;0;All;LINETO: 255.0.0;210,297;“ –fj content.pdf output.pdf
Here, a red line is inserted at the front level (Top) from the upper left edge (0.0) to the lower right edge (210.297). The result is returned in output.pdf.
5) cibrsh.exe Overlay=“ POS:Top|0;150;All;BEZIERTO: 255.255.255;100,60,150,110,210,150“ –fj content.pdf output.pdf
Here, a red Bezier curve with a starting point (0,150), end point (210,150) and the support points (100,60) and (150,110) is inserted at the front level (Top). The result is returned in output.pdf.
Barcode
(since CIB pdf toolbox Release 1.4.84)
The barcodes specified in the "Overlay" property are placed at the desired position in the result document of the join.
The priorities are regulated here in the same way as described in the Stationery section
The "Overlay" property is assigned as follows:
[POS:Level|X-Position;Y-Position;] PageReferences;BARCODE:Type;Value;Orientation;Width;Height;CheckDigit;CodePage
QR [POS:Level|X-Position;Y-Position;] PageReferences;BARCODE:QR;Type;Value;Orientation;Width;Height;CheckDigit;CodePage;CorrectionLevel
Name |
Value |
Effect |
Level Same as Text |
|
|
X-Position Same as Text |
|
|
Y-Position Same as Text |
|
|
Pagenumber(s) Same as Text |
|
|
Type |
A barcode type from the set of types supported by CIB format:
Code ITF Code 2/5 Industry Code 2/5 Matrix Code 39 Code 39 extended Code 128 (A, B, C) EAN 8 EAN 13 EAN 128 DataMatrix PDF417 Code 93 Code 93 Extended OMR Barcodes QR |
This barcode type is used |
Value |
Numbers |
The individual value that the barcode should represent. |
Orientation |
horizontalleft |
Vertical lines side by side, first character left.
|
horizontalright |
Vertical lines side by side, first character on the right. |
|
verticalleft |
Horizontal lines below each other, first character on top. |
|
verticalright |
Horizontal lines above each other, first character below. |
|
Width |
Line width in mm (x.xmm; or x,xmm both allowed) |
Sets the bar width of the barcode |
Height |
Height of the barcode bars in mm (x.xmm; or x,xmm both allowed) |
Sets the height of the barcode bars |
Check digit / CorrectionLevel
(since version 1.26.0) |
default |
Barcode is generated with check digit |
nochecksum |
Barcode is generated without check digit |
|
The check digit is not available for 2D barcodes (QR). The default is therefore nochecksum. However, the correction level (ECL) can be specified here. The level goes from 0 (low correction) to 3 (maximum correction = default). |
|
|
Codepage |
Specifies code page for QR barcode data. Default: Ansi; Possible Values:
|
Note: |
Size (since version 1.26.0) |
QR Code: The size has not been used so far. Now the version can be specified here. |
The size of the QR Code is determined by the version. Example: |
For the assignment of the parameters after "value", please refer to the corresponding documentation regarding barcode realization in CIB format. Which parameters must be assigned which value depends strongly on the barcode type.
Releaseplan
The overlay function is implemented in several stages. The functionality must be implemented according to the following step plan:
- Specification of the Word mail merge field {PAGE} with default option Arabic, possibility to specify font, size, color and position of the text itself.
- Logos without rotation.
- arbitrary text with rotation.
- Support for other fields (like {NUMPAGES} or {DATE} with options anywhere in the text.
- Barcode support.
It must be examined to what extent the layer function can be used or supported. Please note that this is not included in PDF 1.3 and is not supported by older viewers.
Since Toolbox 1.2.56, overlay of text (including rotation), graphics and rectangles are supported.