Hoe te werken met PDF Graphics in C++

Aspose.PDF FOSS voor C++ bevat een kleine vector-graphics API voor het tekenen van vrije vormen direct op een PDF-pagina — los van de raster-renderingsapparaten van de bibliotheek (BmpDevice, JpegDevice, TiffDevice), die bestaande paginainhoud naar afbeeldingen converteren. Deze gids leidt u door het maken van een Graph container, het toevoegen van Circle, Ellipse en Line vormen, het stijlen van die vormen met GraphInfo, en het plaatsen van de voltooide Graph op een pagina. De bibliotheek wordt aan een project toegevoegd via CMake.

Stapsgewijze handleiding

Stap 1: Installeer het pakket

Voeg de bibliotheek toe als een CMake-subdirectory en link tegen de aspose_pdf_foss target:

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

Verifieer dat de toolchain en headers worden gevonden door een minimaal programma te compileren:

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

int main() {
    Aspose::Pdf::Document doc;
    std::cout << "Linked OK — pages: " << doc.Pages().Count() << "\n";
}

Een succesvolle build die pages: 0 afdrukt bevestigt dat de bibliotheek correct is gelinkt.

Stap 2: Vereiste Klassen importeren

Neem de headers op voor het document, de vormcontainer, de drie concrete vormen en hun stylingtypen:

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/drawing/graph.hpp>
#include <aspose/pdf/drawing/circle.hpp>
#include <aspose/pdf/drawing/ellipse.hpp>
#include <aspose/pdf/drawing/line.hpp>
#include <aspose/pdf/graph_info.hpp>
#include <aspose/pdf/border_info.hpp>
#include <aspose/pdf/color.hpp>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Drawing;

Graph, Shape, Circle, Ellipse en Line bevinden zich in de Aspose::Pdf::Drawing namespace; GraphInfo, BorderInfo en Color bevinden zich rechtstreeks onder Aspose::Pdf.

Stap 3: Maak een grafiek en voeg deze toe aan een pagina

Graph is een container die zichzelf op de pagina positioneert via Left(), Top(), Width() en Height(), en de vormen die erin getekend worden vasthoudt via Shapes(). Eenmaal geconfigureerd, wordt hij op de pagina geplaatst via Page.Paragraphs().Add(), dezelfde collectie die wordt gebruikt voor andere paginainhoud:

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

auto graph = std::make_shared<Graph>();
graph->Left(50.0);
graph->Top(50.0);
graph->Width(400.0);
graph->Height(400.0);

page.Paragraphs().Add(graph);

Stap 4: Teken een cirkel en een ellips

Circle beschrijft zijn geometrie met PosX(), PosY() en Radius(). Ellipse gebruikt in plaats daarvan een begrenzingsvak — Left(), Bottom(), Width() en Height(). Beide worden toegevoegd aan de Graph door ze, als Shape pointers, toe te voegen aan de vector die wordt geretourneerd door Shapes():

auto circle = std::make_unique<Circle>();
circle->PosX(150.0);
circle->PosY(150.0);
circle->Radius(75.0);
graph->Shapes().push_back(std::move(circle));

auto ellipse = std::make_unique<Ellipse>();
ellipse->Left(20.0);
ellipse->Bottom(20.0);
ellipse->Width(120.0);
ellipse->Height(60.0);
graph->Shapes().push_back(std::move(ellipse));

Beide vormen erven CheckBounds(containerWidth, containerHeight) van Shape, die rapporteert of de huidige geometrie van de vorm binnen een container van de opgegeven grootte past:

bool circleFits = circle->CheckBounds(graph->Width(), graph->Height());

Stap 5: Teken een lijn

Line slaat zijn geometrie anders op: PositionArray() bevat een platte std::vector<float> van coördinaten — een x, y-paar per punt — in plaats van benoemde eigenschappen. Een tweepuntsegment heeft vier waarden nodig: start x, start y, eind x, eind y.

auto line = std::make_unique<Line>();
line->PositionArray({0.0f, 0.0f, 400.0f, 400.0f});
graph->Shapes().push_back(std::move(line));

Stap 6: Stijl vormen met GraphInfo en de containerrand

Elke vorm’s lijn en vulling komen van een GraphInfo, gelezen en ingesteld via Shape.GraphInfo() / GraphInfo(value). Het biedt lijndikte (LineWidth(), standaard 1.0f), lijn- en vulkleur (Color(), FillColor()), en een stippellijnpatroon (DashArray(), DashPhase()):

