FPDFPage_CreateAnnot'in az önce döndürdüğü bir vurgu ek açıklaması FPDFAnnot_CountAttachmentPoints = 0 bildirir ve ona karşı FPDFAnnot_SetAttachmentPoints(Annot, 0, Quad) çağrısı, ne koordinat verirseniz verin 0 döndürür. Sorun koordinatlar değildir. İndeks 0 "var olan sıfır numaralı dörtgeni değiştir" demektir; yeni bir ek açıklamada hiç dörtgen yoktur ve yuva oluşturan çağrı FPDFAnnot_AppendAttachmentPoints'tir
Bu bir paragrafa sığar; yine de üzerinde saatler kaybetmek kolaydır, çünkü false dönüşe doğal tepki geometriye kuşku duymaktır. İnsanlar köşeleri yer değiştirir, Y eksenini çevirir, aygıt uzayına ve geriye dönüştürür. Bunların hiçbiri sonucu değiştirmez. Aşağıda, dörtgenlerin ISO 32000-1'e göre ne içermesi gerektiği, bunların bileşen API'siyle ve ham C işlevleriyle nasıl yazılacağı, çok satırlı seçimler ve Delphi, Free Pascal ile C++Builder arasında farklılaşan bir indeksleme tuzağı yer alıyor. Bu yazı, aynı yapıları öbür yönden gezen mevcut ek açıklamaları okuma ve inceleme makalesinin oluşturma tarafındaki eşidir
QuadPoints, ISO 32000-1 §12.5.6.10'da ne demektir
QuadPoints, dört metin işaretleme alt türünün — Highlight, Underline, Squiggly ve StrikeOut — zorunlu girişidir: öntanımlı kullanıcı uzayında n adet dörtgen veren 8×n sayılık bir dizidir ve her dörtgen, ek açıklamanın altındaki metinde bir sözcüğü ya da bitişik sözcük grubunu kapsar. Ek açıklama yine de her ek açıklamanın ihtiyaç duyduğu Rect'i taşır; ama işaretleme alt türlerinde hangi gliflerin işaretlendiğini dörtgenler söyler, Rect onları yalnızca sınırlar. Metin sayfada döndürülmüş ya da eğik olabilir; dikdörtgen yerine dörtgen kullanılmasının nedeni budur ve her köşe bağımsız bir nokta olarak saklanır: x1 y1 x2 y2 x3 y3 x4 y4
Köşe sırası, spesifikasyon metniyle dolaşımdaki dosyaların ayrıştığı yerdir. §12.5.6.10, dört köşenin saat yönünün tersine verildiğini söyler ve metnin (x1, y1)-(x2, y2) kenarına göre yönlendirildiğini ekler. Acrobat ve Acrobat'ın yazdığını okumak için yapılmış uzun araç silsilesi bunun yerine bir Z deseni kullanır: 1. nokta sol üst, 2. sağ üst, 3. sol alt, 4. sağ alt. O düzen yön cümlesini yine de gözetir; 1–2 kenarı metnin tepesi boyunca akar ama şekil etrafında saat yönünün tersine bir tur değildir. Z sırasıyla yazın. Harfiyen saat yönünün tersine bir liste (sol üst, sol alt, sağ alt, sağ üst) kağıt üzerinde savunulabilir; ama noktaları Z olarak gezen bir okuyucu sol üst, sol alt, sağ üst, sağ alt görür ve o kenarlar kemen yayı gibi çaprazlaşır
Bütün koordinatlar point cinsinden sayfa koordinatlarıdır; başlangıç sayfanın sol alt köşesinde, Y yukarı doğru büyür. A4 sayfasının tepesine yakın bir metin satırının Y değerleri bu yüzden 700-800 civarındadır ve üst kenarı daha büyük Y taşır. Spesifikasyon ayrıca, ikisi de varolduğunda görünüm akışına (AP) QuadPoints'ten öncelik verir; dörtgenler, işaretlemeyi kendisi üreten görüntüleyiciler için en çok işe yarar
FPDFAnnot_SetAttachmentPoints neden false döndürür?
FPDFAnnot_SetAttachmentPoints, yeni bir ek açıklamada false döndürür çünkü yalnızca çoktan var olan bir dörtgeni değiştirir. PDFium başlığı sözleşmeyi açıkça yazar: quad_index, "FPDFAnnot_CountAttachmentPoints() sonucunun içinde olmak zorundadır". FPDFPage_CreateAnnot ile yapılan her ek açıklama sıfır sayıyla başlar; değiştirilecek 0 indeksi yoktur. FPDFAnnot_AppendAttachmentPoints bir yuva ekler ve sayıyı bir artırır; ondan sonra 0 indeksi vardır ve Set onu kabul eder. İki işlev de PDFium başlıklarında deneysel (experimental) işaretlidir ve ikisi de, yeni dörtgen eskinden daha uzağa uzandığında mevcut görünüm akışının sınırlayıcı kutusunu genişletir
PDFium Bileşeni, bütün FPDFAnnot_* giriş noktalarını PDFium.pas'ta açık eder; FS_QUADPOINTSF kaydı ile size_t takma adı FPdfView.pas'ta durur. Bir ek açıklama tanıtıcısını kendiniz tutuyorsanız her yazmadan önce sayıya göre yol seçin:
uses
SysUtils, PDFium, FPdfView;
// Etkin sayfanın AnnotIndex numaralı ek açıklamasına QuadIndex konumuna Quad yazar:
// yuva varsa değiştirir, yoksa yeni bir tane ekler
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;
Aynı işlev ailesinde ikinci bir tuzak daha yatar. FPDFAnnot_CountAttachmentPoints işaretsiz olan size_t döndürür; dörtgensiz bir ek açıklama için her eski for I := 0 to Count - 1 döngüsü, işaretsiz aritmetikte 0 − 1 hesaplar ve olabilecek en büyük değere sarar. Dörtgenler üzerindeki her döngüye girmeden önce Count > 0 sınayın ya da önce işaretli bir türe dönüştürün. Öbür araçların işaretlemeleri neredeyse her zaman en az bir dörtgenle gelir; yeni yaratılan bir ek açıklama sıfırla gelir
TPdf.CreateAnnotation ile vurgulama oluşturma
Bileşen API'siyle Append ile Set arasında asla seçim yapmazsınız. TPdf.CreateAnnotation ile TPdf.SetAnnotation, ek açıklamanın kaç dörtgen taşıdığına bakar; var olan yuvaları değiştirir, kalanını ekler. Böylece oluşturma yolu ekler, güncelleme yolu değiştirir. Sizin verdiğiniz şey Subtype, renk, dörtgen ve Rectangle taşıyan bir TPdfAnnotation kaydıdır
Kaydın burada önemli iki ayrıntısı var. Kaydı Default(TPdfAnnotation) ile ilkleyin. Kayıt dizeler ve dinamik diziler taşır; hâlâ bir dize tutan kayıt üzerine FillChar o dizeyi sızdırır, bu yüzden yeniden kullandığınız her kayıt için Default daha güvenli alışkanlıktır. Ve Rectangle'ı daima doldurun: bileşen onu her oluşturmada ve güncellemede ek açıklamanın Rect'i olarak yazar; sıfırlanmış bir kayıt, dörtgenler doğruyken bile [0 0 0 0] bir Rect üretir. CreateAnnotation etkin sayfada çalışır; AddPage yeni sayfa için, PageNumber var olan belge için etkin sayfayı belirler ve PDFium istenen alt türü oluşturamadığında 'Unsupported annotation subtype' istisnası fırlatır
var
Pdf: TPdf;
A: TPdfAnnotation;
begin
Pdf := TPdf.Create(nil);
try
Pdf.CreateDocument;
Pdf.AddPage(0, 595, 842); // A4; etkin sayfa olur
A := Default(TPdfAnnotation);
A.Subtype := anHighlight;
A.HasColor := True;
A.Color := clYellow;
A.ColorAlpha := $80; // alfa, renkle birlikte iletilir
A.HasAttachmentPoints := True;
A.AttachmentPoints[1].X := 50; A.AttachmentPoints[1].Y := 700; // sol üst
A.AttachmentPoints[2].X := 250; A.AttachmentPoints[2].Y := 700; // sağ üst
A.AttachmentPoints[3].X := 50; A.AttachmentPoints[3].Y := 680; // sol alt
A.AttachmentPoints[4].X := 250; A.AttachmentPoints[4].Y := 680; // sağ alt
A.Rectangle.Left := 50; A.Rectangle.Top := 700; // dörtgeni sarar
A.Rectangle.Right := 250; A.Rectangle.Bottom := 680;
A.ContentsText := 'Highlighted region';
Pdf.CreateAnnotation(A);
Pdf.SaveAs('highlighted.pdf');
finally
Pdf.Free;
end;
end;
Süslemeyi değiştirmek bir satıra mal olur. anUnderline, anStrikeout ve anSquiggly özdeş kaydı, dörtgenleriyle birlikte alır; ISO 32000-1 dördünü birlikte anlatır ve aralarındaki tek fark, dörtgen bölgesinin nasıl boyandığıdır. O ailenin dışındaki alt türler, anSquare, anCircle, anText gibi, kendilerini yalnızca Rectangle'dan konumlandırır; onlar için HasAttachmentPoints'i False bırakın, AttachmentPointSets'i boş tutun, hiç dörtgen yazılmaz
Çok satırlı seçimler: tek ek açıklama, birkaç dörtgen
Üç satıra saran bir seçimin üç dörtgene ihtiyacı vardır, satır başına birine; üçünü birden kaplayan tek bir dörtgen, birinci satırın sağ ucunu ve üçüncü satırın sol ucunu da boyardı. TPdfAnnotation, her dörtgeni AttachmentPointSets içinde taşır — TQuadrilateralPoint türünden bir dinamik dizi; tekil AttachmentPoints alanı ilk girdi için bir takma ad olarak kalır. AttachmentPointSets boş olmadığında CreateAnnotation girdilerinin tamamını sırayla yazar ve tekil alan yok sayılır
Bunun yerine satır başına bir ek açıklama da oluşturabilirsiniz. Görüntü aynı olur; ama inceleyen kişi, tek bir vurgu için üç yorum, üç baloncuk ve üç silinecek madde görür. Satırları tek ek açıklamaya koyun. Geometriyi aramadan almak kolaydır; TPdf.CreateDocumentSearch her eşleşmeyi, bir satırdaki metin bölümü başına bir dikdörtgen tutan Rectangles dizisiyle döndürür, koordinatlar hazırca sayfa uzayındadır:
function QuadFromRect(const R: TPdfRectangle): TQuadrilateralPoint;
begin
Result[1].X := R.Left; Result[1].Y := R.Top; // sol üst
Result[2].X := R.Right; Result[2].Y := R.Top; // sağ üst
Result[3].X := R.Left; Result[3].Y := R.Bottom; // sol alt
Result[4].X := R.Right; Result[4].Y := R.Bottom; // sağ alt
end;
// Kendi yardımcınız, kütüphanenin parçası değil: satır dikdörtgenlerinin birleşimi
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
// Herhangi bir sayfayı düzenlemeden önce bütün eşleşmeleri topla
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;
Arama dikdörtgenleri eksen hizalıdır, her biri dört sayıdır; döndürülmüş metinde çıkan dörtgen, eğimi izlemek yerine bölümün sınırlayıcı kutusunu kaplar. Düz yatay metinde — vurgulanan şeyin çoğu budur — kutu ile glif alanı çakışır. Karakter başına geometri gerekiyorsa PDFium Bileşeni ile metin ayıklama rehberi CharacterRectangle'ı ve ilgili metin sayfası çağrılarını işler; metin ölçümü ve satır kaydırma makalesi ise üretmek üzere olduğunuz metnin satır genişliklerini nasıl hesaplayacağınızı gösterir
Var olan bir işaretleme ek açıklamasını düzenlemek Pdf.Annotation[Index] := A'dan geçer; bu, SetAnnotation'ı çağırır ve kayıttaki alt tür, saklanmışla uyuşmazsa çağrı 'Incorrect annotation subtype' fırlatır. Dörtgenler indeks indeks yeniden yazılır ve AttachmentPointSets'teki fazladan girdiler eklenir. PDFium tek bir dörtgeni kaldıran bir çağrı açığa etmez; üç dörtgenden ikiye inmek üçüncüyü dosyada bırakır. Bir vurguyu küçültmek için onu DeleteAnnotation ile silin ve kısa diziyle yeniden oluşturun
AttachmentPoints 1'den sayar, C++ hariç
TQuadrilateralPoint, array [1..4] of TPdfPoint olarak bildirilir ve numaralandırma spesifikasyondaki köşe numaralarıyla uyuşur: 1. eleman (x1, y1), 4. eleman (x4, y4). Sıfır tabanlı alışkanlıklarla hafızadan yazılan kod, derleyicinin her yakalayamadığı biçimde bunu yanlış yapar. for I := 0 to 3 do A.AttachmentPoints[I] := ... gibi bir döngü Delphi'de de Free Pascal'da da derlenir; çünkü indeks yalnızca çalışma zamanında bilinir. Aralık denetimi kapalıyken — Delphi projesinin öntanımlısı budur — 0 indeksine yazma, dizinin hemen önündeki baytlara, önceki kayıt alanlarının içine düşer ve dörtgenin kendisi sıfır köşe taşımaya devam eder. Hiçbir şey istisna üretmez
Sabit indeks başka bir meseledir. Derleyici onu herhangi bir şey çalışmadan önce bildirilen sınırlarla karşılaştırabilir ve fpc her şeyden önce, AttachmentPoints[0] yazımını aralık hatasıyla reddeder. Aradan sıyan biçim hesaplanan indekstir. Ek açıklama koduna güvenmeden önce Delphi'de en az bir kez {$R+} ile ya da fpc üzerinden derleyin; aralık denetimi açıkken yukarıdaki çalışma zamanı döngüsü 0 indeksinde ERangeError fırlatır
C++Builder kuralı tersine çevirir. Üretilen PDFium.hpp, TQuadrilateralPoint'i System::StaticArray<TPdfPoint, 4> olarak bildirir ve bir C++ statik dizisi, Pascal alt sınırı ne olursa olsun sıfırdan başlar. C++'da köşeler bu yüzden AttachmentPoints[0]'dan AttachmentPoints[3]'e gider; yine Z sırasında. Delphi örnek kodunu satır satır taşıyıp 1'den 4'e kalan indeksleri korumak, her köşeyi bir kaydırır ve sonuncuyu dizinin sonuna yazar
Dörtgenleri geri okumak
Bir işaretleme ek açıklamasının doğru oturup oturmadığının en hızlı denetimi, onu aynı API'den geri okumaktır. Pdf.Annotation[Index], AttachmentPointSets'i ek açıklamada saklı her dörtgenle doldurur ve en az biri varken HasAttachmentPoints True'dur:
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;
Önceki bölümde oluşturulan tek vurgu için beklenen satır annot 0 quad 0: TL (50.0, 700.0) BR (250.0, 680.0) olur; sol üst Y'si sağ alt Y'sinden küçükse köşeler baş aşağı girmiştir. Dörtgenler, işaretlemeyi öbür araçlarla takas ederken ek açıklamayla birlikte yol alır: XFDF'deki coords özniteliği, XFDF dışa ve içe aktarma makalesinin anlattığı gibi, dörtgen başına sekiz sayı olmak üzere hepsini taşır. Sonra kaydedilen dosyayı ikinci bir görüntüleyicide açın ve rengin gliflerin üzerinde durduğunu, yanlarında değil, denetleyin; çünkü görünümünü QuadPoints'ten kendisi kuran görüntüleyici, bozuk köşe sırasını ortaya çıkaran kişidir
Bu makale boyunca kullanılan ek açıklama kaydı, çok dörtgenli dizi ve sayıya duyarlı yazıcı, Delphi, C++Builder ve Lazarus için PDFium Bileşeni ile gelir; tam ek açıklama API başvurusu, bu örneklerin dayandığı metin arama ve ayıklama çağrılarının yanında durur