Die Bibliothek auf Ihrer eigenen Maschine

Worum es hier geht

Eine PDF-Datei sieht überall genau gleich aus. Sie öffnen sie auf Ihrem Computer, Ihr Nachbar auf einem Telefon, die Druckerei lässt sie über ihre Maschine laufen, und es ist auf den Millimeter dieselbe Seite. Deshalb reisen Rechnungen, Verträge und Gehaltsabrechnungen in dieser Form.

HQF Development stellt die Engine her, die diese Dateien schreibt. Kein Programm, das man öffnet und in dem man herumklickt: eine Engine, die die Person, die Ihre Software schreibt, in ihre eigene einbaut.

Was eine Bibliothek ist

In der Informatik ist eine Bibliothek eine Sammlung fertiger Teile. Denken Sie an einen Automotor. Ein Hersteller baut nicht für jedes Modell einen von Grund auf neu: Er nimmt einen vorhandenen Motor, setzt ihn in die Karosserie, die er entworfen hat, und verbindet das Pedal damit. Der Motor dreht die Räder; das Auto bleibt seines.

Eine Bibliothek ist diese Engine. Wer Ihre Rechnungssoftware schreibt, behält seine Software, seine Bildschirme, seine Gewohnheiten, seine Arbeitsweise. Er baut unsere Engine ein, sagt ihr: Hier sind die Rechnungspositionen, hier ist das Logo, hier ist die Summe, und die Engine gibt die PDF-Datei zurück.

Umgekehrt, und was sich ändert

Es gibt einen anderen Weg: die Informationen an einen Computer irgendwo im Internet senden, der das Dokument erzeugt und zurückschickt. Das ist, als brächte man seinen Brief zu einer Druckerei am anderen Ende der Stadt. Es funktioniert sehr gut, und das Team bietet auch das an. Aber man muss den Umschlag hinbringen, warten und ihn wieder abholen.

Mit der Bibliothek ist die Druckerei im Nebenzimmer. Drei Dinge ändern sich, und alle drei spürt man sofort.

• Es geht sofort. Die Rechnung wird auf Ihrer eigenen Maschine erzeugt, im Moment des Klicks, der sie verlangt hat. Nichts geht hinaus, nichts kommt zurück.
• Ihre Informationen bleiben bei Ihnen. Die Namen Ihrer Kunden, ihre Adressen, ihre Beträge bleiben von Anfang bis Ende auf Ihrer Maschine. Die Bibliothek arbeitet vollständig vor Ort, mit dem, was sie in ihrem eigenen Paket trägt. Ihre Daten verlassen nie die Maschine, die sie ausführt.
• Sie steht für sich. Ihre Software erzeugt ihre Dokumente auch dann, wenn die Verbindung unterbrochen ist, und an einem abgeschotteten Standort. Die einzige Maschine, die man im Auge behalten muss, ist Ihre eigene.

Was es erzeugt

Rechnungen, Auftragsbestätigungen, Lieferscheine, Gehaltsabrechnungen, Verträge, Kontoauszüge, Etikettenbogen, Kataloge, Urkunden, Bordkarten, ganze Bücher. Mit Tabellen, die von einer Seite zur nächsten weiterlaufen, Logos, Fotos, den QR-Codes, die ein Telefon zum Bezahlen liest, Feldern, die Menschen am Bildschirm ausfüllen, und einem Passwort, das die Datei verschließt, wenn Sie danach fragen.

Was Sie erhalten, und wie es zu Ihnen gelangt

Die zu installierende Datei liegt auf der Download-Seite dieser Website, offen für alle: Sie klicken darauf, und sie wird auf Ihrem Computer gespeichert, genau wie jede andere heruntergeladene Datei. Ohne Lizenzschlüssel funktioniert sie bereits und versieht jede erzeugte Seite mit einem Wasserzeichen.

