README

DX Pdfium4D

Delphi Cross-Platform Wrapper for Google's PDFium

Features • Getting Started • Documentation • Examples • Contributing • License

Overview

DX Pdfium4D is a comprehensive Delphi wrapper for Google's PDFium library, providing object-oriented classes for PDF document handling in cross-platform Delphi applications.

The project includes DX PDF Viewer demo applications for both FireMonkey (FMX) and VCL, which serve as practical demonstrations of the wrapper's capabilities and showcase modern Delphi development practices.

Why DX Pdfium4D?

• ✅ Type-safe, object-oriented API - No more dealing with raw C pointers
• ✅ Automatic resource management - Destructors handle PDFium cleanup automatically
• ✅ Cross-platform - Windows, macOS, Android, iOS
• ✅ FMX and VCL support - Works with both FireMonkey and VCL frameworks
• ✅ Well-documented - Comprehensive documentation and examples
• ✅ Production-ready - Includes unit tests and demo applications
• ✅ MIT Licensed - Free for commercial and open-source projects

Table of Contents

• Overview
• Features
• Quick Start
• Documentation
• Examples
• Project Structure
• Architecture
• Testing
• Contributing
• License
• Acknowledgments

Features

DX Pdfium4D Wrapper

🔧 Object-Oriented API

• High-level Delphi classes wrapping PDFium C-API
• Automatic PDFium resource cleanup in destructors
• Type-safe, exception-based error handling

📄 PDF Document Support

• Load PDF documents from files or memory
• Extract metadata (title, author, subject, keywords)
• PDF/A compliance detection
• Page count and dimensions

🎨 Rendering

• High-quality bitmap rendering
• Configurable DPI support
• Platform-independent rendering
• Separate renderers for FMX and VCL

🌍 Cross-Platform

• Windows (Win32, Win64) - FMX and VCL
• macOS (Intel, Apple Silicon) - FMX
• Android - FMX
• iOS - FMX
• Linux (Linux64) - core binding only by default; optional FMX viewer via FMXLinux (see Building on Linux with FMXLinux)

DX PDF Viewer Applications

✨ Two Implementations

• FMX Viewer - Cross-platform (Windows, macOS, Android, iOS)
• VCL Viewer - Windows-only with native Windows controls

✨ Minimalistic Design

• Clean, distraction-free interface
• Focus on content, not chrome
• Modern Material Design-inspired UI (FMX)
• Native Windows look and feel (VCL)

🎯 User-Friendly

• Drag & Drop PDF files to open
• Click anywhere to browse for files
• Keyboard shortcuts (Ctrl+O to open, arrow keys to navigate)
• PDF/A detection and metadata display

⚡ Performance

• Background rendering for smooth UI
• Efficient memory management
• Fast page switching
• Proper aspect ratio preservation
• Centered display with visual feedback

Quick Start

Prerequisites

• Delphi 12 or 13 (tested with Delphi 12.3 Athens and Delphi 13 Florence)
• GitHub CLI (gh) - for automatic PDFium download

1. Clone and Setup

git clone --recurse-submodules https://github.com/omonien/DX.Pdfium4D.git
cd DX.Pdfium4D

Download the PDFium binary:

cd build
.\copy-pdfium-dll.ps1 -Platform Win64              # Win64 Debug (default)
.\copy-pdfium-dll.ps1 -Platform Win32              # Win32 Debug
.\copy-pdfium-dll.ps1 -Platform Win64 -Config Release  # Win64 Release

The script downloads the latest PDFium release from bblanchon/pdfium-binaries and caches it locally.

2. Build and Run

From Delphi IDE:

1. Open src/PdfViewer/DX.PdfViewer.dproj (FMX) or src/PdfViewerVCL/DX.PdfViewerVCL.dproj (VCL)
2. Press F9 to build and run

From command line (PowerShell):

cd build
.\build-tests.ps1 -Run                        # Build and run tests
.\build-release.ps1 -Version "v1.0.0"         # Build release (FMX + VCL, Win32 + Win64)

All build output goes to build/<Platform>/<Config>/ (e.g., build/Win64/Debug/).

3. Use in Your Own Project

uses
  DX.Pdf.API,          // Low-level PDFium C-API bindings
  DX.Pdf.Document,     // High-level document/page classes
  DX.Pdf.Viewer.FMX,   // (Optional) FMX visual component
  DX.Pdf.Viewer.VCL;   // (Optional) VCL visual component

Ensure pdfium.dll is in your output directory, then:

var
  LDocument: TPdfDocument;
  LPage: TPdfPage;
  LBitmap: TBitmap;
begin
  LDocument := TPdfDocument.Create('document.pdf');
  try
    LPage := LDocument.Pages[0];
    LBitmap := LPage.RenderToBitmap(96); // 96 DPI
    try
      // Use the bitmap
    finally
      LBitmap.Free;
    end;
  finally
    LDocument.Free;
  end;
end;

For detailed usage see 📖 Using the DX.Pdf Wrapper Classes

Building on Linux with FMXLinux

