ZingPDF logo

API Reference

Main public API

How to use this page

Use the developer guide for workflows and examples, then drop into this reference for canonical signatures, XML-backed member descriptions, and save-time behavior details.

Interface

IPdf

ZingPDF

Interface 
public interface IPdf

Represents a loaded or newly created PDF document.

Properties

Property

Data

Stream Data { get; }

Gets the underlying source stream for the PDF.

Property

Objects

IPdfObjectCollection Objects { get; }

Gets the low-level PDF object collection for advanced scenarios.

Methods

Method

AuthenticateAsync

Task AuthenticateAsync(string password);

Unlocks the PDF for reading and/or writing. The password can be a user password or an owner password.

Method

GetAllPagesAsync

Task<IList<IndirectObject>> GetAllPagesAsync();

Gets every page indirect object in page order.

Method

GetPageAsync

Task<Page> GetPageAsync(int pageNumber);

Gets a page by its 1-based page number.

Method

GetPageCountAsync

Task<int> GetPageCountAsync();

Gets the number of pages in the document.

Method

GetFormAsync

Task<Form?> GetFormAsync();

Gets the document form wrapper if the PDF contains an AcroForm.

Method

GetMetadataAsync

Task<PdfMetadata> GetMetadataAsync();

Gets the editable document metadata backed by the trailer Info dictionary.

Remarks

Changes are persisted when SaveAsync is called. Saving also stamps the metadata producer as ZingPDF and refreshes the modification date.

Method

AppendPageAsync

Task<Page> AppendPageAsync(Action<PageDictionary.PageCreationOptions>? configureOptions = null);

Appends a new page to the end of the document.

Method

InsertPageAsync

Task<Page> InsertPageAsync(int pageNumber, Action<PageDictionary.PageCreationOptions>? configureOptions = null);

Inserts a new page before the specified 1-based page number.

Method

DeletePageAsync

Task DeletePageAsync(int pageNumber);

Deletes a page by its 1-based page number.

Method

SetRotationAsync

Task SetRotationAsync(Rotation rotation);

Sets the rotation for every page in the document.

Method

ExtractTextAsync

Task<IEnumerable<ExtractedText>> ExtractTextAsync();

Extracts text from the document.

Method

AddWatermarkAsync

Task AddWatermarkAsync(string text);

Adds a simple text watermark to each page.

Method

Compress

void Compress(int dpi, int quality);

Compresses eligible streams in the document.

Parameters

  • dpi Reserved for future image downsampling behavior. Must be greater than zero.
  • quality JPEG recompression quality from 1 to 100.

Method

DecompressAsync

Task DecompressAsync();

Removes compression filters from all objects in the PDF.

Remarks

This applies an incremental update to the PDF with all objects decompressed. This can add significant size to the PDF. Typically, this is used to make the source code of a PDF more readable.

Method

EncryptAsync

Task EncryptAsync(string userPassword, string? ownerPassword = null);

Saves the PDF using standard password protection.

Remarks

If the source PDF is already encrypted, authenticate it first so the document can be rewritten. The current implementation writes Standard security handler encryption using RC4 (V=2, R=3).

Method

DecryptAsync

Task DecryptAsync(string password);

Authenticates with the supplied password and saves the PDF without encryption.

Method

AppendPdfAsync

Task AppendPdfAsync(Stream stream);

Appends the pages from another PDF stream to the current document.

Method

SaveAsync

Task SaveAsync(Stream outputStream);

Saves the document by writing an incremental update.

Remarks

When saving to a different stream, the output stream must be empty, writable, and seekable.

Class

PdfMetadata

ZingPDF

Class 
public sealed class PdfMetadata

Represents editable document metadata backed by the trailer Info dictionary.

Properties

Property

Title

public string? Title

Gets or sets the document title.

Property

Author

public string? Author

Gets or sets the document author.

Property

Subject

public string? Subject

Gets or sets the document subject.

Property

Keywords

public string? Keywords

Gets or sets document keywords.

Property

Creator

public string? Creator

Gets or sets the application or person that originally created the document.

Property

Producer

public string? Producer { get; private set; }

Gets the producer value that will be written by ZingPDF on save.

Remarks

This value is managed by ZingPDF and is refreshed during SaveAsync(...).

Property

CreationDate

public DateTimeOffset? CreationDate

Gets or sets the original document creation date.

Remarks

Existing documents may store this as either a PDF date object or a raw string; both are supported when loading.

Property

ModifiedDate

public DateTimeOffset? ModifiedDate { get; private set; }

Gets the modification date that will be written on save.

Remarks

This value is managed by ZingPDF and is refreshed during SaveAsync(...).

Class

Page

ZingPDF.Elements

Class 
public class Page

Represents a single page in a PDF document.

Properties

Property

IndirectObject

public IndirectObject IndirectObject { get; }

Gets the underlying indirect object for the page.

Property

Dictionary

public PageDictionary Dictionary { get; }

Gets the page dictionary for the page.

Methods

Method

AddTextAsync

public Task AddTextAsync(TextObject text)

Adds a text object to the page contents.

Method

AddImageAsync

public Task AddImageAsync(Image image)

Adds an image to the page contents.

