LlosLab Software Development BlogEngineering notes for PDF, Delphi, and document software developers.

기술 문서

PDFium Component: Delphi에서 annotation review UI

PDFium Component

Delphi와 C++Builder 애플리케이션에는 PDFium VCL Component 워크플로를, Lazarus/FPC에는 PDFium LCL Component 워크플로를 통합하여 보기, 렌더링, 폼, 인쇄, 프리플라이트 보고서, 표준 중심 검증을 소스 코드 컴포넌트로 구현할 수 있습니다.

이 글은 teams adding review, markup, approval, or quality-control panels to a Delphi PDF viewer을 위한 글입니다. annotation review UI을 단순한 컴포넌트 호출이 아니라 운영 환경의 문서 엔지니어링으로 다룹니다.

실제 위험은 annotations are easy to display but hard to trust when page rotation, authorship, replies, hidden states, or coordinate conversions are not handled consistently입니다. 따라서 명확한 계약, 관찰 가능한 진단, 실제 고객 파일을 반영한 회귀 샘플이 필요합니다.

아키텍처 결정

Separate review state from page rendering. which annotation types can be viewed, filtered, replied to, exported, or locked / author identity, status labels, and whether review data is stored in the PDF

  • which annotation types can be viewed, filtered, replied to, exported, or locked
  • author identity, status labels, and whether review data is stored in the PDF
  • coordinate conversion for rotation, zoom, crop boxes, and high-DPI displays
  • read-only mode for signed, protected, or externally governed documents

구현 흐름

Index annotations before showing review actions. The order below keeps the workflow reviewable for Delphi and C++Builder teams.

  1. load annotation metadata into a review index before painting page overlays
  2. normalize page coordinates and keep a stable reference for every annotation
  3. apply filters by author, status, type, page, and date without re-parsing pages
  4. tie selection in the review list to viewport navigation and highlight behavior
  5. export review summaries with enough context for non-viewer workflows

검증 증거

Review evidence that supports collaboration. Keep these fields with the output or support record.

  • annotation type, author, page, bounds, status, and reply count
  • coordinate transform used for the current zoom, rotation, and crop box
  • permission decision when a user attempts to edit a locked or signed document
  • exported review summary with stable page references

Coordinates and intent matter

A professional review UI treats annotations as structured data with authors, dates, page locations, appearance, replies, status, and permissions. The canvas view is only one presentation of that model.

Customer-visible behavior

Users do not see internal call order. They see whether the file opens, validates, prints, edits, imports, or gets rejected. The workflow should translate annotation review UI results into states users can act on.

  • load annotation metadata into a review index before painting page overlays
  • normalize page coordinates and keep a stable reference for every annotation
  • apply filters by author, status, type, page, and date without re-parsing pages
  • rotated pages can make highlights appear detached from the original text
  • popup annotations and replies may be missed when only visible marks are scanned

annotation review UI에 대한 엔지니어링 검토 노트

