TextPage property

TextPage exposes the raw PDFium FPDF_TEXTPAGE handle associated with the currently loaded page. The handle is created lazily when the page becomes active and is kept alive for the lifetime of that page binding; it gives direct access to PDFium’s text-extraction API (FPDFText_*) for callers that need operations not surfaced by higher-level TPdf properties — for example glyph-level text runs, kerning data, custom search semantics or raw character-index to bounding-box mappings.

The handle is valid only while Active is True and a valid page is selected. Switching pages (assigning a new PageNumber or calling ReloadPage) destroys the previous handle and creates a new one, so do not store the handle across page changes. The component owns the handle and will release it during page teardown — do not call FPDFText_ClosePage on it yourself.

This is an advanced property. Most callers should prefer the high-level wrappers CharacterCount, Character[I], CharacterRectangle[I], Find / FindNext — these already manage the FPDF_TEXTPAGE lifecycle internally. Drop down to the raw handle only when you need PDFium APIs that PDFiumVCL has not surfaced yet.

• Returns nil when no page is active. Always check the handle before passing it to PDFium.
• The handle reflects the page’s content stream as parsed by PDFium — it does not include extraction state from FPDFText_FindStart; that search context is owned independently through the Find property.
• Calling raw PDFium APIs through this handle bypasses PDFiumVCL caching layers, so heavy use may regress performance compared with the high-level accessors.