Method

RotateAsync

public Task RotateAsync(Rotation rotation)

Applies an additional rotation to the page.

Class

Form

ZingPDF.Elements.Forms

Class 
public class Form

Represents an AcroForm attached to a PDF document.

Remarks

Call GetFieldsAsync to discover fields, then pattern match the returned values to the public field types such as TextFormField, ChoiceFormField, ButtonOptionsFormField, or SignatureFormField.

Methods

Method

GetFieldsAsync

public Task<IEnumerable<IFormField>> GetFieldsAsync()

Enumerates the terminal form fields in the document.

Remarks

Field names are returned as fully qualified names using dot notation for nested fields.

Interface

IFormField

ZingPDF.Elements.Forms

Interface 
public interface IFormField

Common metadata exposed for every discovered AcroForm field.

Properties

Property

Description

string? Description { get; }

Gets the user-facing description or tooltip for the field, when present.

Property

Name

string Name { get; }

Gets the fully qualified field name.

Property

Properties

FieldProperties Properties { get; }

Gets the decoded field flags.

Methods

Method

GetFieldDimensionsAsync

Task<Size> GetFieldDimensionsAsync();

Gets the field rectangle size.

Class

TextFormField

ZingPDF.Elements.Forms.FieldTypes.Text

Class 
public class TextFormField : FormField<PdfString>

Represents a text form field.

Methods

Method

GetValueAsync

public Task<string?> GetValueAsync()

Gets the current field value as decoded text.

Method

SetValueAsync

public Task SetValueAsync(string? value)

Sets the field value and regenerates the field appearance.

Parameters

  • value The new text value, or null to clear the field.

Method

GetAPAsync

public Task<ContentStream?> GetAPAsync()

Gets the field appearance stream, primarily for diagnostics and testing.

Method

ClearAsync

public Task ClearAsync()

Clears the field value and wipes its appearance stream.

Class

ChoiceFormField

ZingPDF.Elements.Forms.FieldTypes.Choice

Class 
public abstract class ChoiceFormField( IndirectObject fieldIndirectObject, string name, string? description, FieldProperties properties, Form parent, IPdf pdf ) : FormField<IPdfObject>(fieldIndirectObject, name, description, properties, parent, pdf)

Base class for choice fields such as combo boxes and list boxes.

Methods

Method

GetOptionsAsync

public Task<IReadOnlyList<ChoiceItem>> GetOptionsAsync()

Gets the available options for the field, including their current selected state.

Class

ChoiceItem

ZingPDF.Elements.Forms.FieldTypes.Choice

Class 
public class ChoiceItem

Represents a selectable option in a choice field.

Properties

Property

Text

public PdfString Text { get; set; }

Gets or sets the display text for the option.

Property

Value

public PdfString Value { get; set; }

Gets or sets the stored option value written to the field when this item is selected.

Property

Selected

public bool Selected { get; }

Gets whether the option is currently selected.

Methods

Method

SelectAsync

public Task SelectAsync();

Selects this option.

Method

DeselectAsync

public Task DeselectAsync();

Deselects this option.

Class

ButtonOptionsFormField

ZingPDF.Elements.Forms.FieldTypes.Button

Class 
public abstract class ButtonOptionsFormField : FormField<Name>

Base class for checkbox and radio-button fields.

Remarks

Call GetOptionsAsync to inspect the available choices and then use SelectAsync or DeselectAsync to change selection state.

Methods

Method

GetOptionsAsync

public Task<IReadOnlyList<SelectableOption>> GetOptionsAsync()

Gets the selectable options for the field.

Class

CheckboxFormField

ZingPDF.Elements.Forms.FieldTypes.Button

Class 
public class CheckboxFormField : ButtonOptionsFormField

Represents a checkbox field whose options can be toggled on or off.

Class

RadioButtonFormField

ZingPDF.Elements.Forms.FieldTypes.Button

Class 
public class RadioButtonFormField : ButtonOptionsFormField

Represents a radio-button field where selecting one option usually clears the others in the same group.

Class

PushButtonFormField

ZingPDF.Elements.Forms.FieldTypes.Button

Class 
public class PushButtonFormField : FormField<IPdfObject>

Represents a push-button field in an AcroForm.

Remarks

This type is currently useful for discovery and inspection only. Push-button actions are not yet exposed through the high-level API.

Class

SelectableOption

ZingPDF.Elements.Forms.FieldTypes.Button

Class 
public class SelectableOption

Represents a selectable checkbox or radio-button option.

Properties

Property

Text

public string Text { get; set; }

Gets or sets the display text for the option.

Property

Value

public string Value { get; set; }

Gets or sets the export value written to the field when this option is selected.

Property

Selected

public bool Selected { get; }

Gets whether the option is currently selected.

Methods

Method

SelectAsync

public Task SelectAsync();

Selects this option.

Method

DeselectAsync

public Task DeselectAsync();

Deselects this option.

Class

SignatureFormField

ZingPDF.Elements.Forms.FieldTypes.Signature

Class 
public class SignatureFormField : FormField<IPdfObject>

Represents a signature field.

Remarks

This type currently exposes metadata only. Digital signing is not yet implemented through this API.