PDFGen Class

Properties   Methods   Events   Config Settings   Errors  

The PDFGen class creates PDF documents from scratch.

Syntax

pdfsdk.PDFGen

Remarks

PDFGen is a versatile document generation class that can be used to create PDF documents in a highly customizable way.

Preparing the document for editing is as easy as calling CreateNew. Before calling this method, optionally configure baseline properties that you would like to apply to the new document, such as its page dimensions (SetLayout), page numbering (SetDocumentProperty), or PDF/A compliance requirements (PDFAConformanceLevel). Then start composing the document by adding content. When finished, call Close to close the document and save the changes to either OutputFile, OutputData, or the stream set in SetOutputStream.

The example below configures page numbers in the right header, adds a centered title with bold and underline formatting, and finally adds a left-aligned paragraph. PDFGen pdfgen = new PDFGen(); pdfgen.OutputFile = "output.pdf"; pdfgen.SetDocumentProperty("PageRightHeader", "%PAGENUMBER%"); pdfgen.CreateNew(); pdfgen.SetAlignment((int)HorizontalAlignments.haCenter, (int)VerticalAlignments.vaTop); pdfgen.SetFont("Arial", "20", "bold underline", "forestgreen"); pdfgen.AddText("The Preface", false); pdfgen.SetFont("Times New Roman", "14", "regular", "black"); pdfgen.AddBreak(0, 2); pdfgen.SetAlignment((int)HorizontalAlignments.haLeft, (int)VerticalAlignments.vaTop); pdfgen.AddParagraph("The artist is the creator of beautiful things. To reveal art and conceal the artist is art's aim. The critic is he who can translate into another manner or a new material his impression of beautiful things."); pdfgen.Close();

Canvases and the Editing Process

Every editing operation performed by PDFGen goes through a canvas, which is an editing window with a set of rules and operations defined for it that is either:

  • A text canvas, which can be thought of as a multi-line rich text editor;
  • A drawing canvas, a rectangular random-access drawing area; or
  • A table canvas, a rectangular grid of rows and columns.

The canvas types are distinct, meaning only one of them can be used at a time to create a specific piece of content. Canvases of different types can be grouped together or used as part of other canvases, which provides a powerful and flexible tool for creating content of various types and complexities. For example, a drawing canvas containing a graphic can be embedded into a text canvas containing the document body.

When CreateNew is called, the class automatically creates a page-wide text canvas (a "page canvas") so you can start adding content right away. This canvas takes into account the dimensions of the page and any margins configured. One-inch margins are set by default. Upon reaching the end of the page, the class closes the corresponding canvas, creates a new one for the next page (thus "turning the page" behind the scenes), and continues until all the content has been added.

You can always create your own canvases (and sub-canvases) should you need to add non-standard kinds of content that go beyond the traditional document layout, such as marginal notes, watermarks, or signatures.

Additionally, a canvas exists in one of three states:

  • Open, where it is in the process of editing and the content can still be changed;
  • Closed, where editing has been completed and the content has been finalized ("committed"); or
  • Rendered, where the content has been serialized from its internal closed representation into a PDF graphics stream.
An open canvas resembles an active editing area. Examples include a text canvas containing a line of text to which words are still being added, and a drawing canvas containing a path that has been started but not completed.

Changes made to an open canvas may influence how the content is represented in the document when the canvas is eventually rendered. For example, any text added to a center-aligned line in a text canvas will cause existing text to move leftward. Any text added to a drawing canvas - which is random access and does not offer the capability of formatting - will not affect any other content added to it previously.

A closed canvas resembles an opaque rectangle filled with visual elements. Once a canvas is closed, all such elements become locked and their dimensions are known, which enables their absolute positions and sizes to be calculated unambiguously as the class can be certain that they will not change.

During the editing process, PDFGen creates pieces of content, fills them in, closes them, and renders them onto the page. It adds content to the document sequentially like a typewriter: once added, content cannot be deleted. However, unlike a typewriter, content can be automatically formatted by the class on a later stage. For example, updating the dimensions of a text canvas may cause elements added to it previously to be rearranged, similar to how expanding a text area control in a browser form rearranges its content.

Text Canvases

A text canvas is a vertical series of lines, each comprised of a horizontal series of elements. It is analogous to a traditional text editor and is used for creating structured (mostly textual) content, which is added element by element, line by line. Pages, signature fields added via AddSignatureField, and table cells are all kinds of text canvases.

Random access is not allowed in text canvases; instead, the class stacks elements in the current line and arranges them as they are added. This means that in general, the dimensions of a text canvas (its Width and Height) are not fixed and may expand horizontally and vertically.

If the current line is full and cannot accommodate a subsequent element (and the chosen constraints do not allow for it to be expanded), in most cases the class completes the current line, adds a new one, places the cursor at the beginning of the new line, and adds the element there. However, if the element's width exceeds MaxWidth, it will not fit in the new line either, so the OutOfSpace event fires to give your code a chance to forcefully expand the canvas or cancel the insertion of the element altogether.

Similarly, exceeding MaxHeight also causes the class to automatically wrap to the next default canvas (e.g., the next page or column) or trigger OutOfSpace. Subscribe to that event to recover from failed calls in a flexible way.

Drawing Canvases

A drawing canvas is analogous to a drawing board and is used for creating free-form vector content in two-dimensional Cartesian space. A drawing canvas provides random access: primitives can be placed anywhere within its bounds in any order, and all coordinates are specified relative to the bottom-left corner of the canvas.

Content is built from path primitives, which include lines, curves, and closed shapes that can be stroked, filled, or used to define clipping regions. Common shapes such as rectangles, circles, and polygons are also supported directly, as is importing SVG path data via AddDrawing and placing bitmaps via AddBitmap.

The visual appearance of each primitive is controlled by the active Pen and Brush at the time the path is started. The pen governs the stroke (color, thickness, style, line cap, and line join) and the brush governs the fill (color and opacity). Use SetPen and SetBrush to configure these properties; they remain in effect until changed.

The dimensions of a drawing canvas are fixed at creation time. Content that exceeds these bounds is clipped. When committed to its parent canvas via EndDrawing, the drawing canvas can be scaled, skewed, and rotated as needed.

When committed to a text canvas, a drawing canvas is treated as an inline element and flows with surrounding content, just like text and bitmaps. When committed to another drawing canvas, it is positioned at explicit coordinates within that canvas.

Table Canvases

A table canvas is used for creating grid-based content organized into rows and columns. The column count is fixed at creation time; rows and cells are added sequentially, and the layout engine resolves all column widths and row heights when the table is committed to its parent canvas via EndTable.

Each cell is itself a text canvas, so any content that can be added to a page can also be added to a cell, including paragraphs, bitmaps, and nested drawing canvases. Cells can span multiple columns or rows, which the layout engine automatically accounts for when distributing space.

Width constraints can be specified at both the table and cell level. When no preferred width is given, the layout engine distributes available space proportionally across columns based on their content. Row heights follow the same principle: the height of each row is determined by the tallest cell it contains, unless a fixed or minimum height is specified via StartTableRow.

The Pen and Brush active when a cell is opened determine its border style and background fill. Individual cell borders can be suppressed via a bitmask passed to StartTableCell, allowing any combination of top, right, bottom, and left borders to be hidden independently.

Property List


The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Attachments A collection of all attached files added to the document.
Brush The current brush settings.
Canvas The current canvas.
Font The currently set font.
Layout The current page layout.
OutputData A byte array containing the PDF document after processing.
OutputFile The path to a local file where the output is written.
Overwrite Whether the class should overwrite files.
PDFAConformanceLevel The PDF/A conformance level of the document.
Pen The current pen settings.

Method List


The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

AddAttachment Adds an attachment to the document.
AddBitmap Adds a bitmap image to the current canvas.
AddBreak Adds a number of breaks to the text canvas.
AddButton Adds a button field to the form.
AddCheckBox Adds a checkbox field to the form.
AddComboBox Adds a combo box field to the form.
AddCopy Adds a copy of a previously saved element to the current canvas.
AddDrawing Adds a vector drawing described by an SVG path string to the current canvas.
AddHeading Adds a heading to the text canvas.
AddLink Adds a hyperlink to the current canvas.
AddListBox Adds a list box field to the form.
AddListItem Adds an item to a list, combo box, or list box.
AddParagraph Adds a paragraph of text to the text canvas.
AddRadioButton Adds a radio button to the form.
AddSignatureField Adds a signature field to the form.
AddSpecial Adds a special element to the text canvas.
AddTableCell Adds a single-paragraph cell to the current table row.
AddText Adds a piece of text to the current canvas.
AddTextBox Adds a text box field to the form.
AddTitle Adds a title to the text canvas.
Cancel Cancels the current canvas.
Close Closes the new document.
Config Sets or retrieves a configuration setting.
CreateNew Creates a new PDF document.
DrawCircle Draws an ellipse or circle on the drawing canvas.
DrawCurveTo Adds a cubic Bezier curve segment to the current path.
DrawLineTo Adds a straight line segment to the current path.
DrawPolygon Draws a polygon on the drawing canvas.
DrawRectangle Draws a rectangle on the drawing canvas.
EndComboBox Completes the combo box field.
EndContent Completes the logical section.
EndDrawing Finalizes the drawing canvas and commits it to the parent canvas.
EndEditing Finalizes the text canvas and commits it to the parent canvas.
EndForm Completes and closes the current interactive form.
EndList Completes the list.
EndListBox Completes the list box field.
EndListItem Completes the list item.
EndParagraph Completes the paragraph.
EndPath Completes the current path and applies it to the drawing canvas.
EndSignatureField Completes the signature field.
EndTable Finalizes the table canvas and commits it to the parent canvas.
EndTableCell Completes the current table cell.
EndTableRow Completes the current table row.
GetDocumentProperty Returns the value of a document property.
GetFieldProperty Returns the value of a field property.
GetPageProperty Returns the value of a page property.
MoveTo Sets the current pen position on the drawing canvas.
RemoveAttachment Removes an attachment from the document.
Reset Resets the class.
SaveStyle Saves the currently configured font, pen, and brush as a named style.
Scroll Inserts a vertical gap into the text canvas.
SetAlignment Sets the alignment for subsequent text insertion operations.
SetBrush Sets the fill properties used when drawing shapes and cell backgrounds.
SetDocumentProperty Sets the value of a document property.
SetFieldProperty Sets the value of a field property.
SetFont Sets the font properties to be applied to text.
SetLayout Sets the layout for new pages.
SetMargin Sets the margin for a typical element.
SetOutputStream Sets the stream to write the processed document to.
SetPageProperty Sets the value of a page property.
SetPen Sets the stroke properties used when drawing lines, paths, and borders.
SetStyle Applies a previously saved style or one of the built-in styles.
StartComboBox Begins a new combo box field for editing.
StartContent Begins a new logical section.
StartDrawing Initiates a new drawing canvas of the given dimensions.
StartEditing Initiates a new text canvas for editing.
StartForm Begins a new form.
StartList Begins a new list for editing.
StartListBox Begins a new list box field for editing.
StartListItem Begins a new list item for editing.
StartParagraph Begins a new paragraph for editing.
StartPath Starts a new vector path on the drawing canvas.
StartSignatureField Begins a new signature field for editing.
StartTable Initiates a new table canvas with a fixed number of columns.
StartTableCell Begins a new cell in the current table row.
StartTableRow Begins a new row in the current table.

Event List


The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

ActionRequired Fired when the class encounters a conflict that it cannot resolve on its own.
EditingCompleted Fired after a canvas has been closed.
Error Fired when information is available about errors during data delivery.
FontLookup Fired when a required font is missing.
Log Fired once for each log message.
OutOfSpace Fired when an element exceeds the maximum dimensions of the current text canvas.

Config Settings


The following is a list of config settings for the class with short descriptions. Click on the links for further details.

AutoTurnPages Whether to change the page automatically upon exceeding the lower page boundary.
CloseOutputStreamAfterProcessing Whether to close the output stream after processing.
CompressStreams Whether to compress stream objects.
FallbackFont The fallback font.
FontPaths The font search paths.
FontPolicy The font policy to follow.
LogLevel The level of detail that is logged.
SaveChanges Whether to save changes made to the document.
SystemFontNames The system font names.
TempPath The location where temporary files are stored.
UsedFonts The fonts used in the document.
BuildInfo Information about the product's build.
GUIAvailable Whether or not a message loop is available for processing events.
LicenseInfo Information about the current license.
MaskSensitiveData Whether sensitive data is masked in log messages.
UseDaemonThreads Whether threads created by the class are daemon threads.
UseInternalSecurityAPI Whether or not to use the system security libraries or an internal implementation.
UseVirtualThreads Whether threads created by the class use virtual threads instead of platform threads.