이 검토 노트를 사용해 기능이 데모 단계를 넘어섰고 출시, 지원, 고객 에스컬레이션 상황에서 설명할 수 있는지 확인합니다

  • 결정: which annotation types can be viewed, filtered, replied to, exported, or locked. 구현상 핵심 지점: normalize page coordinates and keep a stable reference for every annotation. 승인 증거: permission decision when a user attempts to edit a locked or signed document. 회귀 트리거: annotations on cropped pages need coordinates tied to the intended page box
  • 결정: author identity, status labels, and whether review data is stored in the PDF. 구현상 핵심 지점: apply filters by author, status, type, page, and date without re-parsing pages. 승인 증거: exported review summary with stable page references. 회귀 트리거: rotated pages can make highlights appear detached from the original text
  • 결정: coordinate conversion for rotation, zoom, crop boxes, and high-DPI displays. 구현상 핵심 지점: tie selection in the review list to viewport navigation and highlight behavior. 승인 증거: annotation type, author, page, bounds, status, and reply count. 회귀 트리거: popup annotations and replies may be missed when only visible marks are scanned
  • 결정: read-only mode for signed, protected, or externally governed documents. 구현상 핵심 지점: export review summaries with enough context for non-viewer workflows. 승인 증거: coordinate transform used for the current zoom, rotation, and crop box. 회귀 트리거: read-only review must still allow selection, navigation, filtering, and export
  • 결정: which annotation types can be viewed, filtered, replied to, exported, or locked. 구현상 핵심 지점: load annotation metadata into a review index before painting page overlays. 승인 증거: permission decision when a user attempts to edit a locked or signed document. 회귀 트리거: annotations on cropped pages need coordinates tied to the intended page box
  • 결정: author identity, status labels, and whether review data is stored in the PDF. 구현상 핵심 지점: normalize page coordinates and keep a stable reference for every annotation. 승인 증거: exported review summary with stable page references. 회귀 트리거: rotated pages can make highlights appear detached from the original text
  • 결정: coordinate conversion for rotation, zoom, crop boxes, and high-DPI displays. 구현상 핵심 지점: apply filters by author, status, type, page, and date without re-parsing pages. 승인 증거: annotation type, author, page, bounds, status, and reply count. 회귀 트리거: popup annotations and replies may be missed when only visible marks are scanned

경계 사례

  • rotated pages can make highlights appear detached from the original text
  • popup annotations and replies may be missed when only visible marks are scanned
  • read-only review must still allow selection, navigation, filtering, and export
  • annotations on cropped pages need coordinates tied to the intended page box

Delphi / C++Builder 참고 사항

PDFium Component should sit behind a small service boundary that receives files, streams, profiles, and credentials, then returns output paths, warnings, metrics, and validation status. 중요한 용어는 annotation, markup, reply, page bounds, rotation, review status.

Delphi 코드 예제

다음 Delphi 스케치는 이 주제에 맞는 실무형 서비스 경계를 보여 줍니다. 정책 검사, 로깅, 검증을 좁은 제품 호출 구간 밖에 두면 워크플로를 테스트하기 쉽습니다.

procedure TReviewForm.LoadAnnotationQueue(const FileName: string);
var
  PageNo: Integer;
begin
  PdfView.LoadFromFile(FileName);
  FQueue.Clear;
  for PageNo := 1 to PdfView.PageCount do
    AddPageAnnotationsToQueue(PdfView, PageNo, FQueue);
  FQueue.SortByAuthorAndDate;
  ShowNextReviewItem;
end;

운영 체크리스트

  • 워크플로는 빈 파일, 일반 고객 파일, 최악의 파일에서 실행합니다
  • 생성된 PDF는 대상 뷰어, 검증기, 프린터 또는 downstream 애플리케이션에서 엽니다
  • 제품 버전, 프로필 버전, 입력 해시, 출력 경로, 경과 시간, 경고 수를 기록합니다
  • 암호, 인증서, 임시 파일, 고객 데이터는 명확한 보존 규칙에 따라 관리합니다
  • 고객 파일이 새로운 경계 사례를 드러내면 회귀 문서를 추가합니다

제품 문서

PDFium Component

추가 코드 예제

A := Pdf.Annotation[Item.Index];
A.HasColor := True;
A.Color := $0000B0FF;       // amber
A.ColorAlpha := 160;
try
  Pdf.Annotation[Item.Index] := A;
except
  on EPdfError do
  begin
    // The annotation owns a pre-rendered /AP stream; the dictionary
    // color alone cannot change what viewers paint
    Item.AppearanceLocked := True;
    StatusBar.SimpleText := 'Color is fixed by the annotation appearance';
  end;
end;
Pdf.PageNumber := Item.PageNo;
Pdf.DeleteAnnotation(Item.Index);   // raises EPdfError on failure
Bmp := Pdf.RenderPage(0, 0, ViewWidth, ViewHeight, ro0, [reAnnotations]);
try
  PaintPageBitmap(Bmp);
finally
  Bmp.Free;  // RenderPage hands bitmap ownership to the caller
end;
RebuildPageEntries(Item.PageNo);  // indices after Item.Index shifted