TPDFlibFormSession

Formularer, interaktion, datatyper

Beskrivelse

Vedligeholder AcroForm-hit-test, tastaturnavigation, fokus, redigeringsværdi og tekstmarkeringstilstand uden at være afhængig af en GUI-ramme Den tilknyttede

TPDFlib

/Fo/BlOnAction

/KOnTextEdit/MaxLen

DispatchInputEvent

/E-instans forbliver kalder-ejet og skal overleve sessionen Fokusovergange eksponerer Widget /X- og /D-handlinger som typede værts-callbacks gennem /U Siderectangler bruger den visuelle CropBox efter siderotation i bibliotekets aktuelle måleenheder, med udgangspunktet visuelt øverst til venstre Rettede markeringer bevarer uafhængige anker- og tekstmarkørpositioner og kan sættes eller forespørges i UTF-16-kodeenheder, Unicode-kodepunkter eller udvidede grafemklynger Tvejsredigeringer bevarer den logiske feltværdiorden, mens de opløser visuelle tekstmarkørspladser pr. linje ud fra indlejringsniveauer, så fysisk Venstre- og Højre-bevægelse følger blandede venstre-mod-højre- og højre-mod-venstre-tekster Markeringserstatninger udsender

/V til værten, eksponerer den valgte tekst og erstatningsteksten gennem /F, håndhæver

DisplayValue ved komplette grafemgrænser og sammentrækker markeringen efter én accepteret redigering Hver aktiv redigering gemmer en afgrænset deltahistorik, der gendanner den midlertidige værdi, visningsværdi og rettede markering uden at udsende formularhandlinger eller værts-redigeringscallbacks igen

Deklaration

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;

Metoder

Create	Opretter en session tilknyttet en kalder-ejet biblioteksinstans
AttachLibrary	Nulstiller al midlertidig tilstand og tilknytter en anden kalder-ejet biblioteksinstans eller `nil`
Reset	Rydder fokus-, redigerings- og markeringstilstand uden at ændre feltværdier eller udsende handlinger
FocusField	Committer eller annullerer den aktuelle redigering, udsender `/Bl` for den forrige Widget og udsender derefter `/Fo` for den anmodede synlige Widget
GetFieldPageRect	Returnerer et synligt Widget-rektangel i roterede visuelle CropBox-koordinater uden at ændre den valgte side
HitTest	Returnerer den øverst synlige Widget ved et visuelt siddepunkt, idet senere poster i sidens `/Annots`-array behandles som det forreste træf
GetTabSequence	Returnerer synlige Widgets på tværs af sider i siderækkefølge og anvender `/Tabs /R`-, `/C`-, `/S`-, PDF 2.0 `/A`- og `/W`-semantik, siderotation og ViewerPreferences `/Direction`; en manglende eller ugyldig `/Tabs`-værdi bruger annoteringsarray-orden
FocusAt	Udfører hit-test af et visuelt siddepunkt og fokuserer den returnerede Widget gennem det normale commit-, blur- og fokushandlingsforløb
FocusNext	Flytter frem eller tilbage gennem den beregnede tabulatorsekvens med valgfri wraparound og de normale fokusovergangsregler
Blur	Committer eller annullerer den aktuelle redigering og udsender `/Bl`, før fokussen ryddes
BeginEdit	Fokuserer et redigerbart tekst- eller valgfelt og tager et snapshot af dets oprindelige værdi
SetEditValue	Opdaterer den midlertidige værdi og håndhæver et tekstfelts konfigurerede maksimale længde uden at opdele en udvidet grafemklynge
SetSelection	Afgrænser og gemmer et nulbaseret UTF-16-markeringsinterval inden for den midlertidige værdi
SetSelectionRange	Afgrænser rettede anker- og tekstmarkørpositioner i den anmodede indeksenhed, konverterer dem til det interne UTF-16-interval og opdeler aldrig et kodepunkt eller en grafemklynge, når en af Unicode-enhederne bruges
GetSelectionRange	Returnerer anker, tekstmarkør, normaliseret start og længde i den anmodede indeksenhed sammen med den oprindelige retning
SetTextDirection	Vælger automatisk, eksplicit venstre-mod-højre eller eksplicit højre-mod-venstre paragrafretning og ugyldiggør den cachede visuelle tekstmarkørorden
GetVisualCaretOrder	Returnerer grafemsikre logiske tekstmarkørindekser i fysisk venstre-mod-højre-orden, herunder adskilte opdelte pladser ved grænser med blandet retning
MoveVisualCaret	Flytter eller udvider den rettede markering med én fysisk visuel plads og sammentrækker eksisterende markeringer mod den anmodede fysiske kant
GetSelectedText	Returnerer den aktuelt valgte UTF-16-tekst eller en tom streng
ReplaceSelection	Erstatter den normaliserede markering gennem én veto-bar `/K`- og `OnTextEdit`-transaktion og sammentrækker derefter tekstmarkøren efter den accepterede erstatning
CutSelection	Returnerer og fjerner den valgte tekst gennem det samme atomære erstatningsforløb
PasteText	Erstatter den aktuelle markering med kalderlevert udklipsholderstekst uden at indføre en platformsafhængighed af udklipsholderen
CanUndoEdit	Rapporterer, om den aktive redigering har en historikpost, der kan vendes
CanRedoEdit	Rapporterer, om den aktive redigering har en vendt historikpost, der kan afspilles igen
UndoEdit	Vender den seneste bevarede redigering og gendanner dens forrige rettede markering
RedoEdit	Afspiller den næste bevarede redigering igen og gendanner dens resulterende rettede markering
ClearEditHistory	Kasserer den aktive redigerings fortryd- og gendanhistorik uden at ændre dens aktuelle værdi eller markering
DispatchInputEvent	Udsender én platformneutral peger-, hjul-, tast- eller sammensat tekst-hændelse og returnerer den resulterende fokus-, hover-, tryk-, værdi- og markeringstilstand
CommitEdit	Validerer og formaterer en kandidat, før dens rå værdi gemmes, opdaterer det formatere udseende og udløser derefter `OnValueChanged`
CancelEdit	Kasserer den midlertidige værdi og markering uden at ændre feltet