Attachments Property (PDFGen Class)

A collection of all attached files added to the document.

Syntax

public PDFAttachmentList getAttachments();

Remarks

This property is used to access the details of all the attached files added to the document. Use AddAttachment and RemoveAttachment to add and remove attachments to/from this collection respectively.

This property is not available at design time.

Please refer to the PDFAttachment type for a complete list of fields.

Brush Property (PDFGen Class)

The current brush settings.

Syntax

public PDFBrush getBrush();

Remarks

This property is used to access the fill configuration most recently applied via SetBrush.

This property is read-only and not available at design time.

Please refer to the PDFBrush type for a complete list of fields.

Canvas Property (PDFGen Class)

The current canvas.

Syntax

public PDFCanvas getCanvas();

Remarks

This property is used to access the details of the current canvas after one of the following methods is called:

It may be used to adjust the maximum dimensions of the canvas before calling the corresponding End* method.

This property is read-only and not available at design time.

Please refer to the PDFCanvas type for a complete list of fields.

Font Property (PDFGen Class)

The currently set font.

Syntax

public PDFFont getFont();

Remarks

This property is used to access the font details specified using SetFont.

This property is read-only and not available at design time.

Please refer to the PDFFont type for a complete list of fields.

Layout Property (PDFGen Class)

The current page layout.

Syntax

public PDFPageLayout getLayout();

Remarks

This property is used to access the current page settings specified using SetLayout.

This property is read-only and not available at design time.

Please refer to the PDFPageLayout type for a complete list of fields.

OutputData Property (PDFGen Class)

A byte array containing the PDF document after processing.

Syntax

public byte[] getOutputData();

Remarks

This property is used to read the byte array containing the produced output after the operation has completed. It is only set if an output file and output stream have not been assigned via OutputFile and SetOutputStream respectively.

This property is read-only and not available at design time.

OutputFile Property (PDFGen Class)

The path to a local file where the output is written.

Syntax

public String getOutputFile();
public void setOutputFile(String outputFile);

Default Value

""

Remarks

This property is used to provide a path where the resulting PDF document is saved after the operation has completed.

Overwrite Property (PDFGen Class)

Whether the class should overwrite files.

Syntax

public boolean isOverwrite();
public void setOverwrite(boolean overwrite);

Default Value

False

Remarks

This property indicates whether the class overwrites OutputFile. If set to false, an error is thrown whenever OutputFile exists before an operation.

PDFAConformanceLevel Property (PDFGen Class)

The PDF/A conformance level of the document.

Syntax

public int getPDFAConformanceLevel();
public void setPDFAConformanceLevel(int PDFAConformanceLevel);

Enumerated values:
  public final static int paclNone = 0;
  public final static int paclA1a = 1;
  public final static int paclA1b = 2;
  public final static int paclA2a = 3;
  public final static int paclA2b = 4;
  public final static int paclA2u = 5;
  public final static int paclA3a = 6;
  public final static int paclA3b = 7;
  public final static int paclA3u = 8;
  public final static int paclA4 = 9;
  public final static int paclA4e = 10;
  public final static int paclA4f = 11;

Default Value

0

Remarks

This property is used to specify the desired PDF/A conformance level the class attempts to apply when operating on the document.

Possible values are:

0 (paclNone - default) No PDF/A compliance
1 (paclA1a) PDF/A-1a
2 (paclA1b) PDF/A-1b
3 (paclA2a) PDF/A-2a
4 (paclA2b) PDF/A-2b
5 (paclA2u) PDF/A-2u
6 (paclA3a) PDF/A-3a
7 (paclA3b) PDF/A-3b
8 (paclA3u) PDF/A-3u
9 (paclA4) PDF/A-4
10 (paclA4e) PDF/A-4e
11 (paclA4f) PDF/A-4f

Pen Property (PDFGen Class)

The current pen settings.

Syntax

public PDFPen getPen();

Remarks

This property is used to access the stroke configuration most recently applied via SetPen.

This property is read-only and not available at design time.

Please refer to the PDFPen type for a complete list of fields.

AddAttachment Method (PDFGen Class)

Adds an attachment to the document.

Syntax

public void addAttachment(String fileName, String description, int attachmentType);

Remarks

This method is used to add an attachment (embedded file) to the document and to the Attachments collection.

FileName and Description specify the filename and description of the attachment respectively.

AttachmentType specifies the type of the attachment. Possible values are:

0 (patGeneric - default) A generic attachment.
1 (patElectronicInvoice) An XML invoice, for example in ZUGFeRD or Factur-X format.

Example: pdfgen.AddAttachment("foo.txt", "desc", (int)PDFAttachmentTypes.patGeneric); // Alternatively, create a PDFAttachment object and add it to Attachments manually: PDFAttachment attachment = new PDFAttachment(); attachment.FileName = "foo.txt"; // or attachment.DataB = new byte[] { ... }; // or attachment.InputStream = new FileStream(...); attachment.Description = "desc"; pdfgen.Attachments.Add(attachment); // Or using one of the constructors: pdfgen.Attachments.Add(new PDFAttachment("foo.txt", "desc")); pdfgen.Close(); The full list of attachments is contained in the Attachments collection.

AddBitmap Method (PDFGen Class)

Adds a bitmap image to the current canvas.

Syntax

public void addBitmap(String format, byte[] bytes, int bitmapWidth, int bitmapHeight, String scaleWidth, String scaleHeight);

Remarks

This method is used to add a bitmap image to the current canvas.

Its behavior differs depending on the type of canvas it is called on. On a text canvas, the image is treated as an inline element and placed in the normal flow of content, following the same layout rules as text and other content. On a drawing canvas, the image is placed at the current pen position as set by MoveTo.

Format specifies the image format and color space of the supplied bytes, as a combined string (e.g., png-rgb, jpeg-cmyk).

Bytes contains the raw image data.

BitmapWidth and BitmapHeight specify the intrinsic pixel dimensions of the image.

ScaleWidth and ScaleHeight specify the rendered dimensions of the image. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

NOTE: This method throws an exception if a list is currently being edited.

AddBreak Method (PDFGen Class)

Adds a number of breaks to the text canvas.

Syntax

public void addBreak(int breakKind, int count);

Remarks

This method is used to add Count breaks to the current text canvas, completing the current line, column, or page early and starting a new one (or multiple).

BreakKind specifies the kind of break to add. Possible values are:

0 (bkLine) A line break.
1 (bkColumn) Currently unsupported.
2 (bkPage) A page break.

NOTE: This method throws an exception if the current canvas is not a text canvas.

AddButton Method (PDFGen Class)

Adds a button field to the form.

Syntax

public void addButton(String fieldName, String caption, int actionType, String width, String height);

Remarks

This method is used to create a button field with name FieldName and caption Caption.

ActionType specifies the type of action that is executed when the button is pressed. Possible values are:

0 (batNone) No action
1 (batSubmit) Submit-form action
2 (batReset) Reset-form action
3 (batImport) Import-data action

Width and Height specify the width and height of the button. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

On a text canvas, the element is placed in the normal flow of content. On a drawing canvas, it is placed at the current pen position as set by MoveTo.

NOTE: This method throws an exception if a list is currently being edited.

AddCheckBox Method (PDFGen Class)

Adds a checkbox field to the form.

Syntax

public void addCheckBox(String fieldName, boolean defaultValue, String width, String height);

Remarks

This method is used to create a checkbox field with name FieldName.

DefaultValue specifies the initial state of the checkbox (checked/unchecked).

Width and Height specify the width and height of the checkbox. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

On a text canvas, the element is placed in the normal flow of content. On a drawing canvas, it is placed at the current pen position as set by MoveTo.

NOTE: This method throws an exception if a list is currently being edited.

AddComboBox Method (PDFGen Class)

Adds a combo box field to the form.

Syntax

public void addComboBox(String fieldName, String options, String defaultValue, String width, String height);

Remarks

This method is used to create a combo box field with name FieldName.

Options specifies a list of choices as a multi-line string.

DefaultValue specifies the initial value selected in the combo box.

Width and Height specify the width and height of the combo box. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

To create a combo box incrementally instead of all at once, use StartComboBox and EndComboBox.

On a text canvas, the element is placed in the normal flow of content. On a drawing canvas, it is placed at the current pen position as set by MoveTo.

NOTE: This method throws an exception if a list is currently being edited.

AddCopy Method (PDFGen Class)

Adds a copy of a previously saved element to the current canvas.

Syntax

public void addCopy(String id, String scaleX, String scaleY, String rotation, String skewA, String skewB);

Remarks

This method is used to add a copy of an element that was previously saved in the class to the current canvas.

Id specifies the Id given to the saved:

  • Canvas when it was closed in one of the canvas-finalizing End* methods
  • Path when it was completed in EndPath
  • List when it was completed in EndList
  • Paragraph when it was completed in EndParagraph
  • Table row when it was closed in EndTableRow

A saved element may be added any number of times, to any number of canvases.

On a text canvas, the copy is treated as an inline element and placed in the normal flow of content, following the same layout rules as text and other content. On a drawing canvas, the copy is placed at the current pen position as set by MoveTo.

Note that a saved path can only be added to a drawing canvas; attempting to add one to any other type of canvas throws an exception.

ScaleX and ScaleY specify the horizontal and vertical scale factors to apply to the copy when placing it on the current canvas, with 1.0 being the original size of the saved element (100%).

Rotation specifies the rotation angle of the copy in degrees counterclockwise. If empty or 0, no rotation is applied.

SkewA and SkewB specify the horizontal and vertical skew angles of the copy in degrees. SkewA shears along the X axis and SkewB shears along the Y axis. If empty or 0, no skew is applied.

NOTE: This method throws an exception if a list is currently being edited.

AddDrawing Method (PDFGen Class)

Adds a vector drawing described by an SVG path string to the current canvas.

Syntax

public void addDrawing(String svgPath, String scaleX, String scaleY);

Remarks

This method is used to parse an SVG path data string and add the resulting drawing to the current canvas.

SvgPath is a standard SVG path data string using the commands M, L, H, V, C, S, Q, T, A, Z (and their lowercase relative equivalents). The following commands are supported:

M / m Move to (absolute / relative)
L / l Line to
H / h Horizontal line to
V / v Vertical line to
C / c Cubic Bezier curve
S / s Smooth cubic Bezier curve
Q / q Quadratic Bezier curve
T / t Smooth quadratic Bezier curve
A / a Elliptical arc
Z / z Close path

ScaleX and ScaleY specify the horizontal and vertical scale factors to apply to the drawing when placing it on the parent canvas. These parameters accept real values, with 1.0 being the actual size of the drawing (100%).

If the current canvas is already a drawing canvas, the path is imported directly into it. Otherwise, a temporary drawing canvas is created, the path is added to it, and the canvas is committed to the current canvas using ScaleX and ScaleY.

NOTE: This method throws an exception if a list is currently being edited.

AddHeading Method (PDFGen Class)

Adds a heading to the text canvas.

Syntax

public void addHeading(int level, String text);

Remarks

This method is currently unsupported.

AddLink Method (PDFGen Class)

Adds a hyperlink to the current canvas.

public void addLink(String text, String URL);

This method is used to add a clickable hyperlink to the current canvas whose visible label is Text. Clicking the link opens the external URL specified by URL.

On a text canvas, the element is placed in the normal flow of content. On a drawing canvas, it is placed at the current pen position as set by MoveTo.

NOTE: This method throws an exception if a list is currently being edited.

AddListBox Method (PDFGen Class)

Adds a list box field to the form.

Syntax

public void addListBox(String fieldName, String options, String defaultValue, String width, String height);

Remarks

This method is used to create a list box field with name FieldName.

Options specifies a list of choices as a multi-line string.

DefaultValue specifies the initial value selected in the list box.

Width and Height specify the width and height of the list box. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

To create a list box incrementally instead of all at once, use StartListBox and EndListBox.

On a text canvas, the element is placed in the normal flow of content. On a drawing canvas, it is placed at the current pen position as set by MoveTo.

NOTE: This method throws an exception if a list is currently being edited.

AddListItem Method (PDFGen Class)

Adds an item to a list, combo box, or list box.

Syntax

public void addListItem(String text);

Remarks

This method is used to add Text as either a list item or a choice in a combo box or list box field.

When this method is used to add a choice to a form field, Text can either contain a user-readable value alone, or be followed by an internal (exported) name that is recorded as the value of the field if the option is selected. If provided, the internal name must be separated from the preceding user-readable value by the vertical bar character (|). If the internal name postfix is omitted, the user-readable value is recorded as the field value if the option is selected.

