Uma anotação de realce que FPDFPage_CreateAnnot devolveu há um instante reporta FPDFAnnot_CountAttachmentPoints = 0, e FPDFAnnot_SetAttachmentPoints(Annot, 0, Quad) devolve 0 contra ela, com as coordenadas que você passar. As coordenadas não são o problema. O índice 0 significa "substituir o quadrilátero 0 existente", uma anotação nova não tem quadrilátero algum, e a chamada que cria uma posição é FPDFAnnot_AppendAttachmentPoints
Isso cabe em um parágrafo, mas é fácil perder horas com isso, porque a reação natural a um devolve-falso é desconfiar da geometria. A gente troca os cantos de lugar, inverte o eixo Y, converte para espaço de dispositivo e volta. Nada disso muda o resultado. O que segue cobre o que os quadriláteros devem conter de acordo com a ISO 32000-1, como escrevê-los pela API do componente e pelas funções C brutas, seleções de várias linhas e uma armadilha de indexação que muda entre Delphi, Free Pascal e C++Builder. É o complemento, do lado da criação, do artigo sobre ler e revisar anotações existentes, que percorre as mesmas estruturas na direção oposta
O que os QuadPoints significam na ISO 32000-1 §12.5.6.10
QuadPoints é uma entrada obrigatória nos quatro subtipos de marcação de texto, Highlight, Underline, Squiggly e StrikeOut: um array de 8×n números que descreve n quadriláteros no user space padrão, em que cada quadrilátero abrange uma palavra ou um grupo de palavras contíguas do texto sob a anotação. A anotação continua carregando um Rect, que toda anotação precisa ter, mas nos subtipos de marcação são os quadriláteros que dizem quais glifos estão marcados, e o Rect apenas os delimita. Quadriláteros em vez de retângulos porque o texto pode estar rotacionado ou cisalhado na página, então cada canto é guardado como um ponto independente: x1 y1 x2 y2 x3 y3 x4 y4
A ordem dos cantos é onde o texto da especificação e os arquivos em circulação se separam. A §12.5.6.10 diz que os quatro vértices vêm em sentido anti-horário, e acrescenta que o texto se orienta pela aresta de (x1, y1) a (x2, y2). O Acrobat, e a longa fila de ferramentas construídas para ler o que o Acrobat escreve, usam um padrão em Z: ponto 1 superior esquerdo, ponto 2 superior direito, ponto 3 inferior esquerdo, ponto 4 inferior direito. Esse arranjo continua respeitando a frase sobre orientação, já que a aresta 1–2 corre ao longo da parte de cima do texto, mas não é um passeio anti-horário ao redor da forma. Escreva em ordem Z. Uma lista literalmente anti-horária (superior esquerdo, inferior esquerdo, inferior direito, superior direito) se defende no papel, mas um leitor que percorre os pontos em Z lê superior esquerdo, inferior esquerdo, superior direito, inferior direito, e essas arestas se cruzam formando um laço
Todas as coordenadas são coordenadas de página em pontos, origem no canto inferior esquerdo da página, Y crescendo para cima. Uma linha de texto perto do topo de uma página A4 tem valores de Y em torno de 700 a 800, e a borda superior dela tem o maior Y. A especificação também dá a um appearance stream (AP) precedência sobre os QuadPoints quando ambos existem, então os quadriláteros importam mais para os visualizadores que geram a marcação por conta própria
Por que FPDFAnnot_SetAttachmentPoints devolve false?
FPDFAnnot_SetAttachmentPoints devolve false em uma anotação nova porque ela só substitui um quadrilátero que já existe. O cabeçalho do PDFium declara o contrato diretamente: o quad_index "precisa estar dentro do resultado de FPDFAnnot_CountAttachmentPoints()". Toda anotação criada por FPDFPage_CreateAnnot começa com contagem zero, então não existe índice 0 a substituir. FPDFAnnot_AppendAttachmentPoints acrescenta uma posição e faz a contagem crescer um; depois disso, o índice 0 existe e o Set o aceita. As duas funções estão marcadas como experimentais nos cabeçalhos do PDFium, e as duas também alargam a caixa delimitadora de um appearance stream existente quando o novo quadrilátero alcança mais longe que o antigo
O PDFium Component expõe todos os pontos de entrada FPDFAnnot_* em PDFium.pas, e o registro FS_QUADPOINTSF e o alias size_t vivem em FPdfView.pas. Se você segura um handle de anotação por conta própria, consulte a contagem antes de cada escrita:
uses
SysUtils, PDFium, FPdfView;
// Escreve Quad em QuadIndex na anotação AnnotIndex da página ativa:
// substitui a posição se ela existe e, senão, acrescenta uma nova
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;
Uma segunda armadilha mora na mesma família de funções. FPDFAnnot_CountAttachmentPoints devolve size_t, que é sem sinal, então o familiar for I := 0 to Count - 1 em uma anotação sem quadriláteros calcula 0 − 1 em aritmética sem sinal e dá a volta para o maior valor possível. Teste Count > 0 antes de entrar em qualquer loop sobre quadriláteros, ou faça cast para um tipo com sinal antes. Marcação vinda de outras ferramentas quase sempre chega com pelo menos um quadrilátero. Uma anotação recém-criada chega com zero
Criando um realce com TPdf.CreateAnnotation
Pela API do componente você nunca escolhe entre Append e Set. TPdf.CreateAnnotation e TPdf.SetAnnotation verificam quantos quadriláteros a anotação já tem, substituem as posições que existem e acrescentam o restante, então o caminho de criação acrescenta e o caminho de atualização substitui. O que você fornece é um registro TPdfAnnotation com Subtype, cor, o quadrilátero e um Rectangle
Dois detalhes do registro importam aqui. Inicialize o registro com Default(TPdfAnnotation). O registro contém strings e arrays dinâmicos, e um FillChar sobre um que já carrega uma string simplesmente vaza essa string, então Default é o hábito mais seguro para todo registro que você reutilizar. E sempre preencha o Rectangle: o componente o escreve como o Rect da anotação em toda criação e atualização, então um registro zerado produz um Rect [0 0 0 0] mesmo quando os quadriláteros estão certos. CreateAnnotation trabalha na página ativa, que AddPage define para uma página nova e PageNumber define para um documento existente, e ele lança 'Unsupported annotation subtype' quando o PDFium não consegue criar o subtipo pedido
var
Pdf: TPdf;
A: TPdfAnnotation;
begin
Pdf := TPdf.Create(nil);
try
Pdf.CreateDocument;
Pdf.AddPage(0, 595, 842); // A4, torna-se a página ativa
A := Default(TPdfAnnotation);
A.Subtype := anHighlight;
A.HasColor := True;
A.Color := clYellow;
A.ColorAlpha := $80; // o alpha é passado junto com a cor
A.HasAttachmentPoints := True;
A.AttachmentPoints[1].X := 50; A.AttachmentPoints[1].Y := 700; // superior esquerdo
A.AttachmentPoints[2].X := 250; A.AttachmentPoints[2].Y := 700; // superior direito
A.AttachmentPoints[3].X := 50; A.AttachmentPoints[3].Y := 680; // inferior esquerdo
A.AttachmentPoints[4].X := 250; A.AttachmentPoints[4].Y := 680; // inferior direito
A.Rectangle.Left := 50; A.Rectangle.Top := 700; // envolve o quadrilátero
A.Rectangle.Right := 250; A.Rectangle.Bottom := 680;
A.ContentsText := 'Highlighted region';
Pdf.CreateAnnotation(A);
Pdf.SaveAs('highlighted.pdf');
finally
Pdf.Free;
end;
end;
Trocar a decoração custa uma linha. anUnderline, anStrikeout e anSquiggly aceitam o registro idêntico, quadriláteros e tudo; a ISO 32000-1 descreve os quatro juntos, e eles só diferem em como a região do quadrilátero é pintada. Subtipos fora dessa família, como anSquare, anCircle e anText, se posicionam apenas pelo Rectangle; deixe HasAttachmentPoints em False e AttachmentPointSets vazio para eles, e nenhum quadrilátero é escrito
Seleções de várias linhas: uma anotação, vários quadriláteros
Uma seleção que quebra em três linhas precisa de três quadriláteros, um por linha, porque um único quadrilátero cobrindo as três também pintaria o fim da primeira linha e o começo da terceira. TPdfAnnotation carrega todos os quadriláteros em AttachmentPointSets, um array dinâmico de TQuadrilateralPoint; o campo único AttachmentPoints permanece como alias da primeira entrada. Quando AttachmentPointSets não está vazio, CreateAnnotation escreve todas as suas entradas em ordem e o campo único é ignorado
Você também poderia criar uma anotação por linha. Renderiza igual, mas um revisor então vê três comentários, três popups e três itens para apagar no lugar do que era um realce. Coloque as linhas em uma anotação. A geometria vem fácil de uma busca, porque TPdf.CreateDocumentSearch devolve cada ocorrência com um array Rectangles contendo um retângulo por trecho de texto na linha, já em coordenadas de página:
function QuadFromRect(const R: TPdfRectangle): TQuadrilateralPoint;
begin
Result[1].X := R.Left; Result[1].Y := R.Top; // superior esquerdo
Result[2].X := R.Right; Result[2].Y := R.Top; // superior direito
Result[3].X := R.Left; Result[3].Y := R.Bottom; // inferior esquerdo
Result[4].X := R.Right; Result[4].Y := R.Bottom; // inferior direito
end;
// Helper seu, fora da biblioteca: união dos retângulos de linha
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
// Coleta todas as ocorrências antes de editar qualquer página
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;
Os retângulos da busca são alinhados aos eixos, quatro números cada, então em texto rotacionado o quadrilátero resultante cobre a caixa delimitadora do trecho em vez de seguir a inclinação. Para texto horizontal reto, que é a maior parte do que se realça, a caixa e a área dos glifos coincidem. Se você precisa de geometria por caractere, o guia de extração de texto com o PDFium Component cobre CharacterRectangle e as chamadas relacionadas de text page, e o artigo de medição de texto e quebra de linha mostra como calcular extensões de linha para texto que você está prestes a gerar
Editar uma anotação de marcação existente passa por Pdf.Annotation[Index] := A, que chama SetAnnotation; o subtipo no registro deve bater com o armazenado, ou a chamada lança 'Incorrect annotation subtype'. Os quadriláteros são reescritos índice por índice, e entradas extras em AttachmentPointSets são acrescentadas. O PDFium não expõe chamada que remova um único quadrilátero, então sair de três quadriláteros para dois deixa o terceiro no arquivo. Para encolher um realce, apague-o com DeleteAnnotation e crie-o de novo com o array menor
AttachmentPoints conta a partir de 1, exceto no C++
TQuadrilateralPoint é declarado como array [1..4] of TPdfPoint, e a numeração casa com os números dos cantos na especificação: o elemento 1 é (x1, y1), o elemento 4 é (x4, y4). Código escrito de memória, com hábito zero-based, erra isso de um jeito que o compilador nem sempre pega. Um loop como for I := 0 to 3 do A.AttachmentPoints[I] := ... compila tanto no Delphi quanto no Free Pascal, porque o índice só é conhecido em tempo de execução. Com a verificação de faixa desligada, que é o padrão de projeto do Delphi, a escrita no índice 0 cai nos bytes logo antes do array, dentro dos campos do registro anterior, e o quadrilátero em si fica com um canto zero. Nada lança erro
Índice constante é outro bicho. O compilador pode compará-lo com os limites declarados antes de qualquer coisa rodar, e o fpc, por exemplo, rejeita um AttachmentPoints[0] literal com erro de faixa. A forma computada é a que escapa. Compile o código de anotações ao menos uma vez com {$R+} no Delphi, ou pelo fpc, antes de confiar nele; com a verificação de faixa ligada, o loop de tempo de execução acima lança ERangeError no índice 0
O C++Builder inverte a regra. O PDFium.hpp gerado declara TQuadrilateralPoint como System::StaticArray<TPdfPoint, 4>, e um array estático de C++ começa do zero, fosse qual fosse o limite inferior Pascal. No C++ os cantos são, portanto, AttachmentPoints[0] a AttachmentPoints[3], ainda em ordem Z. Portar código de exemplo Delphi linha a linha mantém os índices 1 a 4, o que desloca cada canto em um e escreve o último além do fim do array
Lendo os quadriláteros de volta
A conferência mais rápida de que uma anotação de marcação aterrissou certa é lê-la de volta pela mesma API. Pdf.Annotation[Index] enche AttachmentPointSets com todo quadrilátero guardado na anotação, e HasAttachmentPoints é True quando há pelo menos um:
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;
Para o realce único criado antes, a linha esperada é annot 0 quad 0: TL (50.0, 700.0) BR (250.0, 680.0); um Y superior esquerdo menor que o Y inferior direito significa que os cantos entraram de cabeça para baixo. Os quadriláteros também viajam com a anotação quando você troca marcação com outras ferramentas: o atributo coords no XFDF guarda todos eles, oito números por quadrilátero, como descrito em o artigo de exportação e importação de XFDF. Depois disso, abra o arquivo salvo em um segundo visualizador e confira se a cor cai sobre os glifos e não ao lado deles, porque um visualizador que constrói a própria aparência a partir dos QuadPoints é justamente o que expõe uma ordem de cantos errada
O registro de anotação, o array de vários quadriláteros e o escritor ciente da contagem usados ao longo deste artigo vêm no PDFium Component para Delphi, C++Builder e Lazarus, onde a referência completa da API de anotações fica ao lado das chamadas de busca e extração de texto de que esses exemplos dependem