Tilstandsegenskaber

LibraryInstance	Aktuel ikke-ejet `TPDFlib`-instans
FocusedFieldIndex	Fokuseret felt eller midlertidigt Widget-indeks, eller nul, når ingen Widget har fokus
EditingFieldIndex	Basis-tekst- eller valgfelt under redigering, eller nul, når ingen redigering er aktiv
OriginalValue	Feltværdi indfanget af `BeginEdit`
EditValue	Aktuel midlertidig værdi
DisplayValue	Aktuel redigeringsværdi eller den formaterede visningsværdi, som det seneste succesfulde commit producerede
SelectionStart	Nulbaseret UTF-16-startindeks
SelectionLength	UTF-16-markeringslængde
SelectionAnchor	Nulbaseret UTF-16-ankerposition, der forbliver fast, mens tekstmarkøren udvider en rettet markering
SelectionCaret	Nulbaseret UTF-16 bevægelig kant af den rettede markering
TextDirection	Konfigureret retning, som standard `ftdAuto` og bevaret på tværs af redigeringer i sessionen
ResolvedTextDirection	Eksplicit retning eller den automatiske retning valgt ud fra den aktive redigeringsværdis første stærke tegn
VisualCaretPosition	Aktuel plads i den cachede fysiske tekstmarkørorden, eller `-1`, når ingen visuel bevægelse har valgt en plads
MaxUndoSteps	Maksimalt antal bevarede redigeringshistorikposter fra 0 til 10000; standardværdien er 1000, og nul deaktiverer optagelse
UndoEditCount	Antal bevarede poster, der i øjeblikket er tilgængelige for `UndoEdit`
RedoEditCount	Antal bevarede poster, der i øjeblikket er tilgængelige for `RedoEdit`
Modified	`True`, når `EditValue` afviger fra `OriginalValue`
HoveredFieldIndex	Widget med en aktuelt aktiv pointer-enter-tilstand, eller nul
PressedFieldIndex	Widget, der bevarer primær peger-fangst, indtil tilsvarende op eller peger-annullering, eller nul

Hændelser

OnAction	Modtager en typet `TPDFlibActionInfo` for tilgængelige fokus-, blur-, tastetryk-, validerings- og formateringshandlinger; sæt `Allow` til `False` for at nedlægge veto mod den afventende operation
OnFocusChanged	Rapporterer hver fuldførte fokusovergang, herunder overgange til nul, efter at en ny fokushandling er blevet mødt med veto
OnValueChanged	Rapporterer en succesfuldt committet værdiændring, efter at feltet og dets ændrede udseender er blevet opdateret
OnTextEdit	Modtager redigeringsarten, UTF-16-markeringen, den valgte tekst og den ændrelige erstatning, før den midlertidige værdi ændres; sæt `Allow` til `False` for en atomær afvisning

Returværdi

Tilstandsændrende funktioner returnerer 1 ved succes og 0, når anmodningen er ugyldig, reentrant, mødt med veto eller ikke kan committes; HitTest returnerer et felt- eller midlertidigt Widget-indeks, og GetTabSequence returnerer antallet af poster

Markeringsenheder

fsuUTF16CodeUnit bevarer den ældre nulbaserede WideString-indekskontrakt, herunder positioner inde i et surrogatepar, når det eksplicit anmodes

fsuUnicodeCodePoint tæller et gyldigt surrogatepar som ét supplerende kodepunkt og behandler en uparret surrogate som ét selvstændigt kodepunkt

fsuGraphemeCluster tæller komplette udvidede grafemklynger, så kombinerende sekvenser og sammensatte emoji forbliver udelelige Unicode-grænsetabeller caches for den aktuelle redigeringsværdi og ugyldiggøres, når den værdi ændres

Tovejsnavigation

ftdAuto bruger det første stærke tegn og falder tilbage til venstre-mod-højre, når redigeringen ikke har noget stærkt retningsbestemt tegn Den visuelle run-orden opløses uafhængigt for hver linje og ændrer ikke den logiske UTF-16-feltværdi, PDF-strengen eller tekstjusteringen Et logisk indeks kan optage to forskellige visuelle pladser ved en grænse med blandet retning, så

VisualCaretPosition entydiggør gentagen bevægelse gennem den grænse

Eksempel

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;

Se også

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