CIB pdf toolbox technischer Leitfaden (DE)

15. Briefpapierfunktion, Overlay von Texten, Grafiken und Barcodes

15.2. Overlayfunktion

Allgemein
Text
Grafik
Barcode
Releaseplan

Allgemein

Die Overlayfunktion für die CIB pdf toolbox ermöglicht das Einfügen von Grafiken und Text an beliebigen Positionen in PDF-Dateien. Im Folgenden wird der gesamte Funktionsumfang genauer spezifiziert.

Durch Angabe der Property „Overlay“ beim Aufruf von PDF-Join, können Anweisungen für die Overlay-Funktion festgelegt werden. Die Property „Overlay“ enthält folgende Informationen:

eine Ebenen- und Positionsangabe mit optionaler Größenangabe. Bei Grafiken ist es möglich deren Höhe und Breite anzugeben, bei Texten entfällt diese Angabe.
eine Fontangabe (bei Texten) mit optionaler Rotation.
eine Seitenauswahl mit und ohne Prioritäten
zusätzliche Daten, alternativ bestehend aus:
einem Dateinamen
einem Textstring, der optional mittendrin {PAGE}, {NUMPAGES} oder {DATE} enthalten kann.
einer Barcode-Angabe, beginnend mit „BARCODE:“

<Overlay>:= <TextOverlay>*;<GrafikOverlay>*;<BarcodeOverlay>*

<TextOverlay>:=

POS:Ebene|X-Position;Y-Position;Seitenangaben;FONT:Font;Font-Size;Font-Style;Font-Color;[Orientierung] ( ab Toolbox 1.2.56);Text

<GrafikOverlay>:= (ab Toolbox 1.2.56) :=

POS:Ebene|X-Position,Breite;Y-Position,Höhe;Seitenangaben;Grafik

<BarcodeOverlay>:= (ab Toolbox 1.4.84):=

POS:Ebene;X-Position;Y-Position;Seitenangaben;BARCODE:Typ;Wert;Orientierung;Breite;Höhe;Prüfziffer

Diese Property-Angaben werden im Folgenden näher spezifiziert

Text

Die in der Property„Overlay“ spezifizierten Texte werden an gewünschter Stelle im Ergebnisdokument des Joins platziert.

Die Prioritäten sind hier genauso geregelt, wie im Abschnitt Briefpapier beschrieben.

Das Keyword POS: kennzeichnet den Positionsteil der Angabe und das Keyword FONT: den Teil, der die Schriftinformationen enthält.

Bezeichnung	Wert	Wirkung
Ebene	Negative Zahl	Anordnung hinter allen Elementen, die sich bereits im Dokument befinden. Je kleiner die Zahl, desto weiter hinten wird der Text eingefügt. (Zur Anordnung mehrerer Texte im Hintergrund)
	Positive Zahl (einschließlich 0)	0 bezeichnet den Text, der als erstes eingefügt wird. Je größer die Zahl, desto weiter vorn wird der Text eingefügt. Eine positive Zahl bedeutet, dass der entsprechende Text, vor allen Elementen angeordnet wird, die sich bereits im Dokument befinden.
	“Top”	Ganz vorn. Wenn mehrere Texte durch „Top“ gekennzeichnet sind, werden sie in der Aufrufreihenfolge eingefügt, das heißt, der als letztes genannte Text kommt ganz vorne auf das Dokument.
	keine Angabe (Das Trennzeichen muss trotzdem angegeben werden.)	Entspricht „-1“ Achtung: Als Trennzeichen sind „\|“ oder „/“ möglich.
X-Position	„Center“	In horizontaler Richtung auf Seite zentrieren.
	0 oder keine Angabe	Linker Rand
	Zahl > 0	Abstand von links in mm
Y-Position	„Center“	In vertikaler Richtung auf Seite zentrieren.
	0 oder keine Angabe	Oberer Rand
	Zahl > 0	Abstand von oben in mm