Ihr Lizenzschlüssel ist eine Folge von Buchstaben und Ziffern, nur Ihnen gehörend, die Ihre Software einmal erhält und die der Engine sagt, dass sie eine bezahlte Kopie ist: Das Wasserzeichen verschwindet. Sie legen ein Konto auf dieser Website an und zahlen, und Schlüssel und Rechnung warten in diesem Konto auf Sie. Geben Sie die Datei und diese Zeichenkette der Person, die Ihre Software entwickelt, und sie hat alles.

Ist eine neuere Datei bereit, liegt sie auf derselben Downloadseite, und Sie holen sie, wann es Ihnen passt.

Was Sie kaufen, ist das Recht, die Engine zu nutzen, gebaut und lauffertig. Ihr Quellcode bleibt bei HQF Development, so wie ein Autohersteller den Motor verkauft und die Pläne behält, nach denen er gebaut wurde.

Für wen diese Seite ist

Geben Sie die Adresse dieser Seite an die Person weiter, die Ihre Software entwickelt: Weiter unten findet sie alles, was sie braucht, um sie zu beurteilen.

Die öffentliche Schnittstelle auf einen Blick

Version 1.364.0 der Engine stellt 49 öffentliche Module und 262 Namen auf der Wurzelebene des Rust-Crates bereit; die Python-Seite deklariert 434 Klassen, weil dort ein Namensraum enthält, was Rust in einem Modul pro Familie hält. 135 vollständige Beispiele werden mitgeliefert, jedes in zwei Zwillingsfassungen, eine in Rust und eine in Python. Bevor eine Änderung in die Bibliothek gelangt, wird jedes davon in beiden Sprachen ausgeführt und die beiden Dateien Byte für Byte verglichen, damit keines unbemerkt veraltet.

Das kürzeste nützliche Dokument

use hqf_pdf::content::Content;
use hqf_pdf::cos::Name;
use hqf_pdf::{Document, License, Page};

let mut c = Content::new();
c.set_fill_rgb(0.20, 0.40, 0.80)?;
c.rect(50.0, 700.0, 495.0, 90.0)?;
c.fill();

let mut page = Page::a4();
page.content = c.into_bytes();

let mut doc = Document::new();
doc.set_license(License::from_key(key)?);
doc.set_info(Name::new("Title"), "hqf-pdf sample invoice");
doc.add_page(page)?;

let bytes = doc.to_bytes()?;

import hqf_pdf

content = hqf_pdf.Content()
content.set_fill(hqf_pdf.Rgb(0.20, 0.40, 0.80))
content.rect(50.0, 700.0, 495.0, 90.0)
content.fill()

page = hqf_pdf.Page.a4()
page.set_content(content)

document = hqf_pdf.Document()
document.set_license(hqf_pdf.License.from_key(key))
document.set_info("Title", "hqf-pdf sample invoice")
document.add_page(page)

data = document.to_bytes()

Ein minimales PDF Das PDF öffnen

Text in einer eingebetteten Schrift

Nur die Glyphen, die das Dokument zeichnet, kommen in die Datei: Eine Seite mit einer Zeile trägt Schrift für eine Zeile, nicht die ganze Schrift. Gemessen wird über dasselbe Handle, das zeichnet; so bleibt Text in seinem Kasten.

let font = Font::parse(fs::read(&font_path)?)?;
let handle = doc.add_font(font);

let mut c = Content::new();
c.begin_text();
c.set_font(&handle, 14.0)?;
c.text_position(60.0, 760.0)?;
for line in &lines {
    c.show_glyphs(&handle.glyphs(line));
    c.text_position(0.0, -28.0)?;
}
c.end_text();

let width = handle.measure(lines.last().map_or("", String::as_str), 14.0);

font = hqf_pdf.Font.from_path(font_path)
handle = document.add_font(font)

content = hqf_pdf.Content()
content.begin_text()
content.set_font(handle, 14.0)
content.text_position(60.0, 760.0)
for line in lines:
    content.show_glyphs(handle.glyphs(line))
    content.text_position(0.0, -28.0)
content.end_text()

width = handle.measure(lines[-1], 14.0)

In die Datei eingebettete Schriften Das PDF öffnen

Ein Absatz, der sich selbst umbricht

