FormHandle property

FormHandle exposes the raw PDFium FPDF_FORMHANDLE created via FPDFDOC_InitFormFillEnvironment for the currently loaded document. This handle is the gateway to PDFium’s interactive-form layer: it is the parameter every FORM_* and FPDF_FFL* function expects, governing form field rendering, mouse / keyboard event delivery, focus tracking, and JavaScript / XFA callbacks (PDFium fpdf_formfill.h).

The handle is created when Active becomes True and is destroyed when Active returns to False or the component is freed. Treat it as opaque and short-lived — do not store the value past a single load/unload cycle, and never call FPDFDOC_ExitFormFillEnvironment on it yourself; the component owns its lifetime.

FormHandle is an advanced property useful for routing low-level form events (custom mouse / keyboard delivery, programmatic field focus, scripted appearance regeneration, XFA refresh) when the high-level FormField / FormFieldAt properties are not granular enough. For form rendering the VCL TPdfView already wires this handle into its paint loop; manual use is only necessary when bypassing the supplied viewer or implementing an alternate event pipeline.

• Returns nil when no document is loaded. Always check before invoking PDFium form-fill APIs.
• PDFium form-fill state is not threadsafe — use the handle only from the thread that loaded the document.
• When PDFium is built without the v8 JavaScript engine, FormHandle still works for static field rendering and basic interaction but document-level JavaScript actions are inert.