Font	Helvetica Courier Times	Hier kann die Schriftart angegeben werden. Möglich sind die Type1 Standard Fonts von Pdf.
Font-Size	Positive Zahl Auch halbe Schritte möglich z.B. 3.5 Alternativ ist durch die Angabe von <width>,<height> *(ab CIB pdf toolbox 1.4.78)* eine dynamische Schriftgröße möglich.	Schriftgröße in pt oder Breite und Höhe in mm. Der Text wird proportional vergrößert bis er den kleineren Wert von Breite oder Höhe erreicht. Eventuelle Rotationen finden erst nach dem Skalieren statt.
Font-Style	bold	Text wird fett gedruckt
Font-Style	italic	Text wird kursiv gedruckt
Font-Color	RGB-Code, Komponenten durch Punkte getrennt. (R.G.B) Beispiele 0.0.0 = schwarz 255.0.0 = rot 0.128.0 = grün 0.0.255 = blau Default: schwarz (das Trennzeichen „;“ muss trotzdem angegeben werden)	Der Text wird in der angegebenen Farbe dargestellt. Die Farbanteile sind durch Punkte getrennt anzugeben.
Orientierung *(ab CIB pdf toolbox 1.2.56)*	Winkel > 0	Der Text wird um diesen Winkel im Uhrzeigersinn rotiert
Seitenzahl(en)	keine Angabe oder “All”	Auf allen Seiten verteilen
	“Odd”	Auf ungeraden Seiten verteilen
	“Even”	Auf geraden Seiten verteilen
	“First”	Nur auf der ersten Seite
	“Last”	Nur auf der letzten Seite
	“NoFirst”	Alle Seiten bis auf die erste
	“NoLast”	Alle Seiten bis auf der letzte
	Zahl1-Zahl2	Von Seite Zahl1 bis Zahl2
	Zahl1-Zahl2,Zahl3, ...,ZahlN-ZahlM	Auf mehren Seiten oder Seitenbereichen verteilen (Komma als Trennzeichen)
Text (zum jetzigen Zeitpunkt wird beliebiger Text und {PAGE},{DATE},{NUMPAGES} unterstützt (ohne Startnummer und Nummernart), ab CIB pdf toolbox 1.2.56)	Beliebiger Text (kann auch die folgenden Word-Felder enthalten)	Der angegebene Text wird ins Dokument eingefügt. Wenn mehrere Word-Felder nacheinander eingegeben werden, sind sie durch mindestens ein Leerzeichen zu trennen.
	{PAGE \* startnummer \* nummernart} Für „nummernart“ sind folgende Werte möglich: Arabic = 1,2,3.... ArabicDash = -1-,-2-,-3-... alphabetic = a,b,c.... ALPHABETIC = A,B,C… roman = i,ii,iii…. ROMAN = I,II,III....	Fügt die aktuelle Seitenzahl ein, über die Optionen lassen sich Startnummer und Art der Nummerierung angeben.
	{NUMPAGES \*nummernart}	Fügt die Anzahl der Seiten im Dokument ein.
	{DATE \@ dd.MM.yyyy hh:mm:ss}	Fügt aktuelles Datum in gewünschtem Format ein.

Hinweis zu den Seitenzahlen

Die Seitenangaben besitzen unterschiedliche Prioritäten, so dass niedrigere Prioritäten von höheren überschrieben werden können. Die Prioritäten sind wie folgt verteilt:

Priorität keine: All, Odd, Even, NoLast, NoFirst

Priorität DIRECT: Last, First, Zahl

Priorität RANGE: Zahl1 – Zahl2

Dabei gilt folgende Rangfolge: Keine Priorität < RANGE < DIRECT

Besitzen zwei Angaben, die eine bestimmte Seite betreffen,, gleiche Priorität, so gelten beide, ansonsten gilt die mit der höheren Priorität und die niedriger priorisierte Angabe wird nicht angewendet.

Beispiele

Die Beispiele zeigen mögliche Aufrufe über die CIB runshell.

Die Kommandozeile der Beispiele liest sich wie folgt:

Property Overlay
Runshellkommando 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

Hier wird auf hinterster Ebene (-1), zentriert in horizontaler Richtung (Center), 2 cm vom oberen Rand entfernt (20), in Schriftart Helvetica und Schriftgröße 12, fettgedruckt, auf allen Seiten (All) des Dokuments inhalt.pdf der Text „Infoblatt“ mit Schriftfarbe schwarz eingefügt. Das Ergebnis wird in output.pdf zurückgeliefert.

cibrsh.exe Overlay=“POS:Top|180;280;All;FONT:Helvetica;10;italic;255.0.0;;{PAGE}“–fj inhalt.pdf output.pdf