let flow = TextFlow::new(&handle, 11.0).align(align).leading(15.0);
let lines = flow.break_lines(words.paragraph, box_width);

c.begin_text();
flow.draw(&mut c, &lines, x, top, box_width)?;
c.end_text();

flow = hqf_pdf.TextFlow(handle, 11.0, align=align, leading=15.0)
lines = flow.break_lines(words.paragraph, box_width)
flow.draw(content, lines, x, top, box_width)

Einen Absatz umbrechen und ausrichten Das PDF öffnen

Eine Tabelle, die Seite um Seite weiterläuft

Eine Zeilenhöhe wird nie angegeben: Sie wird an dem Text gemessen, den die Zeile trägt, sobald die Spaltenbreiten bekannt sind. So kann die Tabelle Zeile für Zeile entscheiden, ob die nächste noch passt. Das Einpassen zeichnet nichts: Es liefert die Geometrie zurück, sodass sich eine Tabelle messen lässt, bevor jemand festlegt, wohin sie kommt. Rufen Sie es einmal pro Seite auf, bis es meldet, dass es fertig ist, oder verlangen Sie den ganzen Lauf in einem Aufruf und erhalten Sie eine Platzierung pro Seite.

let columns = Columns::new(
    vec![
        ColumnWidth::Fraction(1.0),
        ColumnWidth::Points(46.0),
        ColumnWidth::Points(94.0),
        ColumnWidth::Points(94.0),
    ],
    TABLE_WIDTH,
)?;

let mut table = Table::new(columns);
table.header(1);
table
    .rule(Rule::Frame, Stroke::black(0.8))
    .rule(Rule::HorizontalOther, Stroke::new(0.25, Rgb::gray(0.75)));

let pad = Padding::symmetric(5.0, 4.0);
table.push(
    Row::new()
        .cell(Cell::new(text, 9.0, label).padding(pad))
        .cell(Cell::new(text, 9.0, value).padding(pad).align(Align::Right)),
);

let mut start = 0;
loop {
    let placed = table.fit(TableFrame::new(MARGIN, TOP, TOP - BOTTOM), start)?;

    let mut content = Content::new();
    placed.draw(&mut content)?;

    let mut page = Page::a4();
    page.content = content.into_bytes();
    doc.add_page(page)?;

    match placed.outcome() {
        FitProgress::Done => break,
        FitProgress::BoxFull { next_row } => start = next_row,
        FitProgress::RowTooTall { row } => {
            return Err(format!("row {row} is taller than a page").into());
        }
        outcome => return Err(format!("the table fitted to {outcome:?}").into()),
    }
}

columns = hqf_pdf.Columns(
    [
        hqf_pdf.ColumnWidth.fraction(1.0),
        hqf_pdf.ColumnWidth.points(46.0),
        hqf_pdf.ColumnWidth.points(94.0),
        hqf_pdf.ColumnWidth.points(94.0),
    ],
    TABLE_WIDTH,
)

table = hqf_pdf.Table(columns)
table.header(1)
table.rule(hqf_pdf.Rule.frame(), hqf_pdf.Stroke(0.8))
grey = hqf_pdf.Rgb.gray(0.75)
table.rule(hqf_pdf.Rule.horizontal_other(), hqf_pdf.Stroke(0.25, color=grey))

pad = hqf_pdf.Padding.symmetric(5.0, 4.0)
table.push(
    hqf_pdf.Row(
        cells=[
            hqf_pdf.Cell(font, 9.0, label, padding=pad),
            hqf_pdf.Cell(font, 9.0, value, padding=pad, align=hqf_pdf.Align.Right),
        ]
    )
)

start = 0
while True:
    placed = table.fit(MARGIN, TOP, TOP - BOTTOM, start)

    content = hqf_pdf.Content()
    placed.draw(content)

    page = hqf_pdf.Page.a4()
    page.set_content(content)
    document.add_page(page)

    if placed.done:
        break
    start = placed.next_row

Eine mehrseitige Rechnungstabelle Das PDF öffnen

Wie Ablehnungen zurückkommen

