DispatchInputEvent

Forms, interaction, input

Description

Dispatches one GUI-framework-neutral pointer, wheel, keyboard or text-input event through the current TPDFlibFormSession

Pointer coordinates use the same rotated visual CropBox coordinate system as HitTest, with the origin at the visual top left

The dispatcher tracks entered and pressed Widgets so annotation /E, /X, /D and /U actions follow the PDF trigger ordering rules

A pointer-up action and default activation occur only when the primary button was pressed on a Widget and released inside the same uninterrupted entered area

fiekPointerCancel clears capture without dispatching /U and should be sent when the host loses pointer capture

Keyboard handling includes Tab and Shift+Tab focus traversal, grapheme-safe Backspace and Delete, directed selection movement, line-aware Up and Down movement, Home and End, text-field Enter and Escape, button activation and Control or Meta shortcuts for select all, undo and redo

fiekTextInput accepts complete WideString input so hosts can forward composed or supplementary Unicode text without reducing it to platform key codes

Vertical wheel deltas are normalized logical steps rather than operating-system constants; positive values select earlier choice items and negative values select later items

Declaration

function DispatchInputEvent(
  const InputEvent: TPDFlibFormInputEvent;
  out InputResult: TPDFlibFormInputResult): Integer;

Parameters

InputEvent	Event kind and the fields required by that kind
InputResult	Handling outcome plus the resulting focus, hover, press, value and selection state

Event fields

Pointer move, down, up and double-click	Set `Page`, `X` and `Y`; down and up also set `Button`
Pointer leave and cancel	No coordinates are required
Wheel	Set `Page`, `X`, `Y` and normalized `WheelDeltaX` or `WheelDeltaY`
Key down and key up	Set `Key` and any active `Modifiers`
Text input	Set `Text` to the composed text to insert or replace

Return value

Returns 1 when the event structure is valid and accepted for dispatch, including events that deliberately remain unhandled so the host can apply its own fallback

Returns 0 for an invalid event, invalid pointer coordinates, a detached session or recursive input dispatch

Use InputResult.Handled to decide whether host fallback is still required

Example

var
  InputEvent: TPDFlibFormInputEvent;
  InputResult: TPDFlibFormInputResult;
begin
  InputEvent.Kind := fiekPointerDown;
  InputEvent.Page := PageNumber;
  InputEvent.X := PageX;
  InputEvent.Y := PageY;
  InputEvent.Button := fibPrimary;
  InputEvent.Modifiers := [fimShift];
  Session.DispatchInputEvent(InputEvent, InputResult);

  InputEvent.Kind := fiekTextInput;
  InputEvent.Text := ComposedText;
  Session.DispatchInputEvent(InputEvent, InputResult);
end;