Hier wird auf vorderster Ebene (Top) 18 cm von links und 28 cm von oben in Schriftart Helvetica und Schriftgröße 10 kursiv auf jeder Seite des Dokuments input.pdf die aktuelle Seitennummer in Arabic mit Schriftfarbe rot eingefügt (1,2,3...). Das Ergebnis wird in output.pdf zurückgeliefert.

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

Hier wird zunächst 4cm links und rechts vom Rand entfernt, in Schriftart Helvetica und Schriftgröße 24 auf der ersten und der letzen Seite des Dokuments input.pdf der Text „TextHinten“ mit Schriftfarbe grün eingefügt. Davor (1) wird 3cm von beiden Rändern entfernt „TextMitte“ mit Schriftfarbe rot und wiederum davor (2) 2 cm vom Rand entfernt „TextVorn“ “ mit Schriftfarbe blau eingefügt. Dadurch lässt sich der Effekt erzielen, dass mehrere Texte versetzt übereinander geschrieben werden. Das Ergebnis wird in output.pdf zurückgeliefert.

Grafik

Diese Funktionalität wird ab Toolbox 1.2.56 unterstützt. Die bisher erlaubten Formate sind bmp, jpg, gif und png.

Die in der Property „Overlay“ spezifizierten Grafiken werden an gewünschter Stelle im Ergebnisdokument des Joins platziert.

Die Prioritäten sind hier genauso geregelt, wie im Abschnitt Briefpapier beschrieben.

Die Property „Overlay“ wird wie folgt belegt:

[POS:Ebene|X-Position,Breite;Y-Position,Höhe;]Seitenangaben;Grafik

Bezeichnung	Wert	Wirkung
Ebene wie Text
X-Position wie Text
Breite	“ScaleToPage”	Auf Seitenbreite anpassen
	0 oder keine Angabe	Original-Breite der Grafik(1 pixel=1 pt=1/72in)
	Zahl > 0	Breite der Grafik in mm
Y-Position wie Text
Höhe	“ScaleToPage”	Auf Seitenhöhe anpassen
	0 oder keine Angabe	Original-Höhe der Grafik(1 pixel=1 pt=1/72in)
	Zahl > 0	Höhe der Grafik in mm
Seitenzahl(en) wie Text
Grafik	Pfad zur Grafikdatei	Die Grafik aus dieser Datei wird eingefügt
Grafik	(ab Version 1.4.83) MEMORYBLOCK: <Speicherblock-Delimiter>;<Speicherblöcke> <Speicherblöcke> ::= <Speicherblock> [<Speicherblock-Delimiter> <Speicherblock>]... Speicherblock ::= <Adresse> <Speicherblock-Delimiter> <Länge>	Die Übergabe der Grafik kann auch im Speicher erfolgen. Dazu werden die Speicheradressen an die CIB pdf toolbox übergeben. Ein <Speicherblock-Delimiter> ist ein einzelnes Zeichen ungleich „;“, das möglichst nicht in einem Filenamen vorkommt, z.B. „#“, „?“. Adresse und Länge sind Dezimalzahlen.

Anstelle eines Dateinamens kann angegeben werden, dass ein farbiges Rechteck, eine Linie oder eine Bezier-Kurve an der spezifizierten Stelle platziert werden soll. Der Dateiname muss dann wie folgt ersetzt werden:

RECT:Color[;Orientierung;Transparenz]

LINETO:Color;X2,Y2

BEZIERTO:Color;SX1,SY1,SX2,SY2,X2,Y2

Linien und Bezier-Kurven haben keine Breiten- und Höhenangabe. Sie können nicht über den Wert „Center“ für X- und Y-Position zentriert werden. Die Angabe dieses Wertes wird als „-1“ interpretiert.

Bezeichnung	Wert	Wirkung
RECT: Color (ab CIB pdf toolbox 1.2.56) LINETO: Color BEZIERTO: Color (ab CIB pdf toolbox 1.4.75)	RGB-Code, Komponenten durch Punkte getrennt. (R.G.B) Beispiele 0.0.0 = schwarz 255.0.0 = rot 0.128.0 = grün 0.0.255 = blau	Das Rechteck bzw. die Linie oder Bezier-Kurve wird in der angegebenen Farbe dargestellt. Die Farbanteile sind durch Punkte getrennt anzugeben.
Orientierung	> 0	Rechteck wird um den angegebenenWinkel im Uhrzeigersinn gedreht.
Transparenz	> 0	Grad der Transparenz für das Rechteck Beispiel: 75 bedeutet, dass das Rechteck 75% transparent dargestellt wird. Eine Transparenz von 100% bedeutet, dass das Rechteck unsichtbar wird.
X2 (X-Koordinate für den Endpunkt der Linie bzw. Bezier-Kurve)	0	Linker Rand.
	Zahl > 0	Abstand von links in mm.