By default the Linux64 build includes only the core binding — the FMX viewer units (DX.Pdf.Viewer.FMX, DX.Pdf.Renderer.FMX) are excluded because the stock Delphi RTL does not ship FMX for Linux. FMXLinux (KSDev) is a third-party, commercial add-on, so this project does not assume it is installed.

If you do have FMXLinux licensed and installed, you can opt in:

1. Add the FMXLinux source path to Tools → Options → Library → Library Path (for Linux64) in the Delphi IDE.

2. Build with the -FmxLinux switch (run from the build/ directory, matching the Quick Start above):

   powershellCopy

   cd build
   .\build-tests.ps1 -Platform Linux64 -FmxLinux

   The switch passes /p:FmxLinux=true to MSBuild, which defines HAS_FMXLINUX for the test project and includes the FMX viewer.

In your own projects, mirror the same pattern: gate FMX-dependent units with {$IF not Defined(LINUX) or Defined(HAS_FMXLINUX)} and define HAS_FMXLINUX in your Linux64 build configuration.

See issue #9 for the full rationale and the long-term plan.

Documentation

For detailed documentation on using the DX Pdfium4D wrapper in your projects, see:

📖 Using the DX.Pdf Wrapper Classes

API Reference

The wrapper provides three main abstraction layers:

1. DX.Pdf.API - Low-level PDFium C-API bindings
2. DX.Pdf.Document - High-level object-oriented wrapper
3. DX.Pdf.Viewer.Core - Shared viewer logic (platform-independent)
4. DX.Pdf.Viewer.FMX - FMX visual component
5. DX.Pdf.Viewer.VCL - VCL visual component
6. DX.Pdf.Renderer.FMX - FMX-specific rendering
7. DX.Pdf.Renderer.VCL - VCL-specific rendering

Examples

DX PDF Viewer Demo Applications

The included DX PDF Viewer applications (FMX and VCL) demonstrate the wrapper's capabilities.

Features

Opening PDF Files

Method 1: Drag & Drop

• Drag a PDF file from Explorer and drop it onto the DX PDF Viewer window

Method 2: Click to Browse

• Click anywhere on the drop zone or status bar to open the file browser
• Select a PDF file and click "Open"

Method 3: Keyboard Shortcut

• Press Ctrl+O to open the file browser

Method 4: Command Line

• Pass the PDF file path as a command-line argument:
  bashCopy

  DX.PdfViewer.exe document.pdf

Navigation

Status Bar

The status bar displays:

• File name (clickable to open another file)
• PDF version (e.g., PDF 1.7)
• PDF/A compliance (if applicable)
• Current page / Total pages

Project Structure

DX.Pdfium4D/
????????? src/                          # Source code
???   ????????? DX.Pdf.API.pas           # Low-level PDFium C-API bindings
???   ????????? DX.Pdf.Document.pas      # High-level document/page classes
???   ????????? DX.Pdf.Viewer.Core.pas   # Shared viewer logic
???   ????????? DX.Pdf.Viewer.FMX.pas    # FMX visual component
???   ????????? DX.Pdf.Viewer.VCL.pas    # VCL visual component
???   ????????? DX.Pdf.Renderer.FMX.pas  # FMX rendering
???   ????????? DX.Pdf.Renderer.VCL.pas  # VCL rendering
???   ????????? PdfViewer/               # FMX demo application
???   ????????? PdfViewerVCL/            # VCL demo application
???   ????????? tests/                   # DUnitX unit tests
????????? build/                        # Build scripts and output
???   ????????? DelphiBuildDPROJ.ps1     # Universal Delphi build script
???   ????????? build-tests.ps1          # Build & run unit tests
???   ????????? build-release.ps1        # Build release packages
???   ????????? copy-pdfium-dll.ps1      # Download & copy PDFium DLL
???   ????????? <Platform>/<Config>/     # Build output (e.g., Win64/Debug/)
????????? assets/                       # Icons and logos
????????? samples/                      # Sample PDF files for testing
????????? lib/                          # Third-party libraries (Git submodules)
    ????????? pdfium-bin/              # PDFium binary config & cache
    ????????? pdfium-binaries/         # PDFium build scripts (submodule)
    ????????? DUnitX/                  # Unit testing framework (submodule)

Architecture

PDFium Wrapper Layers

1. Low-Level API (DX.Pdf.API.pas)

• Direct C-API bindings to PDFium
• Platform-independent function declarations
• Minimal abstraction

2. High-Level Classes (DX.Pdf.Document.pas)

• Object-oriented wrapper with automatic PDFium resource cleanup
• Metadata extraction (title, author, PDF/A compliance, etc.)
• Bitmap rendering with configurable DPI

3. Viewer Core (DX.Pdf.Viewer.Core.pas)

• Shared viewer logic for FMX and VCL
• Page navigation and state management
• Platform-independent functionality

4. Visual Components

• FMX Component (DX.Pdf.Viewer.FMX.pas) - Cross-platform PDF viewer
• VCL Component (DX.Pdf.Viewer.VCL.pas) - Windows-native PDF viewer
• Automatic page navigation
• Drag & Drop support
• Background rendering for smooth UI
• Proper aspect ratio preservation

