소개

PDF 주석은 페이지 내용 위에 겹쳐지는 다양한 인터랙티브 및 시각 요소들을 포괄합니다: 붙어 있는 텍스트 메모, 하이퍼링크, 강조되거나 취소선이 그어진 텍스트, 기하학적 도형, 잉크 스트로크, 파일 첨부 및 승인 스탬프. Aspose.PDF FOSS for C++는 이들 각각을 Annotation의 구체적인 하위 클래스으로 나타내므로, 페이지의 주석을 순회하는 코드는 기본 클래스에 대해 일반적으로 작업하면서도 필요할 때 TextAnnotation의 Icon()이나 LinkAnnotation의 Action()과 같은 하위 타입 전용 멤버에 접근할 수 있습니다.

라이브러리의 Annotations::AnnotationType 열거형은 인식하는 하위 유형들을 나열합니다: Text, Link, FreeText, Line, Square, Circle, Polygon, PolyLine, Highlight, Underline, Squiggly, StrikeOut, Stamp, Caret, Ink, Popup, FileAttachment, Sound, Movie, Widget, Screen, PrinterMark, Watermark, Redaction, RichMedia 등 여러 가지. 각 값은 구체적인 클래스에 매핑됩니다 — 도형 마크업을 위한 CircleAnnotation, SquareAnnotation, PolygonAnnotation, PolylineAnnotation, LineAnnotation; 자유 형식 텍스트와 그린 스트로크를 위한 FreeTextAnnotation 및 InkAnnotation; 임베디드 콘텐츠를 위한 FileAttachmentAnnotation, SoundAnnotation, MovieAnnotation, ScreenAnnotation, RichMediaAnnotation; 그리고 AcroForm 필드 외관을 위한 WidgetAnnotation.

이 게시물은 Annotation 및 AnnotationCollection 기본 API을 다루며, 텍스트 메모와 링크 추가, 기존 문서를 로드할 때 주석 유형 감지, 마크업 메타데이터 및 스탬프 읽기 또는 업데이트 방법을 설명합니다. Aspose.PDF FOSS for C++는 표준 라이브러리 외에 런타임 종속성이 없는 C++20 라이브러리이며, 헤더는 aspose/pdf/annotations/ 디렉터리에서 직접 포함되고 라이브러리는 CMake 타깃으로 빌드됩니다.

포함 내용

Annotation 및 AnnotationCollection

Annotation은 모든 주석 하위 유형의 기본 클래스입니다. 주석의 경계 사각형을 위한 Rect() / Rect(value), 연관된 텍스트를 위한 Contents(), Name(), Color(), Flags()(AnnotationFlags 비트마스크 — Print, Hidden, Invisible, NoZoom, ReadOnly 등), Border(), Width() / Height(), AnnotationType(), PageIndex()와 같은 공통 속성을 제공합니다. AnnotationCollection은 단일 페이지의 주석을 보관하며 Page.Annotations()를 통해 접근합니다.

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/annotation_collection.hpp>
#include <iostream>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

Document doc("reviewed.pdf");
AnnotationCollection& annots = doc.Pages()[1].Annotations();

std::cout << "Annotation count: " << annots.Count() << "\n";
for (int i = 0; i < annots.Count(); ++i) {
    Annotation& a = annots[i];
    std::cout << "  " << a.Name() << ": " << a.Contents() << "\n";
}

AnnotationCollection은 또한 Add(annotation), Add(annotation, considerRotation), Delete(index), Delete(annotation), Clear(), Remove(annotation), Contains(annotation), IsReadOnly() 메서드를 제공합니다.

TextAnnotation을 사용한 텍스트 노트

TextAnnotation은 익숙한 스티키 노트 주석을 나타냅니다. 기본 Annotation 멤버 외에, 메모가 펼쳐져 표시될지를 제어하는 Open() / Open(value)와 아이콘 글리프를 선택하기 위한 Icon() / Icon(value)(Note, Comment, Key, Help, Check와 같은 TextIcon 값)를 추가합니다.

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/text_annotation.hpp>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

Document doc("input.pdf");

TextAnnotation note{doc};
note.Rect(Rectangle{100.0, 700.0, 200.0, 720.0, false});
note.Contents("Reviewed by QA");
note.Icon(TextIcon::Comment);
note.Open(true);

doc.Pages()[1].Annotations().Add(note);
doc.Save("annotated.pdf");

LinkAnnotation을 사용한 링크 및 동작

LinkAnnotation은 페이지에 클릭 가능한 영역을 부착합니다. 이는 소유 Page와 Rectangle으로 구성되며, 동작은 Action(value) — PdfAction 서브클래스, NamedAction(예: PredefinedAction::LastPage와 같은 사전 정의된 탐색), GoToAction, GoToURIAction, JavascriptAction 등 — 로 설정됩니다. Destination()은 링크의 IAppointment 대상을 읽고, Highlighting() / Highlighting(value)는 링크가 활성화될 때 적용되는 HighlightingMode(None, Invert, Outline, Push, Toggle)를 설정합니다.

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/link_annotation.hpp>
#include <aspose/pdf/annotations/named_action.hpp>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

Document doc;
Page page = doc.Pages().Add();

