Un'annotazione di evidenziazione appena restituita da FPDFPage_CreateAnnot riporta FPDFAnnot_CountAttachmentPoints = 0, e FPDFAnnot_SetAttachmentPoints(Annot, 0, Quad) su di essa restituisce 0 qualunque siano le coordinate passate. Il problema non sono le coordinate. Indice 0 significa "sostituisci il quad esistente numero 0", un'annotazione nuova non ha alcun quad, e la chiamata che crea uno slot è FPDFAnnot_AppendAttachmentPoints
Sta tutto in un paragrafo, eppure è facile perderci ore, perché la reazione naturale a un false è diffidare della geometria. Si traspongono gli angoli, si inverte l'asse Y, si converte in spazio dispositivo e ritorno. Niente di tutto questo cambia il risultato. Qui sotto vediamo cosa devono contenere i quad secondo ISO 32000-1, come scriverli tramite l'API del componente e tramite le funzioni C grezze, le selezioni su più righe e una trappola di indicizzazione che cambia tra Delphi, Free Pascal e C++Builder. È il complemento lato creazione dell'articolo sulla lettura e revisione delle annotazioni esistenti, che percorre le stesse strutture nella direzione opposta
Cosa significano i QuadPoints in ISO 32000-1 §12.5.6.10
QuadPoints è una voce obbligatoria sui quattro sottotipi di text markup, Highlight, Underline, Squiggly e StrikeOut: un array di 8×n numeri che descrive n quadrilateri nello spazio utente predefinito, dove ogni quadrilatero racchiude una parola o un gruppo di parole contigue nel testo sotto l'annotazione. L'annotazione porta comunque un Rect, che serve a ogni annotazione, ma per i sottotipi di markup sono i quad a dire quali glifi sono marcati e Rect si limita a delimitarli. Si usano quadrilateri e non rettangoli perché il testo sulla pagina può essere ruotato o inclinato, quindi ogni angolo viene memorizzato come punto indipendente: x1 y1 x2 y2 x3 y3 x4 y4
L'ordine degli angoli è il punto in cui il testo della specifica e i file in circolazione prendono strade diverse. Il §12.5.6.10 dice che i quattro vertici vanno dati in senso antiorario, e aggiunge che il testo è orientato rispetto al lato che va da (x1, y1) a (x2, y2). Acrobat, e la lunga serie di strumenti costruiti per leggere ciò che Acrobat scrive, usano invece uno schema a Z: punto 1 in alto a sinistra, punto 2 in alto a destra, punto 3 in basso a sinistra, punto 4 in basso a destra. Questa disposizione rispetta comunque la frase sull'orientamento, visto che il lato 1–2 corre lungo la parte superiore del testo, ma non è un giro antiorario attorno alla figura. Scrivi l'ordine a Z. Una lista letteralmente antioraria (alto-sinistra, basso-sinistra, basso-destra, alto-destra) è difendibile sulla carta, ma un reader che percorre i punti a Z ottiene alto-sinistra, basso-sinistra, alto-destra, basso-destra, e quei lati si incrociano a farfalla
Tutte le coordinate sono coordinate di pagina in punti, con origine in basso a sinistra della pagina e Y che cresce verso l'alto. Una riga di testo vicino al bordo superiore di una pagina A4 ha quindi valori Y attorno a 700-800, e il suo lato superiore ha la Y maggiore. La specifica dà inoltre la precedenza all'appearance stream (AP) rispetto ai QuadPoints quando sono presenti entrambi, quindi i quad contano soprattutto per i viewer che generano il markup da sé
Perché FPDFAnnot_SetAttachmentPoints restituisce false?
FPDFAnnot_SetAttachmentPoints restituisce false su un'annotazione nuova perché sostituisce soltanto un quad già esistente. L'header di PDFium enuncia il contratto senza giri di parole: il quad_index "needs to be within the result of FPDFAnnot_CountAttachmentPoints()". Ogni annotazione creata da FPDFPage_CreateAnnot parte con conteggio zero, quindi non esiste alcun indice 0 da sostituire. FPDFAnnot_AppendAttachmentPoints aggiunge uno slot e incrementa il conteggio di uno; da quel momento l'indice 0 esiste e Set lo accetta. Entrambe le funzioni sono marcate come sperimentali negli header di PDFium, ed entrambe allargano anche il bounding box di un appearance stream esistente quando il nuovo quad si estende oltre il precedente
Il componente PDFium espone tutti gli entry point FPDFAnnot_* in PDFium.pas, mentre il record FS_QUADPOINTSF e l'alias size_t stanno in FPdfView.pas. Se gestisci tu stesso un handle di annotazione, decidi in base al conteggio prima di ogni scrittura:
uses
SysUtils, PDFium, FPdfView;
// Scrive Quad alla posizione QuadIndex sull'annotazione AnnotIndex della pagina attiva:
// sostituisce lo slot se esiste, altrimenti ne accoda uno nuovo
procedure WriteQuad(Pdf: TPdf; AnnotIndex: Integer; QuadIndex: size_t;
var Quad: FS_QUADPOINTSF);
var
Annot: FPDF_ANNOTATION;
Count: size_t;
Ok: Boolean;
begin
Annot := FPDFPage_GetAnnot(Pdf.Page, AnnotIndex);
if Annot = nil then
raise Exception.CreateFmt('No annotation at index %d', [AnnotIndex]);
try
Count := FPDFAnnot_CountAttachmentPoints(Annot);
if QuadIndex < Count then
Ok := FPDFAnnot_SetAttachmentPoints(Annot, QuadIndex, Quad) <> 0
else
Ok := FPDFAnnot_AppendAttachmentPoints(Annot, Quad) <> 0;
if not Ok then
raise Exception.Create('PDFium rejected the quad');
finally
FPDFPage_CloseAnnot(Annot);
end;
end;
Una seconda trappola si annida nella stessa famiglia di funzioni. FPDFAnnot_CountAttachmentPoints restituisce size_t, che è senza segno, quindi il solito for I := 0 to Count - 1 su un'annotazione senza quad calcola 0 − 1 in aritmetica unsigned e va in wrap al valore massimo possibile. Verifica Count > 0 prima di entrare in qualsiasi ciclo sui quad, oppure fai prima un cast a un tipo con segno. Il markup prodotto da altri strumenti arriva quasi sempre con almeno un quad. Un'annotazione appena creata arriva con zero
Creare un'evidenziazione con TPdf.CreateAnnotation
Con l'API del componente non devi mai scegliere tra Append e Set. TPdf.CreateAnnotation e TPdf.SetAnnotation controllano entrambe quanti quad l'annotazione contiene già, sostituiscono gli slot esistenti e accodano il resto, così il percorso di creazione accoda e quello di aggiornamento sostituisce. Quello che fornisci tu è un record TPdfAnnotation con Subtype, colore, il quad e un Rectangle
Due dettagli del record contano qui. Inizializza il record con Default(TPdfAnnotation). Il record contiene stringhe e array dinamici, e un FillChar su un record che già contiene una stringa manda quella stringa in leak, quindi Default è l'abitudine più sicura per ogni record che riutilizzi. E compila sempre Rectangle: il componente lo scrive come Rect dell'annotazione a ogni creazione e aggiornamento, quindi un record azzerato produce un Rect di [0 0 0 0] anche quando i quad sono corretti. CreateAnnotation lavora sulla pagina attiva, che AddPage imposta per una pagina nuova e PageNumber per un documento esistente, e solleva 'Unsupported annotation subtype' quando PDFium non riesce a creare il sottotipo richiesto
var
Pdf: TPdf;
A: TPdfAnnotation;
begin
Pdf := TPdf.Create(nil);
try
Pdf.CreateDocument;
Pdf.AddPage(0, 595, 842); // A4, diventa la pagina attiva
A := Default(TPdfAnnotation);
A.Subtype := anHighlight;
A.HasColor := True;
A.Color := clYellow;
A.ColorAlpha := $80; // l'alfa viaggia insieme al colore
A.HasAttachmentPoints := True;
A.AttachmentPoints[1].X := 50; A.AttachmentPoints[1].Y := 700; // alto-sinistra
A.AttachmentPoints[2].X := 250; A.AttachmentPoints[2].Y := 700; // alto-destra
A.AttachmentPoints[3].X := 50; A.AttachmentPoints[3].Y := 680; // basso-sinistra
A.AttachmentPoints[4].X := 250; A.AttachmentPoints[4].Y := 680; // basso-destra
A.Rectangle.Left := 50; A.Rectangle.Top := 700; // racchiude il quad
A.Rectangle.Right := 250; A.Rectangle.Bottom := 680;
A.ContentsText := 'Highlighted region';
Pdf.CreateAnnotation(A);
Pdf.SaveAs('highlighted.pdf');
finally
Pdf.Free;
end;
end;
Cambiare decorazione costa una riga. anUnderline, anStrikeout e anSquiggly prendono lo stesso identico record, quad compresi; ISO 32000-1 descrive i quattro insieme, e differiscono solo per come viene dipinta la regione del quad. I sottotipi fuori da quella famiglia, come anSquare, anCircle e anText, si posizionano solo in base a Rectangle; per questi lascia HasAttachmentPoints a False e AttachmentPointSets vuoto, e nessun quad viene scritto
Selezioni su più righe: un'annotazione, più quad
Una selezione che va a capo su tre righe ha bisogno di tre quad, uno per riga, perché un unico quadrilatero che le copre tutte e tre dipingerebbe anche la parte destra della prima riga e quella sinistra della terza. TPdfAnnotation tiene tutti i quad in AttachmentPointSets, un array dinamico di TQuadrilateralPoint; il singolo campo AttachmentPoints resta come alias della prima voce. Quando AttachmentPointSets non è vuoto, CreateAnnotation scrive tutte le sue voci in ordine e il campo singolo viene ignorato
Potresti invece creare un'annotazione per riga. Il rendering è identico, ma chi revisiona il documento si ritrova tre commenti, tre popup e tre elementi da cancellare per quella che era una sola evidenziazione. Metti le righe in un'unica annotazione. La geometria si ricava facilmente da una ricerca, perché TPdf.CreateDocumentSearch restituisce ogni corrispondenza con un array Rectangles che contiene un rettangolo per ogni run di testo su una riga, già in coordinate di pagina:
function QuadFromRect(const R: TPdfRectangle): TQuadrilateralPoint;
begin
Result[1].X := R.Left; Result[1].Y := R.Top; // alto-sinistra
Result[2].X := R.Right; Result[2].Y := R.Top; // alto-destra
Result[3].X := R.Left; Result[3].Y := R.Bottom; // basso-sinistra
Result[4].X := R.Right; Result[4].Y := R.Bottom; // basso-destra
end;
// Helper tuo, non fa parte della libreria: unione dei rettangoli delle righe
function UnionRect(const Rects: TPdfRectangles): TPdfRectangle;
var
I: Integer;
begin
Result := Rects[0];
for I := 1 to High(Rects) do
begin
if Rects[I].Left < Result.Left then Result.Left := Rects[I].Left;
if Rects[I].Right > Result.Right then Result.Right := Rects[I].Right;
if Rects[I].Top > Result.Top then Result.Top := Rects[I].Top;
if Rects[I].Bottom < Result.Bottom then Result.Bottom := Rects[I].Bottom;
end;
end;
procedure HighlightMatches(Pdf: TPdf; const Needle: WString);
var
Search: TPdfDocumentSearch;
Match: TPdfDocumentSearchResult;
Found: array of TPdfDocumentSearchResult;
A: TPdfAnnotation;
I, J: Integer;
begin
// Raccogli tutte le corrispondenze prima di modificare qualsiasi pagina
Search := Pdf.CreateDocumentSearch(Needle, [seWholeWord]);
try
while Search.Next(Match) do
if Length(Match.Rectangles) > 0 then
begin
SetLength(Found, Length(Found) + 1);
Found[High(Found)] := Match;
end;
finally
Search.Free;
end;
for I := 0 to High(Found) do
begin
Pdf.PageNumber := Found[I].PageNumber;
A := Default(TPdfAnnotation);
A.Subtype := anHighlight;
A.HasColor := True;
A.Color := clYellow;
A.ColorAlpha := $80;
SetLength(A.AttachmentPointSets, Length(Found[I].Rectangles));
for J := 0 to High(Found[I].Rectangles) do
A.AttachmentPointSets[J] := QuadFromRect(Found[I].Rectangles[J]);
A.Rectangle := UnionRect(Found[I].Rectangles);
A.ContentsText := Found[I].Text;
Pdf.CreateAnnotation(A);
end;
end;
I rettangoli della ricerca sono allineati agli assi, quattro numeri ciascuno, quindi su testo ruotato il quad risultante copre il bounding box del run invece di seguirne l'inclinazione. Per testo orizzontale dritto, cioè la maggior parte di quello che si evidenzia, il box e l'area dei glifi coincidono. Se invece ti serve la geometria per singolo carattere, la guida all'estrazione del testo con il componente PDFium copre CharacterRectangle e le chiamate correlate della text page, e l'articolo su misurazione del testo e word wrap mostra come calcolare l'estensione delle righe per testo che stai per generare
La modifica di un'annotazione di markup esistente passa da Pdf.Annotation[Index] := A, che chiama SetAnnotation; il sottotipo nel record deve coincidere con quello memorizzato, altrimenti la chiamata solleva 'Incorrect annotation subtype'. I quad vengono riscritti indice per indice, e le voci in più di AttachmentPointSets vengono accodate. PDFium non espone alcuna chiamata che rimuova un singolo quad, quindi passare da tre quad a due lascia il terzo nel file. Per accorciare un'evidenziazione, cancellala con DeleteAnnotation e ricreala con l'array più corto
AttachmentPoints conta da 1, tranne in C++
TQuadrilateralPoint è dichiarato come array [1..4] of TPdfPoint, e la numerazione segue quella degli angoli nella specifica: l'elemento 1 è (x1, y1), l'elemento 4 è (x4, y4). Il codice scritto a memoria con abitudini zero-based sbaglia qui in un modo che il compilatore non sempre intercetta. Un ciclo come for I := 0 to 3 do A.AttachmentPoints[I] := ... compila sia in Delphi sia in Free Pascal, perché l'indice si conosce solo a run time. Con il range checking disattivato, che è il default dei progetti Delphi, la scrittura per l'indice 0 finisce sui byte subito prima dell'array, dentro i campi precedenti del record, e il quad stesso si tiene un angolo a zero. Non viene sollevato nulla
Un indice costante è un altro discorso. Il compilatore può confrontarlo con i limiti dichiarati prima che giri qualsiasi cosa, e fpc, per esempio, rifiuta un AttachmentPoints[0] letterale con un errore di range. È l'indice calcolato la forma che passa inosservata. Compila il codice delle annotazioni almeno una volta con {$R+} in Delphi, o con fpc, prima di fidarti; con il range checking attivo, il ciclo a run time visto sopra solleva ERangeError all'indice 0
C++Builder ribalta la regola. Il PDFium.hpp generato dichiara TQuadrilateralPoint come System::StaticArray<TPdfPoint, 4>, e un array statico C++ parte da zero qualunque fosse il limite inferiore in Pascal. In C++ gli angoli sono quindi da AttachmentPoints[0] a AttachmentPoints[3], sempre in ordine Z. Portare il codice di esempio Delphi riga per riga mantiene gli indici da 1 a 4, il che sposta ogni angolo di uno e scrive l'ultimo oltre la fine dell'array
Rileggere i quad
Il controllo più rapido per sapere se un'annotazione di markup è finita al posto giusto è rileggerla con la stessa API. Pdf.Annotation[Index] riempie AttachmentPointSets con tutti i quad memorizzati sull'annotazione, e HasAttachmentPoints è True quando ce n'è almeno uno:
var
I, Q: Integer;
B: TPdfAnnotation;
begin
Pdf.PageNumber := 1;
for I := 0 to Pdf.AnnotationCount - 1 do
begin
B := Pdf.Annotation[I];
if B.Subtype in [anHighlight, anUnderline, anStrikeout, anSquiggly] then
for Q := 0 to High(B.AttachmentPointSets) do
Writeln(Format('annot %d quad %d: TL (%.1f, %.1f) BR (%.1f, %.1f)',
[I, Q,
B.AttachmentPointSets[Q][1].X, B.AttachmentPointSets[Q][1].Y,
B.AttachmentPointSets[Q][4].X, B.AttachmentPointSets[Q][4].Y]));
end;
end;
Per la singola evidenziazione creata prima, la riga attesa è annot 0 quad 0: TL (50.0, 700.0) BR (250.0, 680.0); una Y in alto a sinistra più bassa della Y in basso a destra significa che gli angoli sono entrati capovolti. I quad viaggiano anche con l'annotazione quando scambi markup con altri strumenti: l'attributo coords in XFDF li contiene tutti, otto numeri per quad, come descritto nell'articolo su esportazione e importazione XFDF. Dopodiché apri il file salvato in un secondo viewer e controlla che il colore stia sui glifi e non di fianco, perché è proprio il viewer che costruisce da sé l'aspetto a partire dai QuadPoints a smascherare un ordine degli angoli sbagliato
Il record di annotazione, l'array multi-quad e il writer che tiene conto del conteggio usati in tutto l'articolo fanno parte del componente PDFium per Delphi, C++Builder e Lazarus, dove il riferimento completo dell'API delle annotazioni sta accanto alle chiamate di ricerca ed estrazione del testo su cui si appoggiano questi esempi