Threading Model

• Main Thread: UI updates, user interaction
• Background Thread: PDF page rendering (using TTask)
• Synchronization: TThread.Synchronize for bitmap updates

Dependencies

PDFium Library

DX Pdfium4D uses Google's PDFium library for PDF rendering:

• Source: https://pdfium.googlesource.com/pdfium/
• Binaries: https://github.com/bblanchon/pdfium-binaries
• License: BSD-3-Clause (compatible with commercial use)

DUnitX

Unit testing framework:

• Source: https://github.com/VSoftTechnologies/DUnitX
• License: Apache 2.0

Sample PDF Files

The samples/ directory contains example PDF files for testing and demonstration purposes:

Simple PDF 2.0 file.pdf

A basic single-page PDF 2.0 file demonstrating:

• Simple text and path operators
• Commented content stream for educational purposes
• Example XMP metadata fields

pdf20-utf8-test.pdf

A more complex PDF 2.0 file featuring:

• UTF-8 encoded text strings (new in PDF 2.0)
• Outlines (bookmarks) with Unicode characters
• Optional Content layers with UTF-8 names
• AltText and Information dictionary with UTF-8 values
• Non-trivial Unicode characters for testing

Attribution: Sample PDF files are provided by the PDF Association under the Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) license.

Testing

DX Pdfium4D includes comprehensive unit tests for the PDFium wrapper classes.

Running Tests

Option 1: PowerShell (recommended)

cd build
.\build-tests.ps1 -Run                     # Win64 Debug (default)
.\build-tests.ps1 -Platform Win32 -Run     # Win32 Debug

Option 2: Delphi IDE

1. Open src\tests\DxPdfium4dTests.dproj
2. Press F9 to run tests
3. View results in the console

Network Tests (opt-in)

TestDownloadAndLoadCheatSheets downloads the PDF Association cheat sheets from pdfa.org. It is in the DUnitX category Network and is excluded from the default run. Enable it explicitly:

DxPdfium4dTests.exe --include:Network      # run only the network tests
DxPdfium4dTests.exe --run:DX.Pdf.CheatSheets.Tests   # select the test by name
$env:DX_PDFIUM4D_NETWORK_TESTS = '1'       # run all tests including network tests
DxPdfium4dTests.exe

Each download is retried up to 3 times. Without a network connection the test is skipped (it ends early with a SKIPPED message) instead of failing.

Test Coverage

• ✅ Library initialization
• ✅ PDF document loading (file and stream)
• ✅ Page count and dimensions
• ✅ Page indexed access and caching
• ✅ Metadata extraction
• ✅ PDF/A detection
• ✅ Error handling (non-existent files, out-of-range)
• ✅ Stream adapter callbacks
• ✅ PDF Association Cheat Sheets (download & load integration test, opt-in, see above)

Contributing

Contributions are welcome! We appreciate your help in making DX Pdfium4D better.

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Coding Standards

• Follow the Delphi Coding Style Guide included in this project
• Write unit tests for new features
• Update documentation as needed
• Ensure all tests pass before submitting PR

Reporting Issues

If you find a bug or have a feature request:

1. Check if the issue already exists in Issues
2. If not, create a new issue with:
   • Clear description of the problem/feature
   • Steps to reproduce (for bugs)
   • Expected vs actual behavior
   • Delphi version and platform
   • Sample code if applicable

Development Setup

1. Clone the repository with submodules: git clone --recurse-submodules ...
2. Download PDFium: cd build && .\copy-pdfium-dll.ps1
3. Build and run tests: .\build-tests.ps1 -Run

License

This project is licensed under the MIT License - see the LICENSE file for details.

What does this mean?

✅ Commercial use - Use in commercial projects ✅ Modification - Modify the source code ✅ Distribution - Distribute the software ✅ Private use - Use privately ⚠️ Liability - No warranty provided ⚠️ License and copyright notice - Must include license in distributions

Third-Party Licenses

• PDFium: BSD-3-Clause License (Google)
• DUnitX: Apache 2.0 License (VSoft Technologies)

Author & Support

Olaf Monien 🌐 Website: developer-experts.net 📧 Email: olaf@monien.net 💼 GitHub: @omonien

Support This Project

If you find DX Pdfium4D useful, please consider:

• ⭐ Starring this repository
• 🐛 Reporting bugs and suggesting features
• 🔀 Contributing code improvements
• 📢 Sharing with the Delphi community

Acknowledgments

Special thanks to:

• Google - For creating and maintaining the PDFium library
• Benoît Blanchon - For maintaining PDFium binaries
• PDF Association - For providing PDF 2.0 example files for testing
• VSoft Technologies - For the excellent DUnitX testing framework
• Embarcadero - For Delphi and the FireMonkey framework
• The Delphi Community - For continuous support and feedback

DX Pdfium4D

Delphi Cross-Platform Wrapper für Pdfium

Made with ❤️ by Olaf Monien

Back to top ⬆️