TPDFlibFormSession

Formularze, interakcja, typy danych

Opis

Prowadzi testy trafień AcroForm, nawigację klawiaturą, fokus, wartość edycji i stan zaznaczenia tekstu bez zależności od frameworka GUI

Dołączona instancja TPDFlib pozostaje własnością wywołującego i musi przeżyć sesję

Przejścia fokusa eksponują akcje Widget /Fo i /Bl jako typowane zwrotne wywołania gospodarza przez OnAction

Prostokąty stron używają wizualnego CropBox po obrocie strony w bieżących jednostkach miary biblioteki, z początkiem w wizualnym lewym górnym rogu

Ukierunkowane zaznaczenia zatrzymują niezależne pozycje kotwicy i kursora i mogą być ustawiane albo odpytywane w jednostkach kodowych UTF-16, punktach kodowych Unicode albo klastrach rozszerzonych grafemów

Edycje dwukierunkowe zatrzymują logiczną kolejność wartości pola, rozwiązując per-liniowo wizualne sloty kursora z poziomów zagnieżdżenia, więc fizyczny ruch Lewo i Prawo podąża za tekstem mieszanym od lewej do prawej i od prawej do lewej

Zamiany zaznaczenia wyzwalają /K do gospodarza, eksponują wybrany i zastępczy tekst przez OnTextEdit, wymuszają /MaxLen na pełnych granicach grafemów i zwijają zaznaczenie po jednej zaakceptowanej edycji

Każda aktywna edycja trzyma ograniczoną historię delty, która przywraca wartość tymczasową, wartość wyświetlaną i ukierunkowane zaznaczenie bez ponownego wyzwalania akcji formularza albo zwrotnych wywołań edycji gospodarza

DispatchInputEvent przelicza neutralne platformowo rekordy wskaźnika, kółka, klawiszy nazwanych i tekstu złożonego na obuzdane akcje Widget, przejścia fokusa, edycję bezpieczną dla grafemów, aktywację przycisków i nawigację wyborem

Sesja zatrzymuje tożsamość Widgetów, na których weszło i które wciśnięto, więc /E, /X, /D i /U przestrzegają kolejności wyzwalaczy PDF nawet przez przechwycenie wskaźnika i anulowanie

Zatwierdzenia wyzwalają akcje /V i /F, wykonują swój obsługiwany ograniczony podzbiór JavaScript przed zmianą dokumentu i zatrzymują aktywną edycję, gdy walidacja, formatowanie albo zwrotne wywołanie gospodarza odrzuci transakcję

Zwalidowana surowa wartość jest zapisywana w polu, podczas gdy DisplayValue i wygenerowany wygląd Widgeta zatrzymują każdy wynik formatowania

Deklaracja

type
  TPDFlibFormFieldIndices = array of Integer;

  TPDFlibFormSelectionUnit = (fsuUTF16CodeUnit,
    fsuUnicodeCodePoint, fsuGraphemeCluster);

  TPDFlibFormTextDirection = (ftdAuto,
    ftdLeftToRight, ftdRightToLeft);
  TPDFlibFormCaretIndices = array of Integer;

  TPDFlibFormSelection = record
    IndexUnit: TPDFlibFormSelectionUnit;
    AnchorIndex: Integer;
    CaretIndex: Integer;
    StartIndex: Integer;
    SelectionLength: Integer;
    IsReversed: Boolean;
  end;

  TPDFlibFormSessionActionEvent = procedure(Sender: TObject;
    FieldIndex: Integer; const TriggerEvent: AnsiString;
    const ActionInfo: TPDFlibActionInfo; var Allow: Boolean) of object;
  TPDFlibFormSessionFocusEvent = procedure(Sender: TObject;
    OldFieldIndex, NewFieldIndex: Integer) of object;
  TPDFlibFormSessionValueEvent = procedure(Sender: TObject;
    FieldIndex: Integer; const OldValue, NewValue: WideString) of object;
  TPDFlibFormEditKind = (fekReplaceSelection,
    fekCutSelection, fekPasteText);
  TPDFlibFormSessionTextEditEvent = procedure(Sender: TObject;
    FieldIndex: Integer; EditKind: TPDFlibFormEditKind;
    SelectionStart, SelectionLength: Integer;
    const SelectedText: WideString; var ReplacementText: WideString;
    var Allow: Boolean) of object;

  TPDFlibFormInputEventKind = (fiekPointerMove,
    fiekPointerDown, fiekPointerUp, fiekPointerDoubleClick,
    fiekPointerLeave, fiekPointerCancel, fiekWheel,
    fiekKeyDown, fiekKeyUp, fiekTextInput);
  TPDFlibFormInputModifiers = set of TPDFlibFormInputModifier;

  TPDFlibFormInputEvent = record
    Kind: TPDFlibFormInputEventKind;
    Modifiers: TPDFlibFormInputModifiers;
    Button: TPDFlibFormInputButton;
    Key: TPDFlibFormInputKey;
    Page: Integer;
    X, Y: Double;
    WheelDeltaX, WheelDeltaY: Double;
    Text: WideString;
  end;

  TPDFlibFormSession = class
  public
    constructor Create(ALibrary: TPDFlib);
    procedure AttachLibrary(ALibrary: TPDFlib);
    procedure Reset;
    function FocusField(FieldIndex: Integer;
      CommitCurrent: Boolean = True): Integer;
    function GetFieldPageRect(FieldIndex: Integer; out Page: Integer;
      out Left, Top, Width, Height: Double): Integer;
    function HitTest(Page: Integer; X, Y: Double): Integer;
    function GetTabSequence(out FieldIndices: TPDFlibFormFieldIndices): Integer;
    function FocusAt(Page: Integer; X, Y: Double;
      CommitCurrent: Boolean = True): Integer;
    function FocusNext(Backwards: Boolean = False;
      WrapAround: Boolean = True; CommitCurrent: Boolean = True): Integer;
    function Blur(CommitCurrent: Boolean = True): Integer;
    function BeginEdit(FieldIndex: Integer): Integer;
    function SetEditValue(const NewValue: WideString): Integer;
    function SetSelection(StartIndex, SelectionLength: Integer): Integer;
    function SetSelectionRange(AnchorIndex, CaretIndex: Integer;
      IndexUnit: TPDFlibFormSelectionUnit): Integer;
    function GetSelectionRange(IndexUnit: TPDFlibFormSelectionUnit;
      out Selection: TPDFlibFormSelection): Integer;
    function SetTextDirection(
      Direction: TPDFlibFormTextDirection): Integer;
    function GetVisualCaretOrder(IndexUnit: TPDFlibFormSelectionUnit;
      out CaretIndices: TPDFlibFormCaretIndices): Integer;
    function MoveVisualCaret(ToRight: Boolean;
      ExtendSelection: Boolean = False): Integer;
    function GetSelectedText: WideString;
    function ReplaceSelection(const ReplacementText: WideString): Integer;
    function CutSelection(out CutText: WideString): Integer;
    function PasteText(const Text: WideString): Integer;
    function CanUndoEdit: Boolean;
    function CanRedoEdit: Boolean;
    function UndoEdit: Integer;
    function RedoEdit: Integer;
    procedure ClearEditHistory;
    function DispatchInputEvent(
      const InputEvent: TPDFlibFormInputEvent;
      out InputResult: TPDFlibFormInputResult): Integer;
    function CommitEdit: Integer;
    procedure CancelEdit;
    property TextDirection: TPDFlibFormTextDirection;
    property ResolvedTextDirection: TPDFlibFormTextDirection;
    property VisualCaretPosition: Integer;
    property MaxUndoSteps: Integer;
    property UndoEditCount: Integer;
    property RedoEditCount: Integer;
    property HoveredFieldIndex: Integer;
    property PressedFieldIndex: Integer;
  end;

