HotPDF가 있는 Delphi의 PDF 주석: 유형 및 Rects

주석은 페이지 내용이 아닙니다. TextOut을 호출하거나 사각형을 그리면 마크가 페이지 내용 스트림의 일부가 되어 렌더러가 그리는 바이트로 구워집니다. 주석은 별도의 딕셔너리로 /Annots 배열을 통해 페이지에서 분리되어 있으며 고유한 사각형, 고유한 모양 및 고유한 수명 주기를 갖습니다. 리더는 기본 페이지의 단일 글리프를 건드리지 않고 주석을 열거나, 이동하거나, 숨기거나, 제거할 수 있습니다. 그 분리가 주석이 존재하는 전체 이유이며, 사람들을 처음 놀라게 하는 두 가지, 주석이 안착되는 위치와 특정 뷰어가 이를 확보하면 어떻게 보이는지에 대한 소스이기도 합니다

HotPDF는 페이지 객체에 대한 AddXxxAnnotation 호출 제품군을 통해 ISO 32000 주석 하위 유형을 노출합니다. 이들은 모두 동일한 모양을 공유합니다. 페이지의 PDF 사용자 공간에 주석을 고정하는 사각형, 일부 페이로드(텍스트, 스탬프 이름, 포인트 쌍) 및 색상입니다. 사각형을 올바르게 가져오면 대부분의 작업이 완료됩니다. 나머지는 자체 모양을 가지고 있는 하위 유형과 뷰어에 기대어 그리는 하위 유형을 아는 것입니다

사각형은 텍스트가 아니라 주석입니다

모든 주석 호출은 TRect를 취하며, 그 사각형은 TextOut에 전달하는 좌표와 다른 것을 의미합니다. 텍스트 메모의 경우 메모 아이콘이 있고 클릭 시 주석을 여는 팝업이 나타나는 클릭 가능한 핫스팟입니다. 사각형이나 자유 텍스트 상자의 경우 마크업이 보이는 범위입니다. 스탬프의 경우 스탬프 아트가 크기 조정되는 상자입니다. 이 수치는 PDF 사용자 공간의 포인트로, 페이지의 왼쪽 하단에서부터 시작하여 Y가 위로 커지도록 측정된 것으로, 나머지 HotPDF에서 사용하는 것과 동일한 규칙입니다

텍스트 메모는 가장 가벼운 하위 유형입니다. 본문 텍스트, 아이콘용 사각형, 기본적으로 열릴지 여부에 대한 플래그, 아이콘 이름, 색상을 제공합니다

Pdf.CurrentPage.AddTextAnnotation(
  'Reviewer: confirm the totals on this line before sign-off.',
  Rect(120, 700, 140, 720),   // icon hotspot, ~20pt square
  False,                      // closed until the reader clicks it
  taComment,                  // bubble icon
  clBlue);

여기 사각형은 의도적으로 한 변이 약 20포인트 정도로 작습니다. 왜냐하면 텍스트 메모는 누군가가 그것을 클릭할 때까지는 단지 아이콘에 불과하기 때문입니다. 사각형을 크게 만들면 큰 메모가 나타나지 않습니다. 한 모서리에 아이콘이 핀으로 고정된 과도하게 큰 클릭 타겟을 얻게 됩니다. Open 플래그는 문서가 로드될 때 팝업을 표시할지 여부를 제어합니다. 한 줌의 메모를 True로 설정하면 서로 겹치거나 콘텐츠 상단에 쌓이기 때문에 독자가 즉시 보기를 원하는 하나의 메모에 해당 플래그를 예약하십시오

아이콘 이름은 THPDFTextAnnotationType에서 가져오는데, 표준 메모 아이콘(taComment, taKey, taNote, taHelp, taParagraph, taNewParagraph, 및 taInsert)에 맵핑됩니다. 아이콘은 유형이 바꾸는 유일한 것입니다. 동작을 바꾸지 않으며, 모든 뷰어가 7개 모두를 그리는 것은 아니라는 점을 알아둘 가치가 있습니다. 구형 및 신형 리더 전반에 걸친 안전한 뷰어는 taComment, taNote 및 taHelp입니다

자유 텍스트는 페이지에 쓰지만 주석으로 유지됩니다

자유 텍스트 주석은 클릭하지 않고도 텍스트가 표시되고 캡션처럼 사각형 안에 앉아 있기 때문에 콘텐츠처럼 보입니다. 모든 분리 가능성을 암시하는 여전히 주석이므로, 이는 누군가가 나중에 제거할 수 있어야 하는 검토 스탬프나 초안 레이블에 대해 정확히 원하는 것입니다. 서명은 아이콘과 열기 플래그를 정렬 값으로 맞바꿉니다