Example: // The value displayed to the user is "Pineapple", and the exported value is "pineapple" pdfgen.AddListItem("Pineapple|pineapple"); // The exported value of the option matches the value displayed to the user ("Olives") pdfgen.AddListItem("Olives"); // The value displayed to the user is "Roasted Marshmallows", and the exported value is "marshmallows" pdfgen.AddListItem("Roasted Marshmallows|marshmallows"); To create a list item incrementally instead of all at once, use StartListItem and EndListItem.

NOTE: This method throws an exception if the current canvas is not a text canvas.

NOTE: If used to add a list item, this method throws an exception if a list is not currently being edited.

AddParagraph Method (PDFGen Class)

Adds a paragraph of text to the text canvas.

Syntax

public void addParagraph(String text);

Remarks

This method is used to add a paragraph of Text to the current text canvas, which is done by breaking the text into lines and then words, and adding each word as a separate piece of text. When the end of a line is reached, the class inserts a line break and applies the line spacing set in SetMargin before continuing on to the next line of the paragraph.

Use SetAlignment and SetFont to adjust the parameters of the text that comprises the new paragraph, and use SetMargin to indent the first line of the paragraph.

To create a paragraph incrementally instead of all at once, use StartParagraph and EndParagraph.

NOTE: If Text is empty, a line break is added.

NOTE: This method throws an exception if the current canvas is not a text canvas or if a list is currently being edited.

AddRadioButton Method (PDFGen Class)

Adds a radio button to the form.

Syntax

public void addRadioButton(String fieldName, String radioGroup, boolean isDefaultButton, String width, String height);

Remarks

This method is used to create a radio button field with name FieldName within the radio group RadioGroup.

IsDefaultButton specifies whether the radio button will be selected initially (i.e., whether it will be the default value of the radio group).

Width and Height specify the width and height of the radio button. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

On a text canvas, the element is placed in the normal flow of content. On a drawing canvas, it is placed at the current pen position as set by MoveTo.

NOTE: This method throws an exception if a list is currently being edited.

AddSignatureField Method (PDFGen Class)

Adds a signature field to the form.

Syntax

public void addSignatureField(String fieldName, String width, String height);

Remarks

This method is used to create a signature field with name FieldName as a text canvas.

Width and Height specify the width and height of the signature field. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

To create a signature field incrementally instead of all at once, use StartSignatureField and EndSignatureField.

NOTE: This method only applies if the current canvas is a text canvas.

NOTE: This method throws an exception if a list is currently being edited.

AddSpecial Method (PDFGen Class)

Adds a special element to the text canvas.

Syntax

public void addSpecial(int objectType, String content);

Remarks

This method is currently unsupported.

AddTableCell Method (PDFGen Class)

Adds a single-paragraph cell to the current table row.

Syntax

public void addTableCell(String text, String width);

Remarks

This convenience method is used to open a new cell, add Text as a paragraph, and close the cell in a single call. It is equivalent to calling StartTableCell with ColSpan and RowSpan set to 1 and Borders set to 0, followed by AddParagraph and EndTableCell.

Text specifies the text content of the cell. If empty, an empty cell is added.

Width specifies the cell width constraints using the same [preferred]:[min]:[max] syntax as the corresponding parameter in StartTableCell. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

Use this method when a cell contains only a single plain-text paragraph and does not require colspan, rowspan, or complex inner content. For cells with richer content or spanning requirements, use StartTableCell and EndTableCell directly.

NOTE: This method throws an exception if the current canvas is not a table canvas.

AddText Method (PDFGen Class)

Adds a piece of text to the current canvas.

Syntax

public void addText(String text, boolean wrappable);

Remarks

This method is used to add a piece of Text to the current canvas. Use SetAlignment and SetFont to adjust new text parameters.

Wrappable is reserved for future use.

On a text canvas, the element is placed in the normal flow of content. On a drawing canvas, it is placed at the current pen position as set by MoveTo.

NOTE: This method throws an exception if a list is currently being edited.

AddTextBox Method (PDFGen Class)

Adds a text box field to the form.

Syntax

public void addTextBox(String fieldName, String defaultValue, boolean multiLine, boolean password, String width, String height);

Remarks

This method is used to create a text box field with name FieldName.

DefaultValue specifies the initial value contained in the text box.

MultiLine specifies whether the text box can contain multiple lines of text.

Password specifies whether the text box is intended to contain a password. Pass true to have the text displayed as asterisk characters (*).

Width and Height specify the width and height of the text box. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

On a text canvas, the element is placed in the normal flow of content. On a drawing canvas, it is placed at the current pen position as set by MoveTo.

NOTE: This method throws an exception if a list is currently being edited.

AddTitle Method (PDFGen Class)

Adds a title to the text canvas.

Syntax

public void addTitle(String text);

Remarks

This method is currently unsupported.

Cancel Method (PDFGen Class)

Cancels the current canvas.

Syntax

public void cancel();

Remarks

This method is used to cancel the canvas that is currently being edited. It should be called after one of the following methods as an alternative to setting Choice to oscFullCancel within the OutOfSpace event:

Example: pdfgen.StartEditing("100", "100", (int)ContentAnchors.caTop); pdfgen.AddText("Hello world!", false); try { pdfgen.EndEditing("1", "1", "0", "0", "0", ""); } catch (PDFSDKException ex) { pdfgen.Cancel(); } NOTE: This method throws an exception if the current canvas is a page canvas.

Close Method (PDFGen Class)

Closes the new document.

Syntax

public void close();

Remarks

This method is used to close the new document. It should always be preceded by a call to CreateNew.

Example: pdfgen.OutputFile = "output.pdf"; pdfgen.CreateNew(); // Some operation pdfgen.Close(); The document is saved automatically to OutputFile, OutputData, or the stream set in SetOutputStream when this method is called. To configure this saving behavior, set SaveChanges.

Config Method (PDFGen Class)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

CreateNew Method (PDFGen Class)

Creates a new PDF document.

Syntax

public void createNew();

Remarks

This method is used to create a blank PDF document with one empty page and an underlying page canvas. Use SetLayout to adjust the new page dimensions and number of columns. Having created the baseline document, use the class's methods to add objects to it.

Upon completion of this method, information about the newly created page canvas can be accessed using the Canvas property.

DrawCircle Method (PDFGen Class)

Draws an ellipse or circle on the drawing canvas.

Syntax

public void drawCircle(String radiusX, String radiusY);

Remarks

This method is used to add a closed elliptical shape to the current drawing canvas, centered at the current pen position as set by MoveTo.

RadiusX and RadiusY specify the horizontal and vertical radii of the ellipse. To draw a perfect circle, pass equal values for both. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

Use SetPen and SetBrush before calling this method to control the border style and fill color.

NOTE: This method throws an exception if the current canvas is not a drawing canvas.

DrawCurveTo Method (PDFGen Class)

Adds a cubic Bezier curve segment to the current path.

Syntax

public void drawCurveTo(String X, String Y, String viaX1, String viaY1, String viaX2, String viaY2);

Remarks

This method is used to extend the currently open path on the drawing canvas with a cubic Bezier curve from the current pen position to the endpoint specified by X and Y. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

ViaX1 and ViaY1 specify the first control point, which influences the curve near its start.

ViaX2 and ViaY2 specify the second control point, which influences the curve near its end.

Upon completion of this method, the current pen position will be moved to (X, Y).

NOTE: This method throws an exception if the current canvas is not a drawing canvas or if no path has been started with StartPath.

DrawLineTo Method (PDFGen Class)

Adds a straight line segment to the current path.

Syntax

public void drawLineTo(String X, String Y);

Remarks

This method is used to extend the currently open path on the drawing canvas with a straight line from the current pen position to the point specified by X and Y. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

Upon completion of this method, the current pen position will be moved to (X, Y).

NOTE: This method throws an exception if the current canvas is not a drawing canvas or if no path has been started with StartPath.

DrawPolygon Method (PDFGen Class)

Draws a polygon on the drawing canvas.

Syntax

public void drawPolygon(String points);

Remarks

This method is used to add a closed polygon defined by a list of vertices to the current drawing canvas.

Points specifies a comma-separated list of coordinate pairs in the form X1,Y1,X2,Y2,...,XN,YN containing at least three vertices. All coordinates are relative to the bottom-left corner of the drawing canvas. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

The first vertex is used as the starting point. Subsequent vertices are connected with straight line segments. After the last vertex, the path is automatically closed back to the first vertex.

The polygon is stroked and filled using the current Pen and Brush. Use SetPen and SetBrush before calling this method to control the border style and fill color.

NOTE: This method throws an exception if the current canvas is not a drawing canvas or if fewer than three vertices are supplied.

DrawRectangle Method (PDFGen Class)

Draws a rectangle on the drawing canvas.

Syntax

public void drawRectangle(String width, String height, String cornerRadius);

Remarks

This method is used to add a rectangle to the current drawing canvas. The rectangle is defined by its bottom-left corner at the current pen position as set by MoveTo, and the specified Width and Height. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

CornerRadius specifies the radius of the rounded corners of the rectangle. If greater than 0, each corner is replaced by a circular arc of the given radius. If the radius exceeds half the shorter side of the rectangle, it is automatically clamped to that maximum.

The rectangle is stroked and filled using the current Pen and Brush. Use SetPen and SetBrush before calling this method to control the border style and fill color.

NOTE: This method throws an exception if the current canvas is not a drawing canvas.

EndComboBox Method (PDFGen Class)

Completes the combo box field.

Syntax

public void endComboBox();

Remarks

This method is used to finalize the combo box field started in StartComboBox. Note that the combo box can no longer be modified after it is completed.

NOTE: This method throws an exception if the current canvas is not a text canvas.

EndContent Method (PDFGen Class)

Completes the logical section.

Syntax

public void endContent();

Remarks

This method is currently unsupported.

EndDrawing Method (PDFGen Class)

Finalizes the drawing canvas and commits it to the parent canvas.

Syntax

public void endDrawing(String scaleX, String scaleY, String rotation, String skewA, String skewB, String canvasId);

Remarks

This method is used to close the drawing canvas opened in StartDrawing and commit it to its parent canvas. Any open path on the drawing canvas is automatically closed first. Note that the drawing canvas can no longer be modified after it is closed.

If the parent canvas is a text canvas, the closed canvas is treated as an inline element and placed in the normal flow of content, following the same layout rules as text and other content. If the parent canvas is a drawing canvas, the closed canvas is placed at the current pen position of the parent canvas as set by MoveTo.

ScaleX and ScaleY specify the horizontal and vertical scale factors to apply to the canvas when placing it on the parent canvas. These parameters default to 1 if empty.

Rotation specifies the rotation angle of the canvas in degrees counterclockwise. If empty or 0, no rotation is applied.

SkewA and SkewB specify the horizontal and vertical skew angles of the canvas in degrees. SkewA shears along the X axis and SkewB shears along the Y axis. If empty or 0, no skew is applied.

The full transformation is applied in the following order: scale, skew, rotation, translation.

If CanvasId is non-empty, the closed canvas is also saved in the class under that Id and can be added to other canvases with AddCopy. Each saved Id must be unique, and a canvas that contains form fields cannot be saved.

NOTE: This method throws an exception if the current canvas is not a drawing canvas.

EndEditing Method (PDFGen Class)

Finalizes the text canvas and commits it to the parent canvas.

Syntax

public void endEditing(String scaleX, String scaleY, String rotation, String skewA, String skewB, String canvasId);

Remarks

This method is used to close the text canvas opened in StartEditing and commit it to its parent canvas. Note that the text canvas can no longer be modified after it is closed.

If the parent canvas is a text canvas, the closed canvas is treated as an inline element and placed in the normal flow of content, following the same layout rules as text and other content. If the parent canvas is a drawing canvas, the closed canvas is placed at the current pen position of the parent canvas as set by MoveTo.

ScaleX and ScaleY specify the horizontal and vertical scale factors to apply to the canvas when placing it on the parent canvas. These parameters default to 1 if empty.

Rotation specifies the rotation angle of the canvas in degrees counterclockwise. If empty or 0, no rotation is applied.

SkewA and SkewB specify the horizontal and vertical skew angles of the canvas in degrees. SkewA shears along the X axis and SkewB shears along the Y axis. If empty or 0, no skew is applied.

The full transformation is applied in the following order: scale, skew, rotation, translation.