GraphInfo stroke;
stroke.LineWidth(2.0f);
stroke.Color(Color::FromRgb(1.0, 0.0, 0.0));
stroke.FillColor(Color::FromRgb(1.0, 0.9, 0.9));

De Graph container zelf draagt een BorderInfo, ingesteld via Border(), die één GraphInfo per rand groepeert (Left(), Right(), Top(), Bottom()) plus een RoundedBorderRadius() voor het eigen frame van de container:

BorderInfo border{BorderSide::All, 1.5f, Color::Black()};
border.RoundedBorderRadius(6.0);
graph->Border(border);

Stap 7: Document opslaan

doc.Save("graphics.pdf");

Veelvoorkomende problemen en oplossingen

Een vorm die ik heb geconstrueerd verschijnt nooit op de pagina

Het construeren van een Circle, Ellipse of Line op zichzelf heeft geen effect totdat het wordt toegevoegd aan de vector die wordt geretourneerd door de Shapes() van de eigenaar Graph, en die Graph wordt toegevoegd aan een pagina via Page.Paragraphs().Add(). Alle drie stappen — construeren, toevoegen, het Graph aan de pagina toevoegen — zijn vereist.

Vormen worden weergegeven op de verkeerde positie

Graph.Left() en Graph.Top() positioneren de container op de pagina; vormeigenschappen (Circle.PosX()/PosY(), Ellipse.Left()/Bottom(), Line.PositionArray() coördinaten) beschrijven de geometrie binnen die container. Controleer zowel de plaatsing van de container als de eigen coördinaten van de vorm wanneer de output verschoven lijkt.

CheckBounds returns false unexpectedly

CheckBounds(containerWidth, containerHeight) controleert de eigen geometrie van de vorm tegen de meegegeven afmetingen — meestal de Width()/Height() van de eigenaar Graph, en niet de volledige mediabox van de pagina. Het doorgeven van verkeerde afmetingen levert een vals negatief op, zelfs wanneer de vorm daadwerkelijk binnen de Graph zou passen.

A Line verschijnt niet, of verschijnt als een enkel punt

PositionArray() heeft minstens twee (x, y)-paren nodig — vier float waarden — om een zichtbaar segment te beschrijven. Een kortere vector vormt geen lijn.

Confusing Circle with AnnotationType::Circle or CircleAnnotation

De bibliotheek heeft ook een aparte PDF-annotaties API, waarbij AnnotationType::Circle en CircleAnnotation cirkelvormige markup-annotaties voorstellen. De Circle-klasse die in deze gids wordt behandeld is niet gerelateerd — hij bevindt zich in Aspose::Pdf::Drawing en tekent direct in de paginainhoud in plaats van een annotatie-object toe te voegen.

Veelgestelde vragen

Wat is het verschil tussen GraphInfo en BorderInfo?

GraphInfo styleert een enkele lijn — lijndikte, kleur, vulkleur en stippellijnpatroon — en wordt zowel gebruikt op individuele vormen (via Shape.GraphInfo()) als per rand binnen een BorderInfo. BorderInfo groepeert vier GraphInfo waarden (Left(), Right(), Top(), Bottom()) plus een RoundedBorderRadius() om het eigen randframe van een Graph container te beschrijven.

Kan ik een vorm vullen met een effen kleur?

Ja. GraphInfo.FillColor() stelt de vulkleur in die wordt gebruikt wanneer de vorm wordt getekend via zijn eigen Graph.

Slaat Circle een begrenzingsvak op zoals Ellipse dat doet?

Nee. Circle exposeert PosX(), PosY() en Radius(); Ellipse exposeert Left(), Bottom(), Width() en Height(). Ze delen geen gemeenschappelijke geometrie-representatie behalve de abstracte Shape basis en GraphInfo styling.

Kan één Graph meer dan één vorm bevatten?

Ja. Graph.Shapes() retourneert de volledige collectie van Shape objecten die zich binnen die Graph bevinden — cirkels, ellipsen en lijnen kunnen allemaal aan dezelfde container worden toegevoegd.

Is dit hetzelfde als een pagina renderen naar een afbeelding?

Nee. BmpDevice, JpegDevice en TiffDevice rasteren bestaande paginainhoud naar afbeeldingsformaten. Graph, Shape, Circle, Ellipse en Line construeren nieuwe vectorgeometrie rechtstreeks in de PDF-inhoud terwijl een document wordt opgebouwd of bewerkt.