JetsonPDF.Common 1.1.0

JetsonPDF.Common

Shared value types and pure-data utilities used by JetsonPDF.Reader and JetsonPDF.Writer. This is the "no behaviour, just shapes" layer — every type here is either an enum, a record, or a small immutable POCO that describes a PDF concept (page size, viewer preference, destination, page label range, widget action, conformance flag) without doing any I/O.

Most callers never reference this package directly. You add a project / package reference to JetsonPDF.Writer or JetsonPDF.Reader and the types here come along transitively — JetsonPDF.PageSize.Letter is reachable from the Writer namespace because the Writer transitively re-exports it.

using JetsonPDF;
using JetsonPDF.Writer;

var doc = new PdfDocument
{
    Title = "Hello",
    PageLayout = PageLayout.TwoColumnLeft,            // from Common
    PageMode = PageMode.UseOutlines,                   // from Common
    ViewerPreferences = new ViewerPreferences         // from Common
    {
        DisplayDocTitle = true,
        HideToolbar = true,
    },
};

var page = doc.AddPage(PageSize.Letter);              // PageSize from Common
page.DrawText("Hi", new Font(FontFamily.Helvetica, 12), 50, 700);
doc.Save("hi.pdf");

Contents

• Overview
• When you reference it directly
• Page geometry and sizes
• Viewer hints — layout, mode, preferences
• Destinations
• Encryption and permissions
• Conformance and output intents
• Page labels
• Widget actions
• Miscellaneous enums
• Targets
• License

Overview

The root namespace for every public type in this package is JetsonPDF. A handful of annotation-adjacent enums live under JetsonPDF.Annotations (currently just SoundEncoding). There is no JetsonPDF.Common namespace — the assembly name and the root namespace are intentionally different so users write using JetsonPDF; and not using JetsonPDF.Common;.

The assembly has no behavioural surface — nothing here writes bytes, parses streams, or talks to the file system (with the lone exception of IccProfile.FromFile, which reads ICC bytes off disk). Everything is either a constructor, a property, or an enum literal. That makes the package safe to reference from analysers, source generators, build-time validators, and anywhere else you want PDF vocabulary without the writer/reader binaries.

When you reference it directly

You usually don't. The cases where a direct project / NuGet reference makes sense are:

• Writing a host application that dispatches WidgetAction values returned by JetsonPDF.Reader and want the type hierarchy without pulling in the reader.
• Building a separate validator, linter, or static-analysis tool that needs the conformance flags, the permission bits, or the page-label range type.
• Implementing a third-party renderer that reads back DTOs the JetsonPDF reader produces — Destination, OutputIntent, IccProfile etc. are all here.

For the common writer/reader/fluent paths, just reference the higher-level package and let the transitive bring this one in.

Page geometry and sizes

PageSize is an immutable record struct of (Width, Height) in PDF user space units (points; 1 pt = 1/72 inch). PDF coordinates originate at the bottom-left corner.

For custom dimensions, use the record-struct constructor:

var square = new PageSize(720, 720);            // 10 × 10 in
var halfLetter = new PageSize(612, 792 / 2.0);

// Swap width and height for landscape:
var letterLandscape = new PageSize(PageSize.Letter.Height, PageSize.Letter.Width);

Because PageSize is a record struct, equality and with expressions both work:

var custom = PageSize.Letter with { Height = 900 };
bool isLetter = custom == PageSize.Letter;       // false (height changed)

Viewer hints — layout, mode, preferences

Three types control the catalog's /PageLayout, /PageMode, and /ViewerPreferences entries (ISO 32000-2 §12.2 Table 28 + Table 151).

PageLayout

How the viewer arranges pages on screen.

PageMode

What the viewer shows when the document opens.

ViewerPreferences

Every property is nullable. Only non-null entries are emitted, so viewers pick their own defaults for properties you don't set.

var prefs = new ViewerPreferences
{
    DisplayDocTitle = true,
    FitWindow = true,
    Direction = ReadingDirection.LeftToRight,
};

Destinations

Destination describes a navigation target — a page and a viewport state — used by outline items, link annotations, named destinations, and the catalog's /OpenAction (ISO 32000-2 §12.3.2).