Metody

Właściwości stanu

Zdarzenia

Wartość zwracana

Funkcje zmieniające stan zwracają 1 w razie powodzenia i 0, gdy żądanie jest nieprawidłowe, ponownie wchodzące, zawetowane albo nie może zostać zatwierdzone; HitTest zwraca indeks pola albo tymczasowego widżetu, a GetTabSequence liczbę wpisów

Jednostki wyboru

fsuUTF16CodeUnit zachowuje przestarzałą umowę indeksowania WideString o podstawie zero, w tym pozycje wewnątrz pary surrogatów, gdy są jawnie żądane

fsuUnicodeCodePoint liczy ważną parę surrogatów jako jeden uzupełniający punkt kodowy i traktuje niesparowany surrogat jako jeden samodzielny punkt kodowy

fsuGraphemeCluster liczy kompletne klastry rozszerzonych grafemów, więc sekwencje łączące i połączone emoji pozostają niepodzielne

Tabele granic Unicode są podręczne dla bieżącej wartości edycji i unieważniane przy zmianie tej wartości

Nawigacja dwukierunkowa

ftdAuto używa pierwszego mocnego znaku i domyślnie przyjmuje od lewej do prawej, gdy edycja nie ma mocnego znaku kierunkowego

Wizualna kolejność odcinków jest rozwiązywana niezależnie dla każdej linii i nie zmienia logicznej wartości pola UTF-16, ciągu PDF ani wyrównania tekstu

Indeks logiczny może zajmować dwa różne wizualne sloty na granicy mieszanych kierunków, więc VisualCaretPosition rozróżnia powtarzany ruch przez tę granicę

Przykład

var
  Session: TPDFlibFormSession;
  Selection: TPDFlibFormSelection;
begin
  Session := TPDFlibFormSession.Create(PDF);
  try
    if Session.FocusAt(PageNumber, MouseX, MouseY) = 1 then
      Session.FocusNext(False, True);
    if Session.BeginEdit(Session.FocusedFieldIndex) = 1 then
    begin
      Session.SetEditValue('A' + WideChar($D83D) + WideChar($DE00) + 'B');
      Session.SetSelectionRange(1, 2, fsuUnicodeCodePoint);
      Session.GetSelectionRange(fsuUTF16CodeUnit, Selection);
      Session.SetTextDirection(ftdAuto);
      Session.MoveVisualCaret(True, True);
      Session.PasteText('replacement');
      if Session.CanUndoEdit then
        Session.UndoEdit;
      if Session.CanRedoEdit then
        Session.RedoEdit;
      Session.CommitEdit;
    end;
  finally
    Session.Free;
  end;
end;

Zobacz również

SetTextDirection, GetVisualCaretOrder, MoveVisualCaret, TPDFlibFormTextDirection, DispatchInputEvent, TPDFlibFormInputEvent, TPDFlibFormInputResult, UndoEdit, RedoEdit, ClearEditHistory, ReplaceSelection, CutSelection, PasteText, TPDFlibFormEditKind, SetSelectionRange, GetSelectionRange, ExecuteFormFieldScript, TPDFlibActionInfo