Pdf.CurrentPage.AddFreeTextAnnotation(
  'DRAFT - not for distribution',
  Rect(200, 210, 400, 235),   // the box the text is laid into
  ftCenter,                   // ftLeftJust / ftCenter / ftRightJust
  clRed);

여기 사각형은 텍스트 메모의 경우보다 더 중요합니다. 텍스트가 그 내부로 래핑하고 정렬하기 때문입니다. 상자의 크기를 너무 짧게 맞추면 하단 모서리에서 텍스트가 잘립니다. 너무 좁으면 의도하지 않은 위치에서 줄 바꿈됩니다. 정렬은 THPDFFreeTextAnnotationJust에서 나오며 세 가지 값만 가집니다. 자유 텍스트는 마크업 주석이기 때문에 파일을 편집기에서 여는 리더는 자유 텍스트를 선택하고 이동하거나 유닛으로 삭제할 수 있습니다. 이는 자유 텍스트에 도달할지 아니면 단순히 TextOut을 사용하여 단어를 그릴지 결정하는 차이점입니다. 레이블이 영구적이어야 한다면 그리십시오. 레이블이 사설이고 떨어져 나갈 것을 의미한다면 주석으로 만드십시오

사물을 가리키기 위한 기하학적 및 선 마크업

사각형, 원 및 선은 단어로 설명하는 대신 영역을 가리키는 데 사용하는 마크업입니다. AddCircleSquareAnnotation은 csCircle 또는 csSquare인 THPDFCSAnnotationType을 통해 두 개의 상자 모양을 덮으며, 모양의 경계를 나타내는 사각형이 있습니다

// A box drawn around a figure that needs attention
Pdf.CurrentPage.AddCircleSquareAnnotation(
  'Check this region against the source data',
  Rect(50, 300, 120, 360),
  csSquare,
  clGreen);

// A line, given two points rather than a rectangle
var
  StartPt, EndPt: THPDFCurrPoint;
begin
  StartPt.X := 130; StartPt.Y := 360;
  EndPt.X   := 250; EndPt.Y   := 320;
  Pdf.CurrentPage.AddLineAnnotation(
    'Points from the note to the figure',
    StartPt, EndPt,
    clBlue);
end;

선 주석은 직사각형 패턴을 깬다는 점에 유의하십시오. 선은 경계 상자가 아닌 끝점으로 정의되기 때문에 시작과 끝인 두 개의 THPDFCurrPoint 레코드를 갖습니다. 색상은 선을 설정합니다. 화살표가 필요한 경우 HotPDF는 선 끝 스타일을 허용하는 AddLineAnnotation 오버로드를 가지고 있지만, 일반 3 인자 형식은 대개 콜아웃이 원하는 벌거벗은 선을 그립니다

텍스트 마크업 하위 유형은 이미 레이아웃한 영역에서 작동합니다. AddHighlightAnnotation은 사각형, 선택적 콘텐츠, 기본적으로 노란색인 색상을 취하고 형광펜처럼 영역에 색을 칠합니다. 실제 텍스트 위에 위치하도록 설계되었으므로, 사각형은 여러분이 그린 단어의 경계와 일치해야 합니다. 즉, 추측하는 대신 TextOut에 전달한 것과 같은 좌표에서 일반적으로 계산해야 함을 의미합니다

스탬프는 뷰어에게 렌더링을 의존합니다

스탬프 주석은 독자에 따라 다르게 보일 가능성이 가장 높은 주석이며 그 이유를 이해할 가치가 있습니다. AddStampAnnotation은 THPDFStampAnnotationType을 통해 표준 스탬프의 이름을 지정하며, satApproved, satConfidential, satFinal, satDraft, 및 satForComment와 같은 값이 있습니다

Pdf.CurrentPage.AddStampAnnotation(
  'Approved for release on review',
  Rect(50, 400, 200, 440),
  satApproved,
  clGreen);

스탬프 이름은 요청입니다. PDF는 표준 스탬프 이름의 집합을 정의하지만 그 이면의 아트워크는 정의하지 않습니다. 그래서 각 뷰어는 "APPROVED" 또는 "CONFIDENTIAL"의 자체 렌더링을 내보내며, 인식하지 못하는 이름의 경우 몇몇은 전혀 렌더링하지 않습니다. 사각형은 아트를 크기 조절하는 상자를 통제하고, 색상은 뷰어가 준수할 수도 있고 아닐 수도 있는 힌트입니다. 스탬프가 어느 곳에서나 동일해 보여야 한다면 신뢰할 수 있는 경로는 전혀 표준 스탬프가 아닙니다. TextOut 및 그리기 호출로 스스로 표시를 그리거나 여러분이 제어하는 외형인 자유 텍스트 주석으로 놓으십시오. 뷰어에 익숙한 모습이 필요하고 그러한 변형을 허용할 수 있을 때 표준 스탬프에 도달하십시오