If CanvasId is non-empty, the closed canvas is also saved in the class under that Id and can be added to other canvases with AddCopy. Each saved Id must be unique, and a canvas that contains form fields cannot be saved.

NOTE: This method throws an exception if the current canvas is not a text canvas.

EndForm Method (PDFGen Class)

Completes and closes the current interactive form.

Syntax

public void endForm();

Remarks

The method is used to complete the interactive form that was started explicitly in StartForm or implicitly via a method such as AddCheckBox or AddTextBox.

A PDF document can only contain one form, which can span multiple pages. After the form is closed, no more form fields can be added to the document.

NOTE: This method throws an exception if the current canvas is not a text canvas or if there is no active form in the document.

EndList Method (PDFGen Class)

Completes the list.

Syntax

public void endList(String listId);

Remarks

This method is used to finalize the list started in StartList. Note that the list can no longer be modified after it is completed.

ListId is reserved for future use.

NOTE: This method throws an exception if a list is not currently being edited.

EndListBox Method (PDFGen Class)

Completes the list box field.

Syntax

public void endListBox();

Remarks

This method is used to finalize the list box field started in StartListBox. Note that the list box can no longer be modified after it is completed.

NOTE: This method throws an exception if the current canvas is not a text canvas.

EndListItem Method (PDFGen Class)

Completes the list item.

Syntax

public void endListItem(String canvasId);

Remarks

This method is used to finalize the list item started in StartListItem and commit the underlying text canvas to its parent canvas. Note that the list item can no longer be modified after it is completed.

CanvasId is reserved for future use.

NOTE: This method throws an exception if a list is not currently being edited.

EndParagraph Method (PDFGen Class)

Completes the paragraph.

Syntax

public void endParagraph(String paraId);

Remarks

This method is used to finalize the paragraph started in StartParagraph and add a line break so that subsequent content starts on a new line. Note that the paragraph can no longer be modified after it is completed.

ParaId is reserved for future use.

NOTE: This method only applies if the current canvas is a text canvas.

EndPath Method (PDFGen Class)

Completes the current path and applies it to the drawing canvas.

Syntax

public void endPath(boolean closePath, String pathId);

Remarks

This method is used to finalize the path started in StartPath and record it as a drawing primitive on the current drawing canvas. The path is rendered according to the drawing mode specified in StartPath when the canvas is eventually closed.

ClosePath specifies whether to close the path by drawing a straight line from the current pen position back to the path's starting point before applying the drawing mode. Pass true to close the path (useful for filled shapes), or false to leave the path open.

If PathId is non-empty, the completed path is also saved in the class under that Id and can be added to other drawing canvases with AddCopy. Each saved Id must be unique.

NOTE: This method throws an exception if the current canvas is not a drawing canvas.

EndSignatureField Method (PDFGen Class)

Completes the signature field.

Syntax

public void endSignatureField(String scaleX, String scaleY, String rotation, String skewA, String skewB, String canvasId);

Remarks

This method is used to finalize the signature field started in StartSignatureField and commit the underlying canvas to its parent canvas. Note that the signature field canvas can no longer be modified after it is closed.

ScaleX and ScaleY are reserved for future use.

Rotation is reserved for future use.

SkewA and SkewB are reserved for future use.

CanvasId is reserved for future use.

NOTE: This method throws an exception if the current canvas is not a text canvas.

EndTable Method (PDFGen Class)

Finalizes the table canvas and commits it to the parent canvas.

Syntax

public void endTable(String canvasId);

Remarks

This method is used to close the table canvas opened in StartTable and commit it to its parent canvas. Any open cell or row in the table is automatically closed before the table layout is resolved. Note that the table canvas can no longer be modified after it is closed.

If CanvasId is non-empty, the closed canvas is also saved in the class under that Id and can be added to other canvases with AddCopy. Each saved Id must be unique, and a canvas that contains form fields cannot be saved.

NOTE: This method throws an exception if the current canvas is not a table canvas.

EndTableCell Method (PDFGen Class)

Completes the current table cell.

Syntax

public void endTableCell(String canvasId);

Remarks

This method is used to explicitly close the cell opened in StartTableCell and commit the underlying cell canvas to its parent table canvas. Note that the cell canvas can no longer be modified after it is closed.

CanvasId is reserved for future use.

It is not necessary to call this method before starting the next cell via StartTableCell, as open cells are closed implicitly at that point.

NOTE: This method throws an exception if the current canvas is not a cell canvas.

EndTableRow Method (PDFGen Class)

Completes the current table row.

Syntax

public void endTableRow(String rowId);

Remarks

This method is used to explicitly close the row opened in StartTableRow. Any open cell in the row is automatically closed first, and any columns that have not been filled with a cell are padded with empty cells so that the row always spans the full column count of the table. Note that the row can no longer be modified after it is closed.

RowId is reserved for future use.

It is not necessary to call this method before starting the next row via StartTableRow, as open rows are closed implicitly at that point.

NOTE: This method throws an exception if the current canvas is not a table canvas.

GetDocumentProperty Method (PDFGen Class)

Returns the value of a document property.

Syntax

public String getDocumentProperty(String documentProperty);

Remarks

This method is used to obtain the value of a document property. Together with SetDocumentProperty, this method provides an extensible way of managing the document settings that are not available through other means. The list of settings below may be extended in the future.

DocumentProperty specifies the document property to read. Possible values are:

Document property Default value Description
FooterFromBottom 36 The vertical offset of the footer from the bottom page border in points.
HeaderFromTop 36 The vertical offset of the header from the top page border in points.
MirrorFooters False Whether to automatically swap the left and right footers in double-sided documents. If enabled, the left and right footers will be mirrored on alternating pages.
MirrorHeaders False Whether to automatically swap the left and right headers in double-sided documents. If enabled, the left and right headers will be mirrored on alternating pages.
MirrorMargins False Whether to automatically swap the left and right margins in double-sided documents. If enabled, the left and right margins will be mirrored on alternating pages.
PageFooter "" The central footer text.
PageFooterFont Times New Roman The font name for the footer text.
PageFooterFontColor #000000 The font color for the footer text.
PageFooterFontSize 12 The font size for the footer text.
PageFooterFontStyle "" The font style for the footer text.
PageHeader "" The central header text.
PageHeaderFont Times New Roman The font name for the header text.
PageHeaderFontColor #000000 The font color for the header text.
PageHeaderFontSize 12 The font size for the header text.
PageHeaderFontStyle "" The font style for the header text.
PageLeftFooter "" The left footer text.
PageLeftHeader "" The left header text.
PageNumber 1 The starting page number in the header or footer.
PageNumberFormat Automatic The page number format. Supported values: Automatic, Alpha, AlphaCaps, Roman, RomanCaps, Numeric.
PageRightFooter "" The right footer text.
PageRightHeader "" The right header text.
UsedFonts "" A CRLF-separated list of all the fonts used in the document.
Watermark "" The watermark text to be displayed.
WatermarkFont Times New Roman The font name for the watermark text.
WatermarkFontColor #BFBFBF The font color for the watermark text.
WatermarkFontSize "" The font size for the watermark text. If empty, the watermark is automatically adjusted to fit the page.
WatermarkFontStyle "" The font style for the watermark text.
WatermarkStyle diagonal The style and placement of the watermark. Supported values: diagonal, horizontal, vertical, scattered, brickwork. The style can also include a direction separated by a space: NE/northeast, SE/southeast, NW/northwest, SW/southwest, N/north, S/south, E/east, W/west.
Xmp "" The XML body of the XMP metadata embedded in the document.
Xmp[property] "" The value of an XMP metadata property.
XmpStream "" The hex-encoded content of the XMP metadata stream.

Example: string description = pdfgen.GetDocumentProperty("Xmp[dc:description]"); string metadataXml = pdfgen.GetDocumentProperty("Xmp"); // Use language descriptors for multi-language properties string descriptionEs = pdfgen.GetDocumentProperty("Xmp[dc:description[es]]");

GetFieldProperty Method (PDFGen Class)

Returns the value of a field property.

Syntax

public String getFieldProperty(String fieldName, String fieldProperty);

Remarks

This method is used to obtain the value of a field property. Together with SetFieldProperty, this method provides an extensible way of managing the field settings that are not available through other means. The list of settings below may be extended in the future.

FieldName is the name of the field of interest, and FieldProperty specifies the field property to read. Possible values are:

Field property Default value Description
AnnotationFlags 0 The field annotation flags.
AnnotationHidden False Whether the field annotation is completely invisible, meaning it cannot be displayed, printed, or interacted with.
AnnotationInvisible False Whether the field annotation is invisible on the screen and in print, but still remains interactive.
AnnotationLocked False Whether the user cannot modify the field annotation's properties, such as its position and size.
AnnotationLockedContents False Whether the user cannot modify the field annotation's contents.
AnnotationNoRotate False Whether the field annotation's orientation remains fixed regardless of the page rotation.
AnnotationNoView False Whether the field annotation is invisible on the screen and cannot be interacted with, but still appears when printed.
AnnotationNoZoom False Whether the field annotation's size remains fixed regardless of the page magnification level.
AnnotationPrint False Whether the field annotation appears when the page is printed.
AnnotationReadOnly False Whether the user cannot interact with or modify the field annotation.
AnnotationToggleNoView False Whether the field annotation's NoView flag is intended to be toggled dynamically by a user action or script.
Flags 0 The field flags.
IncludeEdit False Whether the combo box field includes an editable text box in addition to a drop-down list.
MultiLine False Whether the text box field can contain multiple lines of text.
MultiSelect False Whether multiple options can be selected simultaneously in the combo box or list box field.
NoExport False Whether the field is not exported when the form is submitted.
NoToggleToOff False Whether exactly one radio button in the radio group must always be selected.
Password False Whether the text box field is intended to contain a password.
ReadOnly False Whether the user cannot change the field's value.
Required False Whether the field must have a value before the form can be submitted.
Sort False Whether the options are automatically sorted alphabetically in the combo box or list box field.
UnisonSelect False Whether selecting one radio button automatically selects all other radio buttons in the same group that share the same field name and value for the on state.

GetPageProperty Method (PDFGen Class)

Returns the value of a page property.

Syntax

public String getPageProperty(String pageProperty);

Remarks

This method is used to obtain the value of a page property for the current page. Together with SetPageProperty, this method provides an extensible way of managing the current page settings that are not available through other means. The list of settings below may be extended in the future.

PageProperty specifies the page property to read. Possible values are:

Page property Default value Description
PageFooter "" The central footer text.
PageFooterFont Times New Roman The font name for the footer text.
PageFooterFontColor #000000 The font color for the footer text.
PageFooterFontSize 12 The font size for the footer text.
PageFooterFontStyle "" The font style for the footer text.
PageHeader "" The central header text.
PageHeaderFont Times New Roman The font name for the header text.
PageHeaderFontColor #000000 The font color for the header text.
PageHeaderFontSize 12 The font size for the header text.
PageHeaderFontStyle "" The font style for the header text.
PageLeftFooter "" The left footer text.
PageLeftHeader "" The left header text.
PageNumber 1 The page number in the header or footer.
PageNumberFormat Automatic The page number format. Supported values: Automatic, Alpha, AlphaCaps, Roman, RomanCaps, Numeric.
PageRightFooter "" The right footer text.
PageRightHeader "" The right header text.
Watermark "" The watermark text to be displayed.
WatermarkFont Times New Roman The font name for the watermark text.
WatermarkFontColor #BFBFBF The font color for the watermark text.
WatermarkFontSize "" The font size for the watermark text. If empty, the watermark is automatically adjusted to fit the page.
WatermarkFontStyle "" The font style for the watermark text.
WatermarkStyle diagonal The style and placement of the watermark. Supported values: diagonal, horizontal, vertical, scattered, brickwork. The style can also include a direction separated by a space: NE/northeast, SE/southeast, NW/northwest, SW/southwest, N/north, S/south, E/east, W/west.

MoveTo Method (PDFGen Class)

Sets the current pen position on the drawing canvas.

Syntax

public void moveTo(String X, String Y);

Remarks

This method is used to set the pen position on the current drawing canvas to the point specified by X and Y, relative to the bottom-left corner of the canvas. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used. If either parameter is empty, that coordinate is left unchanged.

The current pen position determines where the next element is placed on the canvas. It is used as:

NOTE: This method only applies if the current canvas is a drawing canvas.

RemoveAttachment Method (PDFGen Class)

Removes an attachment from the document.

Syntax

public void removeAttachment(int index);

Remarks

This method is used to remove an attachment from the document and from the Attachments collection.

Index is the index of the attachment in the Attachments collection to be removed.

