PdfSharpCore Documentation

When drawing complex shapes (like clock hands), use coordinate transformations to simplify math:

• TranslateTransform: Moves the origin of the coordinate system (e.g., to the center of the page).
• ScaleTransform: Scales the coordinate system.
• RotateTransform: Rotates the coordinate system around the current origin.
• State Management: Always use gfx.Save() before applying transformations and gfx.Restore(gs) after drawing to ensure subsequent drawing operations are not affected by the previous transformations.

void DrawHourHand(XGraphics gfx, XPen pen, XBrush brush)
{
    XGraphicsState gs = gfx.Save();
    gfx.RotateTransform(360 * Time.Hour / 12 + 30 * Time.Minute / 60);
    gfx.DrawPolygon(
        pen, brush,
        new XPoint[]{new XPoint(0,  150), new XPoint(100, 0), 
        new XPoint(0, -600), new XPoint(-100, 0)},
        XFillMode.Winding);
    gfx.Restore(gs);
}

When specialized PdfSharpCore classes do not support a specific PDF feature, you can manipulate the underlying PDF structure directly using low-level objects like PdfDictionary, PdfArray, PdfName, and PdfReference.

This approach requires knowledge of the PDF specification (e.g., Adobe's PDF Reference). By using these objects, you can implement features like custom actions, advanced metadata, or specific document behaviors that are not yet part of the high-level API.

Key concepts for direct object manipulation:

• Indirect References: Instead of adding a high-level object (like a PdfPage) directly to a collection, use PdfInternals.GetReference(object) to create a PdfReference. This ensures the object is treated as an indirect object in the PDF structure.
• Object Table: Use document.Internals.AddObject(object) to add a manually constructed object to the document's object table.
• Catalog Access: Use document.Internals.Catalog to access the document's root dictionary to add top-level keys like /OpenAction.

// Example: Adding an OpenAction to a document
PdfDocument document = PdfReader.Open(filename);

// 1. Create a dictionary for the action
PdfDictionary dict = new PdfDictionary(document);
dict.Elements["/S"] = new PdfName("/GoTo");

// 2. Create an array for the destination
PdfArray array = new PdfArray(document);
dict.Elements["/D"] = array;

// 3. Add elements to the array (e.g., a reference to page 3, a fit command, and a coordinate)
PdfReference iref = PdfInternals.GetReference(document.Pages[2]);
array.Elements.Add(iref);
array.Elements.Add(new PdfName("/FitV"));
array.Elements.Add(new PdfInteger(-32768));

// 4. Register the dictionary in the document's object table
document.Internals.AddObject(dict);

// 5. Link the action to the document catalog
document.Internals.Catalog.Elements["/OpenAction"] = PdfInternals.GetReference(dict);

Because PdfSharpCore is a low-level drawing library, it does not handle automatic page breaks. You can implement a LayoutHelper pattern to manage vertical positioning and trigger AddPage() calls when the current position exceeds a defined bottom margin.

A LayoutHelper should track:

• The PdfDocument instance.
• The _currentPosition (vertical Y coordinate).
• The _topPosition and _bottomMargin for the current page.
• The current XGraphics and PdfPage objects.

When requesting a line position via a method like GetLinePosition(requestedHeight), the helper checks if _currentPosition + requestedHeight exceeds the _bottomMargin. If it does, it calls a CreatePage() method to reset the position and refresh the graphics context.

public class LayoutHelper
{
    private readonly PdfDocument _document;
    private readonly XUnit _topPosition;
    private readonly XUnit _bottomMargin;
    private XUnit _currentPosition;
    
    public LayoutHelper(PdfDocument document, XUnit topPosition, XUnit bottomMargin)
    {
        _document = document;
        _topPosition = topPosition;
        _bottomMargin = bottomMargin;
        // Set a value outside the page - a new page will be created on the first request.
        _currentPosition = bottomMargin + 10000;
    }
    
    public XUnit GetLinePosition(XUnit requestedHeight, XUnit requiredHeight = -1f)
    {
        XUnit required = requiredHeight == -1f ? requestedHeight : requiredHeight;
        if (_currentPosition + required > _bottomMargin)
            CreatePage();
        XUnit result = _currentPosition;
        _currentPosition += requestedHeight;
        return result;
    }
    
    public XGraphics Gfx { get; private set; }
    public PdfPage Page { get; private set; }
    
    void CreatePage()
    {
        Page = _document.AddPage();
        Page.Size = PageSize.A4;
        Gfx = XGraphics.FromPdfPage(Page);
        _currentPosition = _topPosition;
    }
}