파일 첨부는 동일한 사각형과 더불어 페이로드 형태를 따릅니다. AddFileAttachmentAnnotation은 설명, 포함시킬 파일의 경로, 종이 클립 아이콘용 사각형, 색상을 받습니다. 파일은 PDF 내부를 타고 아이콘은 독자가 이를 추출하는 데 사용하는 핸들입니다

주석이 AcroForm 필드와 어떻게 다른가

가장 많은 시간을 소비하는 혼동은 주석을 양식 필드인 것처럼 다루는 것입니다. 둘 다 /Annots를 통해 페이지에 첨부되며 양식 필드는 사실 특수 주석 하위 유형(위젯)이기 때문에 관련이 있어 보입니다. 이들은 서로 바꿔 사용할 수 없습니다. 양식 필드는 값을 보유하고, 이름을 가지며, 탭 순서에 참여하고, 제출하거나, 재설정하거나 스크립팅될 수 있습니다. 여러분은 이 페이지의 주석 호출이 아니라 AddTextField, AddCheckBox, AddPushButton 호출로 그것들을 생성합니다. 마크업 주석은 코멘트나 모양을 보유하고 제출할 값이 없으며 입력 수집이 필요한 순간 틀린 도구입니다

실제 테스트는 간단합니다. 사용자가 입력하고, 선택하고, 클릭해서 문서를 기억하게 해야 하는 경우 AcroForm 필드가 필요합니다. 메모를 남기고, 영역을 표시하고, 파일과 함께 전달되지만 데이터가 아닌 상태를 스탬핑하는 경우 주석이 필요합니다. 그것들을 섞으면 바르게 보이고 틀리게 동작하는 문서를 생성합니다. 아무도 채울 수 없는 "필드"이거나 폼이 재설정되면 코멘트가 사라집니다. 필드 유형, 유효성 검사, 제출 조치 등이 있는 대화형 측면은 고유한 주제이며 AcroForm 필드 및 조치 연습에서 다루고 있습니다

페이지를 함께 놓기

조각들은 나머지 HotPDF가 작성하는 대로 구성합니다. 문서 속성을 설정하고, BeginDoc를 호출하고, 텍스트 및 그래픽스 호출이 있는 필요한 모든 페이지 콘텐츠를 그린 다음, 그 위에 주석을 추가하고 EndDoc로 닫습니다. 주석은 CurrentPage에 첨부되므로 AddPage 후에 새 페이지에 주석이 안착하고 페이지 휴식 후에 추가하면 페이지 1을 의미한 메모가 페이지 2에 조용히 나타납니다

Pdf := THotPDF.Create(nil);
try
  Pdf.FileName := 'annotated.pdf';
  Pdf.Compression := cmFlateDecode;
  Pdf.FontEmbedding := True;
  Pdf.BeginDoc;

  Pdf.CurrentPage.SetFont('Arial', [], 11);
  Pdf.CurrentPage.TextOut(50, 740, 0, 'Quarterly figures, draft for review');

  Pdf.CurrentPage.AddTextAnnotation(
    'Confirm the totals before sign-off.',
    Rect(50, 720, 70, 740), False, taComment, clBlue);
  Pdf.CurrentPage.AddFreeTextAnnotation(
    'DRAFT', Rect(450, 720, 540, 745), ftCenter, clRed);
  Pdf.CurrentPage.AddStampAnnotation(
    'For comment', Rect(50, 660, 180, 695), satForComment, clGreen);

  Pdf.EndDoc;
finally
  Pdf.Free;
end;

출력이 틀린 것으로 보일 때 가치있는 한 가지 마지막 반사 행동: 코드가 손상되었다고 판단하기 전에 둘 이상의 뷰어에서 파일을 여십시오. 스탬프와 흔하지 않은 메모 아이콘은 일반적인 범인이며 주석은 칠해진 픽셀이 아니라 독자에 대한 요청이기 때문에, Acrobat과 가벼운 뷰어 간의 차이점은 종종 여러분의 호출에 버그가 있는 것이 아니라 설계된 대로 작동하는 사양입니다

여기에 표시된 주석 호출은 Delphi 및 C++Builder용 HotPDF Component의 일부입니다