LinkAnnotation link{page, Rectangle{0.0, 0.0, 100.0, 20.0, false}};
link.Action(NamedAction{PredefinedAction::LastPage});
link.Highlighting(HighlightingMode::Push);

page.Annotations().Add(link);

로드 시 주석 유형 감지

문서가 열릴 때, 기존 주석들은 각 페이지의 AnnotationCollection에 이미 채워져 있으며, AnnotationType()은 각 항목이 나타내는 구체적인 하위 유형을 식별합니다. 이를 통해 호출 코드는 사전에 PDF에 어떤 주석 유형이 포함되어 있는지 알지 못해도 열거값을 기준으로 분기할 수 있습니다.

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/annotation_type.hpp>
#include <iostream>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

Document doc("mixed-annotations.pdf");
auto& annots = doc.Pages()[1].Annotations();

for (int i = 0; i < annots.Count(); ++i) {
    switch (annots[i].AnnotationType()) {
        case AnnotationType::Text:      std::cout << "Text note\n"; break;
        case AnnotationType::Link:      std::cout << "Link\n"; break;
        case AnnotationType::Circle:    std::cout << "Circle shape\n"; break;
        case AnnotationType::Square:    std::cout << "Square shape\n"; break;
        case AnnotationType::Highlight: std::cout << "Highlight\n"; break;
        case AnnotationType::Stamp:     std::cout << "Stamp\n"; break;
        default: break;
    }
}

마크업 주석 메타데이터

MarkupAnnotation은 검토자 메타데이터를 포함하는 주석의 기본 클래스입니다: Title()(작성자), Subject(), 서식 있는 댓글 텍스트를 위한 RichText(), 페이지 내용과 혼합하기 위한 Opacity() 등이 있습니다. InReplyTo()와 Popup()은 마크업 주석을 해당 댓글 스레드와 연결하고, ClearState() / SetReviewState(state, userName)은 검토 상태를 관리합니다. HighlightAnnotation, UnderlineAnnotation, StrikeOutAnnotation, SquigglyAnnotation은 텍스트 위에 배치되는 마크업 하위 유형이며, 이들의 공통 기반인 TextMarkupAnnotation은 커버되는 사각형 영역을 정의하는 QuadPoints()와 아래 텍스트를 읽어오는 GetMarkedText()를 추가합니다.

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/markup_annotation.hpp>

using namespace Aspose::Pdf::Annotations;

for (int i = 0; i < annots.Count(); ++i) {
    if (auto* markup = dynamic_cast<MarkupAnnotation*>(&annots[i])) {
        markup->Title("QA Reviewer");
        markup->Subject("Layout issue");
        markup->Opacity(0.6);
    }
}

StampAnnotation으로 스탬프 주석

StampAnnotation은 페이지에 사전 정의된 스탬프 또는 사용자 정의 스탬프를 배치합니다. Icon() / Icon(value)는 StampIcon 값—Approved, Draft, Confidential, Final, Expired, NotApproved, ForComment, TopSecret 등—을 선택하고, Image() / Image(value)는 기본 아이콘 대신 사용자 정의 스탬프 외관을 위한 원시 이미지 바이트를 제공한다.

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/stamp_annotation.hpp>

using namespace Aspose::Pdf::Annotations;

for (int i = 0; i < annots.Count(); ++i) {
    if (auto* stamp = dynamic_cast<StampAnnotation*>(&annots[i])) {
        stamp->Icon(StampIcon::Approved);
    }
}

빠른 시작

라이브러리를 CMake 하위 디렉터리로 추가하고 aspose_pdf_foss 타깃에 링크합니다:

add_subdirectory(aspose.pdf-foss-for-cpp)
target_link_libraries(your_app PRIVATE aspose_pdf_foss)

문서를 열고, 텍스트 노트를 추가한 뒤, 주석 개수를 다시 읽어옵니다:

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/text_annotation.hpp>
#include <iostream>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

int main() {
    Document doc("input.pdf");

    TextAnnotation note{doc};
    note.Rect(Rectangle{100.0, 700.0, 200.0, 720.0, false});
    note.Contents("Reviewed by QA");
    note.Icon(TextIcon::Comment);

    doc.Pages()[1].Annotations().Add(note);
    doc.Save("annotated.pdf");

    std::cout << "Annotations on page 1: "
              << doc.Pages()[1].Annotations().Count() << "\n";
}

지원되는 형식

포맷확장읽기쓰기
BMP.bmp—✓
JPEG.jpg—✓
TIFF.tiff—✓
Text.txt—✓
SVG.svg✓—

포맷 지원은 문서 수준에서 페이지 렌더링 및 로드 옵션에 적용됩니다; 이 항목들은 주석별 직렬화가 아니라 확인된 내보내기(BmpDevice, JpegDevice, TiffDevice, TextDevice) 및 가져오기(SvgLoadOptions) 경로를 반영합니다.

오픈 소스 및 라이선스

Aspose.PDF FOSS for C++는 MIT 라이선스 하에 배포됩니다. 소스 코드는 https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-Cpp에서 확인할 수 있으며, 이 라이브러리는 상업용 및 오픈소스 프로젝트에서 라이선스 비용 없이 사용할 수 있습니다.

시작하기

관련 자료