Example: pdfgen.RemoveAttachment(0); // Alternatively, remove an attachment from Attachments manually: PDFAttachment attachment = pdfgen.Attachments[0]; pdfgen.Attachments.Remove(attachment); pdfgen.Close();

Reset Method (PDFGen Class)

Resets the class.

Syntax

public void reset();

Remarks

This method is used to reset the class's properties and configuration settings to their default values.

SaveStyle Method (PDFGen Class)

Saves the currently configured font, pen, and brush as a named style.

Syntax

public void saveStyle(String styleId);

Remarks

This method is used to record the current font, pen, and brush settings under the Id given in StyleId, allowing the same look to be reapplied later with SetStyle. A style captures the settings as they are currently configured, so it reflects the accumulated result of any preceding SetFont, SetPen, and SetBrush calls.

Style Ids are case-insensitive. This method throws an exception if a style with the same Id has already been saved or if StyleId is one of the reserved built-in style names (Default, Title, H1 through H6, and P); see SetStyle for details.

Example: pdfgen.SetFont("Arial", "8", "bold", "#FF0000"); pdfgen.SaveStyle("SmallRedArial"); ... pdfgen.SetStyle("SmallRedArial"); // restores the 8pt bold red Arial font

Scroll Method (PDFGen Class)

Inserts a vertical gap into the text canvas.

Syntax

public void scroll(String height);

Remarks

This method is used to insert an empty vertical gap of Height into the current text canvas, pushing the content that follows it down by that amount. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

NOTE: This method throws an exception if the current canvas is not a text canvas.

SetAlignment Method (PDFGen Class)

Sets the alignment for subsequent text insertion operations.

Syntax

public void setAlignment(int horizontalAlignment, int verticalAlignment);

Remarks

This method is used to set the horizontal and vertical alignment parameters to apply to text content, including individual pieces of text and paragraphs. Alignment specifies the position of the newly added text content within the lines of a text canvas.

HorizontalAlignment specifies the horizontal alignment relative to the left or right canvas boundaries. Possible values are:

0 (haLeft - default)
1 (haCenter)
2 (haRight)
3 (haJustify)

VerticalAlignment specifies the vertical alignment of text elements relative to each other. Possible values are:

0 (vaTop - default)
1 (vaCenter)
2 (vaBottom)

NOTE: This method only applies if the current canvas is a text or table canvas.

SetBrush Method (PDFGen Class)

Sets the fill properties used when drawing shapes and cell backgrounds.

Syntax

public void setBrush(String color, String opacity);

Remarks

This method is used to configure the brush that is applied to the interior of all subsequently added shapes, closed paths, and table cell backgrounds.

Color specifies the fill color. If non-empty, the brush is activated and the specified color is used for all subsequent filled elements. For the full list of supported colors, see SetFont.

Opacity specifies the fill opacity as a value between 0 (fully transparent) and 1 (fully opaque). If empty, full opacity is used. Passing a non-empty opacity alone (without a color) also activates the brush using the previously stored color.

If both Color and Opacity are empty, the brush is reset to its unset state, and no fill is applied to subsequent elements. This is useful when you want a shape to be stroked only, with a transparent interior.

SetDocumentProperty Method (PDFGen Class)

Sets the value of a document property.

Syntax

public void setDocumentProperty(String documentProperty, String value);

Remarks

This method is used to adjust properties of the document, including those that apply globally to every page from the current page onward. Together with GetDocumentProperty, this method provides an extensible way of managing the document settings that are not available through other means. The list of settings below may be extended in the future.

DocumentProperty and Value specify the document property and value to set respectively. Possible values for the former are:

Document property Default value Description
FooterFromBottom 36 The vertical offset of the footer from the bottom page border. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.
HeaderFromTop 36 The vertical offset of the header from the top page border. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.
MirrorFooters False Whether to automatically swap the left and right footers in double-sided documents. If enabled, the left and right footers will be mirrored on alternating pages.
MirrorHeaders False Whether to automatically swap the left and right headers in double-sided documents. If enabled, the left and right headers will be mirrored on alternating pages.
MirrorMargins False Whether to automatically swap the left and right margins in double-sided documents. If enabled, the left and right margins will be mirrored on alternating pages.
PageFooter "" The central footer text.
PageFooterFont Times New Roman The font name for the footer text.
PageFooterFontColor #000000 The font color for the footer text.
PageFooterFontSize 12 The font size for the footer text. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.
PageFooterFontStyle "" The font style for the footer text.
PageHeader "" The central header text.
PageHeaderFont Times New Roman The font name for the header text.
PageHeaderFontColor #000000 The font color for the header text.
PageHeaderFontSize 12 The font size for the header text. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.
PageHeaderFontStyle "" The font style for the header text.
PageLeftFooter "" The left footer text.
PageLeftHeader "" The left header text.
PageNumber 1 The starting page number in the header or footer.
PageNumberFormat Automatic The page number format. Supported values: Automatic, Alpha, AlphaCaps, Roman, RomanCaps, Numeric.
PageRightFooter "" The right footer text.
PageRightHeader "" The right header text.
Watermark "" The watermark text to be displayed.
WatermarkFont Times New Roman The font name for the watermark text.
WatermarkFontColor #BFBFBF The font color for the watermark text.
WatermarkFontSize "" The font size for the watermark text. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used. If empty, the watermark is automatically adjusted to fit the page.
WatermarkFontStyle "" The font style for the watermark text.
WatermarkStyle diagonal The style and placement of the watermark. Supported values: diagonal, horizontal, vertical, scattered, brickwork. The style can also include a direction separated by a space: NE/northeast, SE/southeast, NW/northwest, SW/southwest, N/north, S/south, E/east, W/west.
Xmp "" The XML body of the XMP metadata embedded in the document.
Xmp[property] "" The value of an XMP metadata property.
XmpStream "" The hex-encoded content of the XMP metadata stream.

Example: pdfgen.SetDocumentProperty("PageRightHeader", "PDF 32000-1:2008"); pdfgen.SetDocumentProperty("PageLeftFooter", "© Adobe Systems Incorporated 2008 - All rights reserved"); pdfgen.SetDocumentProperty("PageRightFooter", "%PAGENUMBER%"); pdfgen.SetDocumentProperty("PageNumberFormat", "Numeric");

SetFieldProperty Method (PDFGen Class)

Sets the value of a field property.

Syntax

public void setFieldProperty(String fieldName, String fieldProperty, String value);

Remarks

This method is used to modify the value of a field property. Together with GetFieldProperty, this method provides an extensible way of managing the field settings that are not available through other means. The list of settings below may be extended in the future.

FieldName is the name of the field of interest, and FieldProperty and Value specify the field property and value to set respectively. Possible values for the former are:

Field property Default value Description
AnnotationFlags 0 The field annotation flags.
AnnotationHidden False Whether the field annotation is completely invisible, meaning it cannot be displayed, printed, or interacted with.
AnnotationInvisible False Whether the field annotation is invisible on the screen and in print, but still remains interactive.
AnnotationLocked False Whether the user cannot modify the field annotation's properties, such as its position and size.
AnnotationLockedContents False Whether the user cannot modify the field annotation's contents.
AnnotationNoRotate False Whether the field annotation's orientation remains fixed regardless of the page rotation.
AnnotationNoView False Whether the field annotation is invisible on the screen and cannot be interacted with, but still appears when printed.
AnnotationNoZoom False Whether the field annotation's size remains fixed regardless of the page magnification level.
AnnotationPrint False Whether the field annotation appears when the page is printed.
AnnotationReadOnly False Whether the user cannot interact with or modify the field annotation.
AnnotationToggleNoView False Whether the field annotation's NoView flag is intended to be toggled dynamically by a user action or script.
Flags 0 The field flags.
IncludeEdit False Whether the combo box field includes an editable text box in addition to a drop-down list.
MultiLine False Whether the text box field can contain multiple lines of text.
MultiSelect False Whether multiple options can be selected simultaneously in the combo box or list box field.
NoExport False Whether the field is not exported when the form is submitted.
NoToggleToOff False Whether exactly one radio button in the radio group must always be selected.
Password False Whether the text box field is intended to contain a password.
ReadOnly False Whether the user cannot change the field's value.
Required False Whether the field must have a value before the form can be submitted.
Sort False Whether the options are automatically sorted alphabetically in the combo box or list box field.
UnisonSelect False Whether selecting one radio button automatically selects all other radio buttons in the same group that share the same field name and value for the on state.

SetFont Method (PDFGen Class)

Sets the font properties to be applied to text.

Syntax

public void setFont(String name, String size, String style, String color);

Remarks

This method is used to define the font attributes for text.

Name specifies the font name. Full font names (e.g., Times New Roman, Arial Bold Italic), filenames (e.g., times.ttf, arialbi.ttf), and full file paths are all supported.

The list of system TrueType font names that are supported by the class can be obtained from SystemFontNames.

Use FontPaths to specify font search paths when passing a TrueType font without a full file path. Alternatively, pass the full path of the TrueType font file to Name.

Size specifies the font size, either as an absolute value (e.g., 12) or relative adjustment (e.g., +2). Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

Style specifies the font style. The following syntax is supported:

[B][I][U][S][bold][italic][underline][strikethrough][##%][##%,##%][0.###][0.###]

For example:

  • bold
  • bold 50%
  • bold italic 50%
  • BI 50% 42%
  • B 50% italic 0.42
If only one transparency figure is provided, it applies to both pen and brush.

Color specifies the font color in hash-prefixed hexadecimal format (such as #FF0000 for red). The following HTML color aliases are also supported:

aliceblue antiquewhite aqua aquamarine
azure beige bisque black
blanchedalmond blue blueviolet brown
burlywood cadetblue chartreuse chocolate
coral cornflowerblue cornsilk crimson
cyan darkblue darkcyan darkgoldenrod
darkgray darkgrey darkgreen darkkhaki
darkmagenta darkolivegreen darkorange darkorchid
darkred darksalmon darkseagreen darkslateblue
darkslategray darkslategrey darkturquoise darkviolet
deeppink deepskyblue dimgray dimgrey
dodgerblue firebrick floralwhite forestgreen
fuchsia gainsboro ghostwhite gold
goldenrod gray grey green
greenyellow honeydew hotpink indianred
indigo ivory khaki lavender
lavenderblush lawngreen lemonchiffon lightblue
lightcoral lightcyan lightgoldenrodyellow lightgray
lightgrey lightgreen lightpink lightsalmon
lightseagreen lightskyblue lightslategray lightslategrey
lightsteelblue lightyellow lime limegreen
linen magenta maroon mediumaquamarine
mediumblue mediumorchid mediumpurple mediumseagreen
mediumslateblue mediumspringgreen mediumturquoise mediumvioletred
midnightblue mintcream mistyrose moccasin
navajowhite navy oldlace olive
olivedrab orange orangered orchid
palegoldenrod palegreen paleturquoise palevioletred
papayawhip peachpuff peru pink
plum powderblue purple rebeccapurple
red rosybrown royalblue saddlebrown
salmon sandybrown seagreen seashell
sienna silver skyblue slateblue
slategray slategrey snow springgreen
steelblue tan teal thistle
tomato turquoise violet wheat
white whitesmoke yellow yellowgreen

SetLayout Method (PDFGen Class)

Sets the layout for new pages.

Syntax

public void setLayout(String size, int colCount, int contentAnchor);

Remarks

This method is used to set the layout parameters for new pages to be added.

Size specifies the page size as an explicit dimension pair (e.g., 400 400 or 400, 400) in which the first value defines the width and the second defines the height. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

The following named sizes are also supported:

Letter 8.5 by 11 inches, equivalent to 612 792.
A4 210 by 297 millimeters, equivalent to 595 842.
A5 148 by 210 millimeters, equivalent to 420 595.

ColCount specifies the number of columns the page will be divided into. The only value that is currently supported is 1.

ContentAnchor is reserved for future use.

SetMargin Method (PDFGen Class)

Sets the margin for a typical element.

Syntax

public void setMargin(int marginType, String value);

Remarks

This method is used to specify the margin to apply when adding applicable elements.

MarginType specifies the type of margin to set. Possible values are:

0 (mtTableCellTop)
1 (mtTableCellBottom)
2 (mtTableCellLeft)
3 (mtTableCellRight)
4 (mtTableCellAll)
5 (mtPageTop)
6 (mtPageBottom)
7 (mtPageLeft)
8 (mtPageRight)
9 (mtPageAll)
10 (mtListItem)
11 (mtParagraphIndent)
12 (mtColumnGap) Currently unsupported.
13 (mtLineSpacing)

Value specifies the value of the margin. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

SetOutputStream Method (PDFGen Class)

Sets the stream to write the processed document to.

Syntax

public void setOutputStream(java.io.OutputStream outputStream);

Remarks

This method is used to set the stream to which the class writes the resulting PDF document. If an output stream is set before the class attempts to perform operations on the document, the class writes the data to the output stream instead of writing to OutputFile or populating OutputData.

NOTE: It may be useful to additionally set CloseOutputStreamAfterProcessing to true when using output streams.

SetPageProperty Method (PDFGen Class)

Sets the value of a page property.

Syntax

public void setPageProperty(String pageProperty, String value);

Remarks

This method is used to adjust properties of the current page, overriding the corresponding document-level properties set in SetDocumentProperty. Together with GetPageProperty, this method provides an extensible way of managing the current page settings that are not available through other means. The list of settings below may be extended in the future.

PageProperty and Value specify the page property and value to set respectively. Possible values for the former are:

Page property Default value Description
PageFooter "" The central footer text.
PageFooterFont Times New Roman The font name for the footer text.
PageFooterFontColor #000000 The font color for the footer text.
PageFooterFontSize 12 The font size for the footer text.
PageFooterFontStyle "" The font style for the footer text.
PageHeader "" The central header text.
PageHeaderFont Times New Roman The font name for the header text.
PageHeaderFontColor #000000 The font color for the header text.
PageHeaderFontSize 12 The font size for the header text.
PageHeaderFontStyle "" The font style for the header text.
PageLeftFooter "" The left footer text.
PageLeftHeader "" The left header text.
PageNumber 1 The page number in the header or footer.
PageNumberFormat Automatic The page number format. Supported values: Automatic, Alpha, AlphaCaps, Roman, RomanCaps, Numeric.
PageRightFooter "" The right footer text.
PageRightHeader "" The right header text.
Watermark "" The watermark text to be displayed.
WatermarkFont Times New Roman The font name for the watermark text.
WatermarkFontColor #BFBFBF The font color for the watermark text.
WatermarkFontSize "" The font size for the watermark text. If empty, the watermark is automatically adjusted to fit the page.
WatermarkFontStyle "" The font style for the watermark text.
WatermarkStyle diagonal The style and placement of the watermark. Supported values: diagonal, horizontal, vertical, scattered, brickwork. The style can also include a direction separated by a space: NE/northeast, SE/southeast, NW/northwest, SW/southwest, N/north, S/south, E/east, W/west.

Example: pdfgen.SetPageProperty("PageRightHeader", "PDF 32000-1:2008 (revised)");

SetPen Method (PDFGen Class)

Sets the stroke properties used when drawing lines, paths, and borders.

Syntax

public void setPen(String thickness, String style, String color, String opacity);

Remarks

This method is used to configure the pen that is applied to all subsequently added paths, shapes, and table borders.

Thickness specifies the stroke width. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

Style controls the dash pattern, line cap, and line join of the stroke via one or more keywords, which may appear in any order.

The following dash pattern keywords are supported:

solid A continuous unbroken line. This is the default when no dash pattern keyword is present.
dashed A line broken into equal-length dashes, equivalent to -.
dotted A line broken into short dots, equivalent to ..
dash-dot An alternating dash-dot pattern, equivalent to -..

A custom pattern can also be specified directly as a sequence of - and . characters, allowing any combination such as --. or --.-..

The following line cap keywords are supported:

butt cap A flat cap ending exactly at the endpoint.
round cap A semicircular cap extending beyond the endpoint by half the line width.
square cap A square cap extending beyond the endpoint by half the line width.

The following line join keywords are supported:

miter join limit A sharp pointed join. The optional numeric limit value immediately following the keyword sets the miter limit; when omitted, the PDF default is used.
round join A rounded join.
bevel join A flat beveled join.

Example Style strings:

dashed round cap round join A dashed line with round caps and round joins.
dotted butt cap miter join 4 A dotted line with butt caps and a miter limit of 4.
--. square cap bevel join A custom dash-dash-dot pattern with square caps and bevel joins.

Color specifies the stroke color. For the full list of supported colors, see SetFont.

Opacity specifies the stroke opacity as a value between 0 (fully transparent) and 1 (fully opaque). If empty, full opacity is used.

SetStyle Method (PDFGen Class)

Applies a previously saved style or one of the built-in styles.

Syntax

public void setStyle(String styleId);

Remarks

This method is used to apply the style identified by StyleId, which may be either a style previously saved with SaveStyle or one of the below built-in styles. Style Ids are case-insensitive, and this method throws an exception if no style with the given Id exists. Applying a style sets the font it recorded, together with the pen and brush if the style recorded them.

The following built-in styles are supported. They change only the size and boldness of the font, keeping the font family and color:

Style Font style Font size
Title bold 2.2em
H1 bold 2em
H2 bold 1.7em
H3 bold 1.5em
H4 bold 1.3em
H5 bold 1.15em
H6 bold 1em
P normal Base font's size (in points)

Additionally, Default resets the font, pen, and brush to their default values.

The heading sizes are relative to the base font size, which is the value most recently set with SetFont, not the value most recently applied by this method. Applying a style never changes the base font.

Example: pdfgen.SetFont("Arial", "12", "", ""); // the base font pdfgen.SetStyle("H1"); pdfgen.AddParagraph("Chapter One"); // a large bold Arial heading (2em) pdfgen.SetStyle("P"); pdfgen.AddParagraph("Body text..."); // back to 12pt regular Arial pdfgen.SetStyle("Default"); // Times New Roman 12pt, default pen and brush

StartComboBox Method (PDFGen Class)

Begins a new combo box field for editing.

Syntax

public void startComboBox(String fieldName, String width, String height);

Remarks

This method is used to create a blank combo box field with name FieldName.

Width and Height specify the width and height of the combo box. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

After calling this method, use AddListItem to add choices to the combo box. When finished, call EndComboBox to complete it.

To create a combo box all at once instead of incrementally, use AddComboBox.

On a text canvas, the element is placed in the normal flow of content. On a drawing canvas, it is placed at the current pen position as set by MoveTo.

NOTE: This method throws an exception if a list is currently being edited.

StartContent Method (PDFGen Class)

Begins a new logical section.

Syntax

public void startContent(int contentType, String title, String attributes);

Remarks

This method is currently unsupported.

StartDrawing Method (PDFGen Class)

Initiates a new drawing canvas of the given dimensions.

Syntax

public void startDrawing(String width, String height);

Remarks

This method is used to create a new drawing canvas with size specified by Width and Height. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

A drawing canvas accepts vector drawing primitives such as paths, rectangles, circles, and polygons, and can also host bitmaps and nested canvases. All coordinates used within the drawing canvas are relative to its bottom-left corner.

The current Pen and Brush are inherited by the drawing canvas and applied to each new path unless overridden before the path is started. Use SetPen and SetBrush before calling path methods to control stroke and fill.

When finished editing the drawing canvas, call EndDrawing to close it and optionally save it in the class.

NOTE: This method throws an exception if a list is currently being edited.

StartEditing Method (PDFGen Class)

Initiates a new text canvas for editing.

Syntax

public void startEditing(String width, String height, int contentAnchor);

Remarks

This method is used to create a blank text canvas with minimum and/or maximum dimensions specified by Width and Height. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

Width and Height operate the [preferred]:[min]:[max] syntax. For example:

:100: Minimum only.
:400:400 Minimum and maximum.
::612 or 612 Maximum only.

If the minimum is empty or 0, no minimum width is enforced.

ContentAnchor is reserved for future use.

When finished editing the text canvas, call EndEditing to close it and optionally save it in the class.

Upon completion of this method, information about the newly created text canvas can be accessed using the Canvas property.

NOTE: This method throws an exception if a list is currently being edited.

StartForm Method (PDFGen Class)

Begins a new form.

Syntax

public void startForm(String submitURL);

Remarks

This method is used to explicitly create a form. In general, it is not necessary to call this method before adding new fields via AddButton, AddCheckBox, AddRadioButton, and similar methods, as a form is created implicitly when the document is saved.

SubmitURL specifies the URL to which the form data is sent when a submit-form action is executed. Use AddButton to add a button that invokes this type of action when pressed.

When finished editing the form, call EndForm to complete it.

NOTE: This method throws an exception if the current canvas is not a text canvas.

StartList Method (PDFGen Class)

Begins a new list for editing.

Syntax

public void startList(int marker);

Remarks

This method is used to create an empty list. If a list with at least one item is already being edited, a sublist is created.

Marker specifies the character that will precede each item in the list. Possible values are:

0 (lmOrdered)
1 (lmUnordered)
2 (lmNumeric)
3 (lmAlpha)
4 (lmAlphaCaps)
5 (lmRoman)
6 (lmRomanCaps)
7 (lmCircle)
8 (lmBlackCircle)
9 (lmBlackSquare)
10 (lmDash)
11 (lmCustom)

After calling this method, use AddListItem (or StartListItem and EndListItem) to add items to the list. When finished, call EndList to complete it and optionally save it in the class.

NOTE: This method throws an exception if the current canvas is not a text canvas.

StartListBox Method (PDFGen Class)

Begins a new list box field for editing.

Syntax

public void startListBox(String fieldName, String width, String height);

Remarks

This method is used to create a blank list box field with name FieldName.

Width and Height specify the width and height of the list box. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

After calling this method, use AddListItem to add choices to the list box. When finished, call EndListBox to complete it.

To create a list box all at once instead of incrementally, use AddListBox.

NOTE: This method throws an exception if a list is currently being edited.

StartListItem Method (PDFGen Class)

Begins a new list item for editing.

Syntax

public void startListItem();

Remarks

This method is used to create a placeholder for a list item as a text canvas. If a list item is already being edited, it is automatically completed before the new one is started.

After calling this method, use AddText or AddParagraph to populate the list item with text content. When finished, call EndListItem to close the underlying text canvas and optionally save it in the class.

To create a list item all at once instead of incrementally, use AddListItem.

NOTE: This method throws an exception if the current canvas is not a text canvas or if a list is not currently being edited.

StartParagraph Method (PDFGen Class)

Begins a new paragraph for editing.

Syntax

public void startParagraph();

Remarks

This method is used to create an empty paragraph. Content added between this method and EndParagraph, such as text, links, and images, flows into the current canvas.

When finished editing the paragraph, call EndParagraph to complete it and optionally save it in the class.

To create a paragraph all at once instead of incrementally, use AddParagraph.

NOTE: This method throws an exception if a list is currently being edited.

StartPath Method (PDFGen Class)

Starts a new vector path on the drawing canvas.

Syntax

public void startPath(int drawingMode);

Remarks

This method is used to begin a new path on the current drawing canvas, starting at the current pen position as set by MoveTo. All coordinates on a drawing canvas are relative to its bottom-left corner.

DrawingMode specifies how the path interacts with the canvas when it is closed with EndPath. Possible values are:

0 (dmDrawing) The path is rendered as a filled and/or stroked shape.
1 (dmClipping) The path defines a clipping region; subsequent drawing is masked to the interior of this path.
2 (dmMask) Reserved for future use.

The Pen and Brush active when this method is called determine the stroke color, stroke width, line style, and fill color for the path.

When finished with the path, call EndPath to complete it and optionally save it in the class.

NOTE: This method throws an exception if the current canvas is not a drawing canvas or if a list is currently being edited.

StartSignatureField Method (PDFGen Class)

Begins a new signature field for editing.

Syntax

public void startSignatureField(String fieldName, String width, String height, boolean drawing);

Remarks

This method is used to create a blank signature field with name FieldName as either a text or drawing canvas.

Width and Height specify the width and height of the signature field. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

Drawing specifies whether the signature field will be a drawing canvas.

When finished editing the signature field, call EndSignatureField to close the underlying canvas and optionally save it in the class.

To create a signature field all at once instead of incrementally, use AddSignatureField.

NOTE: This method throws an exception if a list is currently being edited.

StartTable Method (PDFGen Class)

Initiates a new table canvas with a fixed number of columns.

Syntax

public void startTable(int colCount, String width);

Remarks

This method is used to create a new table canvas with ColCount columns. The table accumulates rows and cells until EndTable is called, at which point the layout is resolved and the table is committed to the parent canvas.

ColCount specifies the number of logical columns in the table. This value must be positive and cannot be changed after the table is started.

Width specifies the width constraints of the table. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

This parameter operates the [preferred]:[min]:[max] syntax. For example:

:100: Minimum only.
:400:400 Minimum and maximum.
::612 or 612 Maximum only.

If the minimum is empty or 0, no minimum width is enforced. If the maximum is empty or 0, the table may expand to fit its content without an upper bound.

The current Pen and Brush are inherited by the table and used to draw its outer border and background. Use SetPen and SetBrush before calling this method to control the table border style and fill color. Individual cells may override these settings.

After calling this method, use StartTableRow to begin adding rows, and use AddTableCell or StartTableCell to populate each row with content. When finished editing the table, call EndTable to close the underlying table canvas and optionally save it in the class.

NOTE: This method throws an exception if a list is currently being edited.

StartTableCell Method (PDFGen Class)

Begins a new cell in the current table row.

Syntax

public void startTableCell(String width, int colSpan, int rowSpan, int borders, int contentAnchor);

Remarks

This method is used to open a new cell in the current row of the table canvas. Any previously opened cell in the same row is automatically closed before the new one is started.

Width specifies the cell width constraints. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

This parameter operates the [preferred]:[min]:[max] syntax. For example:

200 Preferred only.
200:50 Preferred and minimum.
200::400 Preferred and maximum.
:50: Minimum only.
::400 Maximum only.
200:50:400 Preferred, minimum, and maximum.

If the preferred width is empty or 0, the width is either inherited from the corresponding cell in the previous row or determined automatically during layout. If the minimum is empty or 0, it defaults to twice the cell padding. If the maximum is empty or 0, no maximum width is enforced.

ColSpan specifies the number of columns the cell spans horizontally. Values that would extend the cell beyond the table boundary are clamped automatically.

RowSpan specifies the number of rows the cell spans vertically. Cells covered by a rowspan from a previous row are automatically skipped when advancing through the current row.

Borders specifies which borders of the cell are suppressed. Its value should be provided as a bitmask of the following flags:

0x001 Top border
0x002 Right border
0x004 Bottom border
0x008 Left border

Pass 0 to show all borders.

ContentAnchor is reserved for future use.

The current Pen and Brush are applied to the cell background and borders. Use SetPen and SetBrush before calling this method to style individual cells.

After calling this method, add content to the cell using AddParagraph, AddText, AddBitmap, or any other method applicable to a text canvas. When finished editing the cell, call EndTableCell to close it explicitly and optionally save it in the class, or begin a new cell with StartTableCell to close it implicitly.

To create a table cell all at once instead of incrementally, use AddTableCell.

NOTE: This method throws an exception if the current canvas is not a table canvas.

StartTableRow Method (PDFGen Class)

Begins a new row in the current table.

Syntax

public void startTableRow(String height, boolean isHeader);

Remarks

This method is used to open a new row in the current table canvas. Any previously opened row is automatically closed before the new one is started.

Height specifies the row height constraints. Both integer and decimal values are supported, as are the pt, cm, mm, in, em, and % units (e.g., 5cm or 50%). If no unit is provided, points are used.

This parameter operates the [preferred]:[min]:[max] syntax. For example:

200 Preferred only.
200:50 Preferred and minimum.
200::400 Preferred and maximum.
:50: Minimum only.
::400 Maximum only.
200:50:400 Preferred, minimum, and maximum.

If the preferred height is empty or 0, the row height is determined automatically from the tallest cell it contains. If the minimum is empty or 0, the row may be as short as its content. If the maximum is empty or 0, no maximum height is enforced; otherwise, content that exceeds this height is clipped.

IsHeader specifies whether the row is a header row. This parameter is recorded for informational purposes and future use; it does not currently alter rendering behavior.

After calling this method, add cells to the row using AddTableCell or StartTableCell. When finished editing the row, call EndTableRow to close it explicitly and optionally save it in the class, or begin a new row with StartTableRow to close it implicitly.

NOTE: This method throws an exception if the current canvas is not a table canvas.

ActionRequired Event (PDFGen Class)

Fired when the class encounters a conflict that it cannot resolve on its own.

Syntax

public class DefaultPDFGenEventListener implements PDFGenEventListener {
  ...
  public void actionRequired(PDFGenActionRequiredEvent e) {}
  ...
}

public class PDFGenActionRequiredEvent {
  public String action;
  public String choice; //read-write
}

Remarks

This event is reserved for scenarios where the class needs input from the user to resolve an editing conflict. Currently there are no defined conflicts, so this event does not fire.

EditingCompleted Event (PDFGen Class)

Fired after a canvas has been closed.

Syntax

public class DefaultPDFGenEventListener implements PDFGenEventListener {
  ...
  public void editingCompleted(PDFGenEditingCompletedEvent e) {}
  ...
}

public class PDFGenEditingCompletedEvent {
  public int canvasType;
  public String canvasId;
  public String width;
  public String height;
  public String X;
  public String Y;
}

Remarks

This event is currently unsupported.

Error Event (PDFGen Class)

Fired when information is available about errors during data delivery.

Syntax

public class DefaultPDFGenEventListener implements PDFGenEventListener {
  ...
  public void error(PDFGenErrorEvent e) {}
  ...
}

public class PDFGenErrorEvent {
  public int errorCode;
  public String description;
}

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the class throws an exception.

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

FontLookup Event (PDFGen Class)

Fired when a required font is missing.

Syntax

public class DefaultPDFGenEventListener implements PDFGenEventListener {
  ...
  public void fontLookup(PDFGenFontLookupEvent e) {}
  ...
}

public class PDFGenFontLookupEvent {
  public String fontName;
  public String fontPath; //read-write
}

Remarks

This event is fired from within SetFont or Close to report that the font identified by FontName was not found in FontPaths. It may be used to provide substitute fonts on the fly as an extension to the FallbackFont configuration setting.

FontPath specifies the absolute path to the substitute font file. If empty, the substitute font defaults to FallbackFont, which can also be adjusted within the event handler for each missing font.

Example: component.OnFontLookup += (s, e) => { if (e.FontName == "Helvetica") { component.Config("FallbackFont=Arial"); } else { component.Config("FallbackFont=Times New Roman"); } };

Log Event (PDFGen Class)

Fired once for each log message.

Syntax

public class DefaultPDFGenEventListener implements PDFGenEventListener {
  ...
  public void log(PDFGenLogEvent e) {}
  ...
}

public class PDFGenLogEvent {
  public int logLevel;
  public String message;
  public String logType;
}

Remarks

This event is fired once for each log message generated by the class. The verbosity is controlled by the LogLevel configuration setting.

LogLevel indicates the detail level of the message. Possible values are:

0 (None) No messages are logged.
1 (Info - default) Informational events such as the basics of the chain validation procedure are logged.
2 (Verbose) Detailed data such as HTTP requests are logged.
3 (Debug) Debug data including the full chain validation procedure are logged.

Message is the log message.

LogType identifies the type of log entry. Possible values are:

  • CertValidator
  • Font
  • HTTP
  • PDFInvalidSignature
  • PDFRevocationInfo
  • Timestamp
  • TSL

OutOfSpace Event (PDFGen Class)

Fired when an element exceeds the maximum dimensions of the current text canvas.

Syntax

public class DefaultPDFGenEventListener implements PDFGenEventListener {
  ...
  public void outOfSpace(PDFGenOutOfSpaceEvent e) {}
  ...
}

public class PDFGenOutOfSpaceEvent {
  public int spaceKind;
  public String widthAvailable;
  public String widthNeeded;
  public String heightAvailable;
  public String heightNeeded;
  public int choice; //read-write
}

Remarks

This event is fired while the class populates the text canvas to report that the content does not fit within the canvas boundaries. It can be fired from within:

SpaceKind identifies the kind of space the element has exceeded as a bitmask of the following flags:

0x001 (skWidth) The element is too wide to place within the MaxWidth of the canvas.
0x002 (skHeight) Adding the element would extend the height of the canvas beyond its MaxHeight.

WidthAvailable and HeightAvailable report the remaining width and height of the canvas in points.

WidthNeeded and HeightNeeded report the width and height of the element in points.

Choice specifies the decision requested of the class. Possible values:

0 (oscExpand) Automatically expand the canvas by just enough width and/or height to accommodate the element.
1 (oscWrap) Start a new page and place the element on the new page canvas.
2 (oscRetry) Retry the operation with a resized canvas. Use the Canvas property to adjust the MaxWidth and/or MaxHeight of the canvas within the event handler.
3 (oscSave) Currently unsupported.
4 (oscCancel) Cancel the operation as if the method that directly caused the event invocation was never called. Use this option to retry a compound method, such as EndDrawing, and complete the operation with different parameters (e.g., by applying a smaller scale to a bitmap that is too large).
5 (oscFullCancel) Cancel the compound operation entirely (i.e., both the End* call and its preceding Start* call).
6 (oscAbort - default) Cancel the operation and throw an exception.

NOTE: This event may fire repeatedly if the action the class is instructed to take does not adequately resolve the conflict.

PDFAttachment Type

The file being attached to the PDF document.

Remarks

This type contains information about the file that is being attached to the document.

The following fields are available:

Fields

AFRelationship
String

Default Value: ""

The value of the AFRelationship key for the attachment, for example Alternative or Source.

This key in the file specification dictionary expresses the relationship between the attachment and the document, and it must be set for each attachment added to PDF/A-3 documents.

AttachmentType
int (read-only)

Default Value: 0

The type of the attachment.

Possible values are:

0 (patGeneric - default) A generic attachment.
1 (patElectronicInvoice) An XML invoice, for example in ZUGFeRD or Factur-X format.

ContentType
String

Default Value: ""

The content type of the attachment.

CreationDate
String

Default Value: ""

The creation date of the attachment.

Data
String

Default Value: ""

The raw data of the attachment.

If OutputStream is not set to a valid stream, the class writes to this field when an empty string is passed to SaveAttachment.

DataB
byte[]

Default Value: ""

The raw data of the attachment.

If OutputStream is not set to a valid stream, the class writes to this field when an empty string is passed to SaveAttachment.

Description
String

Default Value: ""

A textual description of the attachment.

FileName
String

Default Value: ""

The path and filename of the attachment.

InputStream
java.io.InputStream

Default Value: ""

A stream containing the attachment.

If this field is set to a valid stream, the class attaches the data from the stream as the current attachment.

ModificationDate
String

Default Value: ""

The date and time of the file's last modification.

Name
String

Default Value: ""

The name of the attachment.

OutputStream
java.io.OutputStream

Default Value: ""

The stream to write the attachment to.

If this field is set to a valid stream, the class writes to the stream when an empty string is passed to SaveAttachment.

Size
long (read-only)

Default Value: 0

The attachment's size in bytes.

Constructors

public PDFAttachment();
public PDFAttachment(String fileName);
public PDFAttachment(String fileName, String description);
public PDFAttachment(String fileName, String description, int attachmentType);
public PDFAttachment(byte[] data, String name, String description);
public PDFAttachment(byte[] data, String name, String description, int attachmentType);
public PDFAttachment(java.io.InputStream inputStream, String name, String description);
public PDFAttachment(java.io.InputStream inputStream, String name, String description, int attachmentType);

PDFBrush Type

The fill configuration used when rendering shapes and cell backgrounds.

Remarks

This type encapsulates the fill properties applied to the interior of closed paths, rectangles, circles, polygons, and table cell backgrounds. It stores a single solid color and an opacity value.

The following fields are available:

Fields

Color
String (read-only)

Default Value: "#FFFFFF"

The fill color of the brush in hash-prefixed hexadecimal format or as a name.

Note that a brush with the default color will not produce a visible fill until it has been explicitly activated via SetBrush.

Opacity
String (read-only)

Default Value: ""

The opacity of the brush fill, from 0 (fully transparent) to 1 (fully opaque).

Constructors

public PDFBrush();

PDFCanvas Type

Details about the current canvas.

Remarks

This type contains information about the canvas that is currently being edited.

The following fields are available:

Fields

CanvasType
int (read-only)

Default Value: 0

The type of the canvas.

Possible values are:

0 (ctPage - default)
1 (ctText)
2 (ctDrawing)
3 (ctTable)
4 (ctTableCell)
5 (ctSignatureField)

This field is also available as a parameter of the EditingCompleted event.

ContentAnchor
int (read-only)

Default Value: 0

This field is currently unsupported.

Drawing
boolean (read-only)

Default Value: False

Whether the canvas is a random-access drawing canvas.

DrawingMode
int (read-only)

Default Value: 0

How paths interact with the drawing canvas.

Possible values are:

0 (dmDrawing) The path is rendered as a filled and/or stroked shape.
1 (dmClipping) The path defines a clipping region; subsequent drawing is masked to the interior of this path.
2 (dmMask) Reserved for future use.

Height
String (read-only)

Default Value: "0"

The current height of the canvas in points.

This field is also available as a parameter of the EditingCompleted event.

HorizontalAlignment
int (read-only)

Default Value: 0

The current horizontal alignment for text content in the text canvas.

Possible values are:

0 (haLeft - default)
1 (haCenter)
2 (haRight)
3 (haJustify)

MaxHeight
String

Default Value: "0"

The maximum height of the canvas in points. Both integer and decimal values are supported.

MaxWidth
String

Default Value: "0"

The maximum width of the canvas in points. Both integer and decimal values are supported.

MinHeight
String (read-only)

Default Value: "0"

The minimum height of the canvas in points.

MinWidth
String (read-only)

Default Value: "0"

The minimum width of the canvas in points.

VerticalAlignment
int (read-only)

Default Value: 0

The current vertical alignment for text content in the text canvas.

Possible values are:

0 (vaTop - default)
1 (vaCenter)
2 (vaBottom)

Width
String (read-only)

Default Value: "0"

The current width of the canvas in points.

This field is also available as a parameter of the EditingCompleted event.

X
String (read-only)

Default Value: "0"

The X coordinate of the canvas in points.

This field is also available as a parameter of the EditingCompleted event.

Y
String (read-only)

Default Value: "0"

The Y coordinate of the canvas in points.

This field is also available as a parameter of the EditingCompleted event.

Constructors

public PDFCanvas();

PDFFont Type

The font used in the PDF document.

Remarks

This type contains details about the font being applied to text.

The following fields are available:

Fields

Color
String (read-only)

Default Value: "#000000"

The color of the current font in hash-prefixed hexadecimal format or as a name.

Name
String (read-only)

Default Value: "Times New Roman"

The name of the current font.

Path
String (read-only)

Default Value: ""

The full file path to the current font, for example C:\Windows\Fonts\times.ttf.

This field returns an empty string if a built-in font is in use.

Size
String (read-only)

Default Value: "12"

The size of the current font in points.

Style
String (read-only)

Default Value: ""

The style of the current font.

Constructors

public PDFFont();

PDFPageLayout Type

Details about the page layout.

Remarks

This type contains information about the layout of a page in the document.

The following fields are available:

Fields

ColCount
int (read-only)

Default Value: 1

The number of columns on the page.

ContentAnchor
int (read-only)

Default Value: 0

This field is currently unsupported.

Height
String (read-only)

Default Value: "792"

The height of the page in points.

Size
String (read-only)

Default Value: ""

The size of the page. Please see SetLayout for more details.

Width
String (read-only)

Default Value: "612"

The width of the page in points.

Constructors

public PDFPageLayout();

PDFPen Type

The stroke configuration used when rendering paths and borders.

Remarks

This type encapsulates the stroke properties applied when drawing lines, path outlines, table borders, and any other stroked element in a PDF document.

The following fields are available:

Fields

Color
String (read-only)

Default Value: "#000000"

The stroke color of the pen in hash-prefixed hexadecimal format or as a name.

Opacity
String (read-only)

Default Value: ""

The opacity of the pen stroke, from 0 (fully transparent) to 1 (fully opaque).

Style
String (read-only)

Default Value: ""

The style of the pen.

Thickness
String (read-only)

Default Value: ""

The line width of the pen stroke in points.

Constructors

public PDFPen();

Config Settings (PDFGen Class)

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

PDFGen Config Settings

AutoTurnPages:   Whether to change the page automatically upon exceeding the lower page boundary.

This setting specifies whether the class turns the page automatically. If set to true, the class automatically progresses to the next page upon reaching a lower page boundary while populating the current page canvas. If set to false, the OutOfSpace event fires for any elements that do not fit on the current page. The default value is true.

CloseOutputStreamAfterProcessing:   Whether to close the output stream after processing.

This setting determines whether the output stream specified in SetOutputStream will be closed after processing is complete. The default value is true.

CompressStreams:   Whether to compress stream objects.

This setting specifies whether the bytes in the document's stream objects are compressed when the document is saved. The default value is false.

FallbackFont:   The fallback font.

This setting specifies the font that the class uses if it cannot find the intended font on the local system. In PDF/A, fonts must be embedded into the document, so this setting can be useful when text must be added but the font is not available. The default value is Times New Roman.

FontPaths:   The font search paths.

This setting specifies a CRLF-separated list of directories where the class searches for additional TrueType font files. It is used when resolving a TrueType font specified in SetFont without a full file path.

Each entry is interpreted as a directory path used during font lookup. To use a specific TrueType font file, either specify its filename and include the containing directory in this setting, or specify the full file path in SetFont.

The default value is the system font search paths. These paths are platform-dependent:

Windows %windir%\Fonts and %LOCALAPPDATA%\Microsoft\Windows\Fonts
macOS and iOS /System/Library/Fonts/, /System/Library/Fonts/Supplemental/, /Library/Fonts/, and ~/Library/Fonts/
Linux Directories listed by dir entries in /etc/fonts/fonts.conf and /usr/local/etc/fonts/fonts.conf
Android /system/fonts

On Windows, the .NET and Java editions obtain these locations through the runtime APIs or the windir, SystemRoot, and LOCALAPPDATA environment variables.

To use custom directories together with the default system locations, include both to prevent the current search path list from being replaced. For example: string fontPaths = component.Config("FontPaths"); fontPaths += @"\r\nC:\Fonts"; component.Config("FontPaths=" + fontPaths);

FontPolicy:   The font policy to follow.

This setting specifies the font policy the class follows when choosing a font, either implicitly or explicitly via SetFont. Possible values are:

TrueTypeOnly Use TrueType fonts only (e.g., Times New Roman instead of Times-Roman).
PreferTrueType (default) Use the TrueType version of the font if available; otherwise, use the corresponding built-in font.
PreferBuiltIn Use the built-in version of the font if it exists; otherwise, use the TrueType font.
BuiltInOnly Use built-in fonts only. If the desired font is only available as a TrueType font, the class throws an exception.

The 14 built-in (Type 1) fonts in PDF are: Times-Roman, Helvetica, Courier, Symbol, Times-Bold, Helvetica-Bold, Courier-Bold, ZapfDingbats, Times-Italic, Helvetica-Oblique, Courier-Oblique, Times-BoldItalic, Helvetica-BoldOblique, Courier-BoldOblique.

NOTE: If set to BuiltInOnly and PDFAConformanceLevel is not set to paclNone, the class throws an exception. This is because PDF/A requires the use of file-based TrueType fonts that can be embedded into the document.

LogLevel:   The level of detail that is logged.

This setting controls the level of detail that is logged through the Log event. Possible values are:

0 (None) No messages are logged.
1 (Info - default) Informational events such as the basics of the chain validation procedure are logged.
2 (Verbose) Detailed data such as HTTP requests are logged.
3 (Debug) Debug data including the full chain validation procedure are logged.
SaveChanges:   Whether to save changes made to the document.

This setting specifies whether and how changes made to the PDF document are saved when Close is called. Possible values are:

0 Discard all changes.
1 Save the document to OutputFile, OutputData, or the stream set in SetOutputStream, even if it has not been modified.
2 (default) Save the document to OutputFile, OutputData, or the stream set in SetOutputStream, but only if it has been modified.
SystemFontNames:   The system font names.

This setting returns a CRLF-separated list of system TrueType font names that are supported by the class. This setting is read-only.

TempPath:   The location where temporary files are stored.

This setting specifies an absolute path to the location on disk where temporary files are stored. It can be useful to reduce memory usage.

UsedFonts:   The fonts used in the document.

This setting returns a CRLF-separated list of all the fonts used in the opened document. This setting is read-only.

Base Config Settings

BuildInfo:   Information about the product's build.

When queried, this setting will return a string containing information about the product's build.

GUIAvailable:   Whether or not a message loop is available for processing events.

In a GUI-based application, long-running blocking operations may cause the application to stop responding to input until the operation returns. The class will attempt to discover whether or not the application has a message loop and, if one is discovered, it will process events in that message loop during any such blocking operation.

In some non-GUI applications, an invalid message loop may be discovered that will result in errant behavior. In these cases, setting GUIAvailable to false will ensure that the class does not attempt to process external events.

LicenseInfo:   Information about the current license.

When queried, this setting will return a string containing information about the license this instance of a class is using. It will return the following information:

  • Product: The product the license is for.
  • Product Key: The key the license was generated from.
  • License Source: Where the license was found (e.g., RuntimeLicense, License File).
  • License Type: The type of license installed (e.g., Royalty Free, Single Server).
  • Last Valid Build: The last valid build number for which the license will work.
MaskSensitiveData:   Whether sensitive data is masked in log messages.

In certain circumstances it may be beneficial to mask sensitive data, like passwords, in log messages. Set this to true to mask sensitive data. The default is true.

UseDaemonThreads:   Whether threads created by the class are daemon threads.

If set to True (default), when the class creates a thread, the thread's Daemon property will be explicitly set to True. When set to False, the class will not set the Daemon property on the created thread. The default value is True.

UseInternalSecurityAPI:   Whether or not to use the system security libraries or an internal implementation.

When set to false, the class will use the system security libraries by default to perform cryptographic functions where applicable.

Setting this configuration setting to true tells the class to use the internal implementation instead of using the system security libraries.

This setting is set to false by default on all platforms.

UseVirtualThreads:   Whether threads created by the class use virtual threads instead of platform threads.

If set to true, when the class creates a thread, it will be created as a virtual thread instead of a platform thread. Virtual threads are lightweight threads managed by the JVM that are multiplexed onto a small pool of carrier threads, significantly reducing memory usage and platform thread count under high-concurrency workloads. Requires Java 24 or later. The default value is false.

Trappable Errors (PDFGen Class)

PDFGen Errors

1401   The current canvas does not support this operation.
1402   Cannot commit canvas that is still open.
1403   Invalid choice.
1404   Text canvas is not started.
1405   Page margins are too large for the current layout.
1406   Not enough space for the element.
1407   Field with specified name not found.
1408   Cannot save canvas containing form fields.
1409   The document already contains a form. Only one form per document is allowed.
1410   Form is not started.
1411   Form has already been closed.

PDF Errors

804   PDF decompression failed.
805   Cannot add entry to cross-reference table.
806   Unsupported field size.
807   Unsupported Encoding filter.
808   Unsupported predictor algorithm.
809   Unsupported document version.
812   Cannot read PDF file stream.
813   Cannot write to PDF file stream.
814   OutputFile already exists and Overwrite is false.
815   Invalid parameter.
817   Bad cross-reference entry.
818   Invalid object or generation number.
819   Invalid object stream.
820   Invalid stream dictionary.
821   Invalid AcroForm entry.
822   Invalid Root entry.
823   Invalid annotation.
824   The input document is empty.
826   OpenType font error. The error description contains the detailed message.
828   Invalid CMS data. The error description contains the detailed message.
835   Cannot change decryption mode for opened document.
836   Unsupported Date string.
838   Cryptographic error. The error description contains the detailed message.
840   DecryptionCert error. The error description contains the detailed message.
841   Encryption failed. The error description contains the detailed message.
842   No proper certificate for encryption found.
846   Unsupported revision.
847   Unsupported security handler SubFilter.
848   Failed to verify permissions.
849   Invalid password.
850   Invalid password information.
852   Unsupported encryption algorithm.
859   Cannot encrypt encrypted document.
864   Cannot modify document after signature update.
868   Cannot encrypt or decrypt object.
869   Invalid security handler information.
870   Invalid encrypted data.
871   Invalid block cipher padding.
872   Failed to reload signature.
873   Object is not encrypted.
874   Unexpected cipher information.
877   Invalid document. Bad document catalog.
878   Invalid document Id.
880   Invalid document. Invalid requirements dictionary.
881   Invalid linearization dictionary.
882   Invalid signature information.
883   Unsupported document format.
890   Unsupported feature.
891   Internal error. The error description contains the detailed message.
892   Unsupported color.
893   This operation is not supported for this PDF/A level.
894   Interactive features (Action) are not supported by PDF/A. Set PDFAConformanceLevel to paclNone or clear the Action property of the field.
895   Font file not found.
896   Invalid font name. The error description contains the detailed message.

Parsing Errors

1001   Bad object.
1002   Bad document trailer.
1003   Illegal stream dictionary.
1004   Illegal string.
1005   Indirect object expected.
1007   Invalid reference.
1008   Invalid reference table.
1009   Invalid stream data.
1010   Unexpected character.
1011   Unexpected EOF.
1012   Unexpected indirect object in cross-reference table.
1013   RDF object not found.
1014   Invalid RDF object.
1015   Cannot create element with unknown prefix.
1021   Invalid type in Root object list.