In Rust gibt alles, was ablehnen kann, ein Ergebnis mit dem eigenen Fehlertyp der Bibliothek zurück: ein nicht erschöpfendes Enum mit 186 Varianten, von denen jede genau benennt, was geschehen ist — eine fehlerhafte Schrift, ein fehlerhaftes Bild, keine solche Schrift, keine solche Seite, zwei gleich benannte Felder, etwas, das für den Druck fehlt, etwas, das für die Archivierung fehlt, etwas, das die Konformitätsstufe verbietet, eine Zeile, die höher ist als ihr Kasten, keine Lizenz, eine ungültige Lizenz, eine verschlüsselte Datei. Ein Kunde prüft den genauen Fall statt des Meldungstextes.

Daten von außen — ein PDF, eine Schrift, ein Bild, ein Profil —, die nicht standhalten, sind ein gewöhnliches Ergebnis, als solches zurückgegeben und nie ein Absturz. 21 Panics verbleiben auf Produktionspfaden. Jeder nennt die Invariante, die er einhält, und keiner ist von einem Wert aus erreichbar, den ein Kunde liefert.

In Python kommen dieselben Ablehnungen als Ausnahmen zurück, alle eigenen der Bibliothek unter einer einzigen Klasse, die ein Kunde als Ganzes abfangen kann. Die 2 Layoutfälle — eine Tabellenzeile, die höher ist als der ihr gegebene Kasten, und ein Stapelblock im selben Fall — teilen sich darunter eine eigene Klasse: Eine Umbruchschleife fängt sie über diese gemeinsame Klasse zusammen ab oder jeden für sich.

Neben Ablehnungen gibt es Hinweise. Das Schreiben der Bytes hat eine berichtende Form, die die Bytes und die Liste der Warnungen zurückgibt, die das Dokument über sich selbst hat; die Datei wird in jedem Fall geschrieben und ist gültig, und eine Warnung zeigt auf ein Dokument, das wahrscheinlich nicht das ist, was der Kunde meinte. Eine davon nennt eine Schrift, die entgegen der in der Schriftdatei selbst angegebenen Berechtigung eingebettet wurde: Die Lizenz, unter der die Schrift gekauft wurde, entscheidet die Sache, und der Hinweis legt die Frage dem Kunden vor, der sie entscheidet. Die Prüfung gegen eine Norm geht weiter: Sie liefert alles zurück, was bekanntermaßen zwischen dem Dokument und dieser Norm steht, ohne etwas zu schreiben oder zu ändern.

Was die aktuelle Version abdeckt

Version 1.364.0 der Engine: Schreiben und Lesen von PDF, alle drei Generationen von Schutz auf der Leseseite und AES-256-Verschlüsselung auf der Schreibseite, PDF/A-2, PDF/A-3 und PDF/A-4, PDF/X-4, PDF/UA-1 und PDF/UA-2, Factur-X, vollständiges Tagging, PAdES-Signatur mit vom Kunden gestelltem Signierer, linearisierte Ausgabe, Objektstreams und das Übernehmen von Seiten aus anderen Dateien.

Das Handbuch

Das vollständige Handbuch der Engine — jeder Aufruf, jede Einstellung, jede Falle — wird im direkten Gespräch mit dem Team übergeben.

Wirklich hilft der Teil, der Ihre Frage beantwortet, mit dem Beispiel, das zu Ihrem Fall passt. Der Weg ist also dieser. Sie registrieren sich auf dieser Website, schreiben uns, was Sie vorhaben — eine Rechnung mit ihrem XML, eine Tabelle mit zweitausend Zeilen, ein Bogen, der in Druck geht —, und das Team sendet Ihnen den Teil des Handbuchs, der genau das abdeckt, mit dem Code auf beiden Seiten, Rust und Python.

Sie sprechen mit den Menschen, die die Engine geschrieben haben, und die Antwort ist auf Ihr Projekt zugeschnitten. In der Zwischenzeit decken die 135 mit der Bibliothek gelieferten Beispiele das meiste ab, was sich von ihr verlangen lässt, und jedes läuft so, wie es ist.