Y2 (Y-Koordinate für den Endpunkt der Linie bzw. Bezier-Kurve)	0	Oberer Rand.
	Zahl > 0	Abstand von oben in mm.
SX1, SX2 (X-Koordinaten für den ersten und zweiten Stützpunkt der Bezier-Kurve)	0	Linker Rand.
	Zahl > 0	Abstand von links in mm.
SY1, SY2 (Y-Koordinaten für den ersten und zweiten Stützpunkt der Bezier-Kurve)	0	Oberer Rand.
	Zahl > 0	Abstand von oben in mm.

Beispiele

Die Beispiele zeigen mögliche Aufrufe über die CIB runshell.

Die Kommandozeile der Beispiele liest sich wie folgt:

Property Overlay
Runshellkommando PDF-Join = cibrsh.exe –fj
input output

1) cibrsh.exe Overlay=“POS:-1|Center,100;Center,100;Odd;Grafik.jpg“ –fj inhalt.pdf output.pdf

Hier wird auf hinterster Ebene (-1), zentriert in X-Richtung und Y-Richtung (Center), auf allen ungeraden Seiten (Odd) des Dokuments inhalt.pdf das Bild Grafik.pdf eingefügt. Dieses wird auf die Maße 10x10 cm skaliert. Das Ergebnis wird in output.pdf zurückgeliefert.

2) cibrsh.exe Overlay=“POS:Top|20,0;Center,0;2-8;Grafik.jpg“ –fj inhalt.pdf output.pdf

Hier wird auf vorderster Ebene (Top) 2 cm von links und zentriert in Y-Richtung auf den Seiten 2-8 des Dokuments input.pdf das Bild Grafik.jpg in Originalgröße eingefügt. Das Ergebnis wird in output.pdf zurückgeliefert.

3) cibrsh.exe Overlay=“POS:Top|Center,ScaleToPage;Center,ScaleToPage;First;Grafik.jpg“ –fj inhalt.pdf output.pdf

Hier wird auf vorderster Ebene (Top) seitenzentriert sowohl in X- als auch in Y-Richtung, auf die erste Seite des Dokuments input.pdf das Bild Grafik.jpg eingefügt. Das Bild wird auf die Maße der Seite skaliert. Das Ergebnis wird in output.pdf zurückgeliefert.

4) 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 inhalt.pdf output.pdf

Hier wird zunächst auf vorderster Ebene (Top) 18 cm von links und 28 cm von oben ein 1cm x 1cm großes weißes Rechteck eingefügt und dann in Schriftart Helvetica und Schriftgröße 10 kursiv auf jeder Seite des Dokuments input.pdf die aktuelle Seitennummer in Arabic an dieser Stelle eingefügt (1,2,3...). Das Ergebnis wird in output.pdf zurückgeliefert.

5) cibrsh.exe Overlay=“POS:Top|0;0;All;LINETO: 255.0.0;210,297;“ –fj inhalt.pdf output.pdf

Hier wird auf vorderster Ebene (Top) eine rote Linie vom linken oberen Rand (0,0) zum rechten unteren Rand (210,297) eingefügt. Das Ergebnis wird in output.pdf zurückgeliefert.

6) cibrsh.exe Overlay=“ POS:Top|0;150;All;BEZIERTO: 255.255.255;100,60,150,110,210,150“ –fj inhalt.pdf output.pdf

Hier wird auf vorderster Ebene (Top) eine rote Bezier-Kurve mit Anfangspunkt (0,150), Endpunkt (210,150) und den Stützpunkten (100,60) und (150,110) eingefügt. Das Ergebnis wird in output.pdf zurückgeliefert.

Barcode

(ab Release 1.4.84)

Die in der Property „Overlay“ spezifizierten Barcodes werden an gewünschter Stelle im Ergebnisdokument des Joins platziert.

Die Prioritäten sind hier genauso geregelt, wie im Abschnitt Briefpapier beschrieben.

Die Property „Overlay“ wird wie folgt belegt:

[POS:Ebene|X-Position;Y-Position;] Seitenangaben;BARCODE:Typ;Wert;Orientierung;Breite;Höhe;Prüfziffer;Codepage

QR [POS:Ebene|X-Position;Y-Position;] Seitenangaben;BARCODE:QR;Wert;Orientierung;Breite;Höhe;Größe;CodePage;KorrekturLevel

Bezeichnung	Wert	Wirkung
Ebene wie Text
X-Position wie Text
Y-Position wie Text
Seitenzahl(en) wie Text
Typ	Ein Barcodetyp aus der von CIB format unterstützten Menge von Typen: Code ITF Code 2/5 Industrie Code 2/5 Matrix Code 39 Code 39 erweitert Code 128 (A, B, C) EAN 8 EAN 13 EAN 128 DataMatrix PDF417 Code 93 Code 93 Extended OMR Strichcodes QR	Diese Barcodetyp wird verwendet
Wert	Zahlen	Der individuelle Wert, den der Barcode darstellen soll.
Orientierung	horizontalleft	vertikale Striche nebeneinander, erstes Zeichen links
	horizontalright	vertikale Striche nebeneinander, erstes Zeichen rechts
	verticalleft	horizontale Striche untereinander, erstes Zeichen oben
	verticalright	horizontale Striche übereinander, erstes Zeichen unten
Breite	Strichbreite in mm (x.xmm; oder x,xmm beides zulässig)	Setzt die Strichbreite des Barcodes
Höhe	Höhe der Barcode-Balken in mm (x.xmm; oder x,xmm beides zulässig)	Setzt die Höhe der Barcode-Balken
Prüfziffer / KorrekturLevel (ab Version 1.26.0)	default	Barcode wird mit Prüfziffer generiert
	nochecksum	Barcode wird ohne Prüfziffer generiert
	Die Prüfziffer gibt es bei 2D-Barcodes (QR) nicht. Default ist daher immer nochecksum. Hier kann aber das Korrekturlevel (ECL) angegeben werden. Das Level geht von 0 (geringe Korrektur) bis 3 (maximale Korrektur = default).
Codepage	Gibt Codepage für QR Barcode-Daten an. Default: Ansi; Mögliche Werte: Ascii Pca Ansi CodePageMac CodePagePc CodePagePdf CodePage932ShiftJIS CodePage949Hangul CodePage936GB2312 CodePage950ChineseBIG5 CodePage1255Hebrew CodePage1256Arabic CodePage1253Greek CodePage1254Turkish CodePage1258Vietnamese CodePage874Thai CodePage1250EastEurope CodePage1251Cyrillic CodePage1257Baltic CodePageUnicode CodePageIdentity CodePage1252Latin1 CodePageUtf8	Bemerkung: Wenn „CodePageUtf8“ benutzt wurde, wird fehlende BOM (Bytereihenfolge-Markierung) am Anfang der eingehenden Barcode-Daten hinzugefügt.
Größe (ab Version 1.26.0)	QR-Code: Die Größe wurde bisher nicht benutzt. Jetzt kann hier die Version angegeben werden.	Die Größe des QR-Codes wird durch die Version bestimmt. Beispiel: Version 13 impliziert eine Größe von 69x69

Für die Belegung der Parameter nach „Wert“ wird auf entsprechende Dokumentationen bezüglich der Barcode-Realisierung im CIB format verwiesen. Welche Parameter mit welchem Wert belegt werden müssen, hängt stark vom Barcode-Typ ab.

Releaseplan

Die Overlayfunktion wird in mehreren Stufen realisiert. Die Realisierung der Funktionalität hat nach folgendem Stufenplan zu erfolgen:

Angabe des Word-Seriendruck-Felds {PAGE} mit Default-Option Arabic, Möglichkeit, Schriftart, -größe, -farbe und die Position des Textes selbst festzulegen.
Logos ohne Rotation
beliebiger Text mit Rotation
Unterstützung von anderen Feldern (wie {NUMPAGES} oder {DATE} mit Optionen an beliebigen Stellen im Text
Unterstützung von Barcodes

Es muss geprüft werden, inwieweit die Ebenen-Funktion ausgenutzt oder unterstützt werden kann. Es ist zu beachten, dass diese nicht im PDF 1.3 enthalten ist und von älteren Viewern nicht unterstützt wird.

Ab Toolbox 1.2.56 wird Overlay von Text (inklusive Rotation), Grafik und Rechtecken unterstützt.