FmxPdfTools documentation

This guide covers the public API of FmxPdfTools. Since you receive the full Delphi source code, every class and method below can also be read and adapted directly in the units you install.

Overview

FmxPdfTools is a native FireMonkey reporting and PDF engine for Delphi. One report definition (a .frp file) drives every platform: a true vector PDF on Windows, macOS, Linux and Android, an on-screen paged preview, and direct printing on desktop.

• Native & dependency-free — no GhostScript, Acrobat, PDF printer driver or external DLLs. Everything compiles into your executable.
• Vector output — text, lines, tables, images, barcodes and QR codes are drawn as real vector content, not bitmaps.
• One codebase — the same .frp renders on desktop and mobile.
• Visual designer included — ship it to your end-users so they can edit reports without code.

Installation

Install the package into the IDE with the included installer (or open and build the runtime/design-time packages manually). After installation a new FmxPdfTools tab appears in the Tool Palette with the three components.

1. Run the installer, or open the design-time package in the IDE and choose Install.
2. Add the source folder to your project (or IDE) library path so the units resolve for every target platform.
3. Drop a TReportEngine on your form — you are ready to render.

The three components

Installing the package adds three components to the FmxPdfTools palette tab:

Quick start

Set your variables and data sources, then render. On Windows this is all you need:

ReportEngine1.SetVariable('Company', 'Acme Trading Co.');
ReportEngine1.SetDataSource('customers', QryCustomers);

ReportEngine1.Preview('customers.frp');                      // paged, zoomable
ReportEngine1.ExportPDF('customers.frp', 'cust.pdf');        // vector PDF
ReportEngine1.PrintReport('customers.frp', 'HP LaserJet 1020');

Binding data

The engine renders against named data sources. There are two ways to supply them.

At runtime — SetDataSource

Bind any TDataSet descendant (such as a TFDQuery) under a name. That name is what you reference from the report's bands and fields.

ReportEngine1.SetDataSource('customers', QryCustomers);
ReportEngine1.SetDataSource('orders',    QryOrders);

At design time — TRptDataSet

Drop a TRptDataSet, point its data set at your query and name it. The engine auto-discovers it, so the designer's Data Tree shows the real fields and you can drag them straight onto a band — no code required to make the fields visible while designing.

Variables

Use variables for values that are not columns — a company name, a report title, the current user, a date range. Set them before rendering and reference them in the report as [Variable].

ReportEngine1.SetVariable('Company',  'Acme Trading Co.');
ReportEngine1.SetVariable('PrintedBy', CurrentUser);
ReportEngine1.SetVariable('AsOf',      DateToStr(Date));

Rendering & output

The same report can be sent to several outputs. Pick the method that matches your target:

// Vector PDF to a file
ReportEngine1.ExportPDF('invoice.frp', 'invoice.pdf');

// Paged on-screen preview (desktop)
ReportEngine1.Preview('invoice.frp');

// Direct printing - explicit printer, or default when omitted
ReportEngine1.PrintReport('invoice.frp', 'HP LaserJet 1020');
ReportEngine1.PrintReport('invoice.frp');                    // default printer

Bundling reports

Merge several .frp reports into a single PDF document — for example a cover page, a summary and a detail section — by passing an array of report names.

// Cover + summary + detail merged into one document
ReportEngine1.ExportPDF(
  TArray<string>.Create('cover.frp', 'summary.frp', 'detail.frp'),
  'quarterly_pack.pdf');

Use ShowReports to do the same and open the combined PDF through the OS.

Android notes

On Android, reports are produced as PDF (then shared, opened or printed through the OS) using the native JPdfDocument back-end. Two extra steps apply on mobile:

1. Drop a TPDFDrawing on the form and assign it to the engine.
2. Write to a writable location such as the documents path.

ReportEngine1.PDFDrawing := PDFDrawing1;        // Android back-end
ReportEngine1.SetDataSource('customers', FDQuery1);
ReportEngine1.ShowReport('customers.frp',
  TPath.Combine(TPath.GetDocumentsPath, 'customers.pdf'));

Visual designer

A complete WYSIWYG report designer ships with the component and can be distributed to your end-users. Open it from your app at runtime:

ReportEngine1.OpenDesigner('report.frp', Self);

Passing your form (Self) lets the engine publish your TRptDataSet fields straight into the Data Tree. Designing a report takes five steps:

1. Open the designer with OpenDesigner.
2. Set up the page & bands — page size, margins, grid, then add the bands you need.
3. Drop elements & bind fields — drag labels, tables, images, barcodes, QR codes and RTF memos from the palette; drag a field from the Data Tree, or type [Field].
4. Add expressions & groups — aggregates, a GroupCondition and group totals.
5. Preview, save & render — check it live, save the .frp, then render from your app.

Bands

Reports are built from bands that control where and how often content repeats:

• Title — once, at the very start.
• Page Header / Page Footer — on every page.
• Master / Detail / Sub-detail — repeat per record of their data source.
• Group Header / Group Footer — wrap each group; ideal for subtotals.
• Summary — once, at the end, for grand totals.

Expressions & groups

Bind a field by typing [Field] on a band, or drag it from the Data Tree. Combine fields and functions inside brackets to build expressions and aggregates.

To group records, set a GroupCondition (for example by country or by customer), then place your group total expressions in the Group Footer band.

Report files (.frp)

A report definition is stored as a .frp file in human-readable JSON. That means reports are easy to diff and version-control: drop them next to your code, review changes in a pull request, and deploy them with your app. Load any .frp by passing its path to ExportPDF, Preview, PrintReport, ShowReport or OpenDesigner.

Platform capability matrix

The same .frp drives every column:

Support

Questions about the API, a report design or deployment? We are glad to help — you also have the full source code to dig into.

Email info@fmxreports.com and we will get back to you, usually within one business day.