// Top of page 3, page width fitted to the window.
var topOfPage3 = Destination.FitH(pageIndex: 2, top: 792);

// Page 0 at 200% zoom, scrolled to (100, 700).
var zoomed = Destination.Xyz(pageIndex: 0, left: 100, top: 700, zoom: 2.0);

Only explicit destinations are exposed here — named destinations are an indirection through the /Dests name tree and resolve to a Destination on the way out.

Encryption and permissions

EncryptionAlgorithm selects the PDF security handler family; Permissions is a [Flags] enum that maps directly to the /P integer in the encryption dictionary (ISO 32000-2 §7.6.4.2 Table 22).

var perms = Permissions.Print | Permissions.FillForms | Permissions.Accessibility;
// Pair with EncryptionOptions (in JetsonPDF.Writer) to actually encrypt.

Conformance and output intents

Conformance is a [Flags] enum — flags compose, so a single document can declare PDF/A and PDF/UA simultaneously.

var conformance = Conformance.PdfA2u | Conformance.PdfUA1;

OutputIntent

Output-intent dictionary (ISO 32000-2 §14.11.5). Required by PDF/A and recommended for prepress.

IccProfile

// From bytes (header inspected to derive component count):
var srgb = IccProfile.FromBytes(File.ReadAllBytes("sRGB.icc"));

// From disk:
var profile = IccProfile.FromFile(@"C:\ICC\sRGB IEC61966-2.1.icc");

// Or supply the component count yourself (1=gray, 3=RGB, 4=CMYK):
var raw = new IccProfile(profileBytes, componentCount: 3);

var intent = new OutputIntent
{
    OutputConditionIdentifier = "sRGB IEC61966-2.1",
    DestProfile = profile,
};

Page labels

PageLabelRange overrides the viewer-facing page-label string for a run of pages — useful when front matter uses roman numerals and the body uses arabic, or when an appendix should display A-1, A-2, …

// Front matter (pages 0..3): i, ii, iii, iv
var front  = new PageLabelRange(startPageIndex: 0, style: PageLabelStyle.LowerRoman);

// Body (pages 4..47): 1, 2, …, 44
var body   = new PageLabelRange(startPageIndex: 4, style: PageLabelStyle.DecimalArabic);

// Appendix (pages 48..): A-1, A-2, …
var apdx   = new PageLabelRange(48, PageLabelStyle.DecimalArabic, prefix: "A-");

// Force a restart at a specific number:
var sectB  = new PageLabelRange(100, PageLabelStyle.DecimalArabic, startNumber: 5);

StartPageIndex is zero-based; StartNumber defaults to 1 and must be ≥ 1. Pages not covered by any range fall through to the viewer's "1, 2, 3" default.

Widget actions

WidgetAction is the discriminated base for every action a widget annotation can dispatch on activation (ISO 32000-2 §12.6). The reader parses the widget's /A entry into one of these subclasses; a viewer shell (the WPF sample, or any custom host) type-tests the value to decide what to do.

WidgetAction action = /* from widget.Action */;

switch (action)
{
    case UriAction uri:
        Process.Start(new ProcessStartInfo(uri.Uri) { UseShellExecute = true });
        break;
    case NamedAction { IsPrint: true }:
        PrintDocument();
        break;
    case ResetFormAction reset:
        ResetForm(reset.FieldNames, exclude: reset.ExcludeFields);
        break;
    case GoToAction go:
        NavigateTo(go.Destination);
        break;
    case JavaScriptAction:
        // ignore — JetsonPDF.Wpf doesn't run scripts
        break;
}

Miscellaneous enums

FillRule (§8.5.3.3)

TextAlignment

Horizontal alignment for Page.DrawTextBlock. Note: the Forms layer has its own FieldAlignment enum for field-content alignment; this TextAlignment is for the writer's text-block drawing helper.

JetsonPDF.Annotations.SoundEncoding (§12.5.6.16 + §13.3)

Sample-data encoding for SoundAction.Encoding and the sound-annotation /E entry.

Targets

• net8.0
• netstandard2.0
• net462

On netstandard2.0 and net462 the project pulls System.Memory 4.5.5 and System.Buffers 4.5.1 to back the Span<T> / Memory<T> surface that net8.0 provides in the BCL.

License

MIT.