GcPdfDocument Class

Represents a PDF document.

The object model provided by this class follows the PDF 1.7 Reference specification.

Inheritance

GcPdfDocument

Namespace: GrapeCity.Documents.Pdf

Assembly: DS.Documents.Pdf.dll

Syntax

public class GcPdfDocument

Public Class GcPdfDocument

Remarks

To create a PDF document, create an instance of the GcPdfDocument class.

Two approaches are possible for adding content and saving the document:

Direct modeIn this mode, you add pages to the document and draw on them (see below) in arbitrary order. In particular, you can modify pages that have been already created. When done, use Save(Stream, bool) or Save(string, bool) method to save the document. This mode is convenient but uses temporary files, so is somewhat less efficient than sequential mode described next.
Sequential mode To use this mode, you call StartDoc(Stream) prior to any other operations on the document. You can then add pages and draw on them, but you can only draw on the last (current) page. All content is immediately added to the underlying stream without the use of temporary files. To complete creating the document, you must call EndDoc().

The pages of the document are accessible via the Pages collection. To add content, use Graphics property to get a GcGraphics for a page. (In sequential mode, only the currently last page of the document can be drawn on.) You can then use that graphics object to draw the desired content.

Constructors

Name	Description
GcPdfDocument(string)	Creates a new instance of the GcPdfDocument class, optionally specifying a license key.

Properties

Name	Description
AcroForm	Gets the AcroForm object defining common properties of the AcroForms in this document.
ArticleThreads	Gets the list of ArticleThread objects.
AssociatedFiles	Gets the collection of embedded files associated with whole document. Typically it is used to identify which embedded file was the source of the PDF document.
BuildRichTextAppearanceStreams	Gets or sets a value indicating whether to generate appearance streams for annotations that have rich text content (FreeTextAnnotation, LineAnnotation). The default value for this property is false. Note that currently there is a limitation: if this property is set to true so that appearance streams for rich text are generated, all rich text formatting is ignored.
CMapProvider	Gets or sets an object that implements the ICMapProvider interface. GcPdfDocument uses that interface to obtain an GrapeCity.Documents.Pdf.Text.CMap.CMap if it specified by name in the PDF file. By default GcPdf tries to initialize this property automatically in the GcPdfDocument's constructor with the CMapProvider.Instance defined in the optional GrapeCity.Documents.Pdf.Resources package (which in this case needs to be explicitly referenced by the application).
CompressionLevel	Gets or sets the compression level. Default value is Fastest.
ConformanceLevel	Gets or sets the PDF/A conformance level. The default is none (the document does not conform to PDF/A).
DestinationsDests	Gets the dictionary of named destinations defined in the Dests entry of the document catalog.
DestinationsNamesDests	Gets the dictionary of named destinations defined in the Dests entry of the Name Dictionary.
DidPrintAction	Gets or sets a ActionJavaScript to be performed after printing the document.
DidSaveAction	Gets or sets a ActionJavaScript to be performed after saving the document.
DocumentInfo	Gets or sets a DocumentInfo object that contains information about this document (author, title, etc). Note: this property is not null by default (when a GcPdfDocument is created) but it can become null after a call to Load(Stream, string) if the loaded document does not have a document info object.
EmbeddedFiles	Gets the dictionary of document level file attachments.
FileID	Gets or sets the FileID object defining ID of this PDF document. Note that this ID is automatically updated if the Clear() method is called.
FontCollection	Gets or sets the IFontCollection object used when the GcPdfDocument needs to find a Font (e.g. if it is not embedded in the PDF). If this property is null (the default), then the SystemFonts will be used.
FontEmbedMode	Gets or sets the font embedding mode. The default is EmbedSubset. Note that this property does not affect the 14 standard PDF fonts, their embedding is determined by the StandardFontEmbedMode property. Also note that if the GcPdfDocument is saved as PDF/A, and the value of this property is NotEmbed, the fonts are embedded anyway using the EmbedSubset mode.
FontHandlers	Gets the collection of font handlers associated with the current document.
FormEmbedUtf32CodeSet	Gets or sets a Utf32CodeSet object that specifies which Unicode characters to include in embedded font subsets for fonts that are used in AcroForms. This value will be used for a font if that font handler's Utf32CodeSet is null. Note that if for a font, its Utf32CodeSet is null, and FormEmbedUtf32CodeSet is null, and the font is used in the AcroForm, then this whole font will be embedded even if partial embedding is specified by EmbedMode or FontEmbedMode.
ImageHandlers	Gets the collection of PdfImageHandler objects associated with the current document.
ImageOptions	Gets the ImageOptions object that contains options controlling how images are processed in the current document.
IsCompressed	Gets a value indicating whether compression is used when saving the document.
JavaScripts	Gets the dictionary of document level JavaScript actions.
Landscape	Gets or sets a value indicating whether newly added pages have landscape orientation.
Lang	Gets or sets a language identifier specifying the natural language for all text in the document except where overridden by language specifications for structure elements or marked content. If this entry is absent, the language is considered unknown.
Linearized	Gets a value indicating whether the PDF that was loaded into this GcPdfDocument was linearized ("fast web view"). Note that this value only indicates the linearization of the original PDF that was loaded, if the current document is saved its linearization is not affected by this property. To save the current document as linearized, pass Linearized when saving the PDF using one of the save methods: Save(Stream, SaveMode) Save(string, SaveMode) Sign(SignatureProperties, Stream, SaveMode) Sign(SignatureProperties, string, SaveMode)
LoadStream	Gets the Stream object that was passed to the Load() method that was used to load this document, or null if Load() was not called.
MarkInfo	Gets a MarkInfo object that provides additional information relevant to specialized uses of structured PDF documents.
Metadata	Gets or sets the metadata associated with this document.
NamedDestinations	Gets the dictionary of named destinations defined in the current document.
OpenAction	Gets or sets a DestinationBase to be displayed or an ActionBase to be performed when the document is opened.
OptionalContent	Gets the OptionalContentProperties object that contains information about optional PDF content (layers) in this document.
Outlines	Gets the collection of the current document outlines.
OutputIntents	Gets the list of OutputIntent objects associated with the current document. Note that if the document is saved as PDF/A (see PdfAConformanceLevel) and this collection is empty, a default output intent will be automatically added to it.
PageLabelingRanges	Gets the dictionary of PageLabelingRange objects. Each key in this dictionary is the index of the first page in a labeling range.
PageLayout	Gets or sets the page layout to be used when the document is opened.
PageMode	Gets or sets how the document should be displayed when opened.
PageRectangle	Gets a rectangle that represents the surface of the current page (in points).
PageSize	Gets or sets the default page size for the document (in points).
Pages	Gets the collection of Page objects that make up the document.
PaperKind	Gets or sets the page size for the document.
PdfACompliant	Gets or sets a value indicating whether the document is PDF/A compliant.
PdfFontFormat	Gets or sets the format used to represent fonts in the current document. The default is Type0AutoOneByteEncoding. Note that this property does not affect the 14 standard PDF fonts, those are always encoded as Type1.
PdfVersion	Gets or sets the PDF Version of the generated document. By default the version is determined automatically based on which features are used in this document. Setting this property to a non-null string in the format "1.X" (where X is a digit from 0 to 9) overrides the automatic value with the specified one. Setting this property to null or an empty string reverts to the default behavior.
RecognitionAlgorithm	Gets or sets the type of algorithm that is used for PDF content recognition when building page text maps (see GetTextMap(float, float, bool)). This property affects the behavior of methods such as GetText(bool), FindText(FindTextParams, OutputRange), FindText(FindTextParams, FindTextCallback) and other APIs that rely on text maps.
Security	Gets the GrapeCity.Documents.Pdf.Security object that manages security for the current document (passwords, etc).
SecurityStore	Gets the DocumentSecurityStore object associated with this document.
StandardFontEmbedMode	Gets or sets the font embedding mode for the 14 standard PDF fonts. The default is NotEmbed. Note that if the GcPdfDocument is saved as PDF/A, and the value of this property is NotEmbed, the standard fonts are embedded anyway using the EmbedSubset mode.
StructTreeRoot	Gets a StructTreeRoot object that represents the current document's structure tree as defined by PDF structure tags.
ViewerPreferences	Gets the ViewerPreferences object that contains information specifying how the current document should be displayed.
WillCloseAction	Gets or sets a ActionJavaScript to be performed before closing the document.
WillPrintAction	Gets or sets a ActionJavaScript to be performed before printing the document.
WillSaveAction	Gets or sets a ActionJavaScript to be performed before saving the document.
WriteComments	Gets or sets a value indicating whether comments and some optional line breaks will be added to the generated PDF file. Primarily useful for debugging.

Methods

Name	Description
Clear()	Clears the document, removing all content and resetting all properties and settings to their initial default values.
DeleteText(FindTextParams, DeleteTextMode, OutputRange)	Deletes a specified text from all pages of the current document. Note that the results may be affected by the current value of the RecognitionAlgorithm property.
EndDoc()	Ends document generation in sequential mode. This call must be preceded by a call to StartDoc(Stream).
ExportFormDataToFDF(Stream, ExportFormDataOptions)	Exports the document's form data to a stream in FDF format.
ExportFormDataToFDF(string, ExportFormDataOptions)	Exports the document's form data to a file in FDF format.
ExportFormDataToXFDF(Stream, ExportFormDataOptions)	Exports the document's form data to a stream in XFDF format.
ExportFormDataToXFDF(string, ExportFormDataOptions)	Exports the document's form data to a file in XFDF format.
ExportFormDataToXML(Stream, ExportFormDataOptions)	Exports the document's form data to a stream in XML format.
ExportFormDataToXML(string, ExportFormDataOptions)	Exports the document's form data to a file in XML format.
FindText(FindTextParams, OutputRange)	Searches for all occurrences of a text in a range of the document's pages. Note that the results are affected by the value of RecognitionAlgorithm property.
GetCustomProperty(string)	Gets the value of a custom property with a specified name. Use UserProps to enumerate custom properties.
GetFonts()	Gets the list of fonts in this GcPdfDocument.
GetImages(float, float, bool, bool)	Gets the list of images in this GcPdfDocument. Note that for large documents this method can take a while to complete, as it enumerates the content streams of all pages in the document.
GetLogicalStructure(ViewState, float, float, bool)	Parses the PDF's structure tree (as returned by the StructTreeRoot property) and creates a LogicalStructure object that represents the logical structure of the document. Returns null if the current document does not have a structure tree.
GetLogicalStructure(float, float, bool)	Parses the PDF's structure tree (as returned by the StructTreeRoot property) and creates a LogicalStructure object that represents the logical structure of the document. Returns null if the current document does not have a structure tree.
GetText(ViewState, bool)	Extracts and returns all text from the current document.
GetText(bool)	Extracts and returns all text from the current document.
ImportFormDataFromCollection(KeyValuePair<IList<string>, IList<string>>[])	Imports the document's form data from a key/value collection. The keys are collections of strings representing fully qualified field names including all parents if they exist, from the top parent to the field itself, e.g. new string[] { "TopParent", "Parent", "MyField" }. The values are collections of field values. This method may be especially useful when importing form data submitted by a web page.
ImportFormDataFromCollection(KeyValuePair<string, IList<string>>[])	Imports the document's form data from a key/value collection. The keys are field names, the values are collections of field values. For nested fields, the field's name should include all its parents' names delimited by dots, e.g. TopParent.Parent.MyField. This method may be especially useful when importing form data submitted by a web page.
ImportFormDataFromFDF(Stream)	Imports the document's form data from a stream in FDF format.
ImportFormDataFromFDF(string)	Imports the document's form data from a file in FDF format.
ImportFormDataFromXFDF(Stream)	Imports the document's form data from a stream in XFDF format.
ImportFormDataFromXFDF(string)	Imports the document's form data from a file in XFDF format.
ImportFormDataFromXML(Stream)	Imports the document's form data from a stream in XML format.
ImportFormDataFromXML(string)	Imports the document's form data from a file in XML format.
Load(Stream, DecryptionOptions)	Loads the document from a specified input stream, overwriting the current content of the document. The stream should contain valid PDF data and must be kept open while reading or modifying the document. If the document is modified, it can be saved using the Save(string, bool) or Save(Stream, bool) methods.
Load(Stream, byte[])	Loads the current document from a specified input stream, overwriting the current content of the document. The stream should contain valid PDF data, and must be kept open while reading or modifying the document. If the document is modified, it can be saved using the Save(string, bool) or Save(Stream, bool) method.
Load(Stream, string)	Loads the current document from a specified input stream, overwriting the current content of the document. The stream should contain valid PDF data, and must be kept open while reading or modifying the document. If the document is modified, it can be saved using the Save(string, bool) or Save(Stream, bool) method.
MergeWithDocument(GcPdfDocument, MergeDocumentOptions)	Merges all or some pages from a specified GcPdfDocument into the current document.
NewPage()	Adds a blank page to the document. The size of the new page is defined by the value of the PageSize property. If you want the new page to have a different size than the rest of the document, create the new page first, then set the Size property.
OnSavingDocument(float, bool)	Fires the SavingDocument event.
Optimize(Stream, OptimizeDocumentOptions)	Optimizes the document and saves it to the specified stream.
Optimize(string, OptimizeDocumentOptions)	Optimizes the document and saves it to the specified file.
OptimizeFonts()	Optimizes font usage by merging subsets of same fonts and by removing duplicate and unused fonts. This method uses the default values from OptimizeFontsOptions.
OptimizeFonts(OptimizeFontsOptions)	Optimizes font usage by merging subsets of same fonts, and by removing duplicate and unused fonts.
Redact(RedactAnnotation, RedactOptions)	Applies a specified RedactAnnotations to the current document.
Redact(RedactOptions)	Applies all RedactAnnotations to the current document.
Redact(IList<RedactAnnotation>, RedactOptions)	Applies a list of specified RedactAnnotations to the current document.
RegisterPdfObject(IPdfObject)	Registers an indirect PDF object with the current document and returns the ID of the object as a PdfObjID.
RemoveDuplicateImages()	Removes images with identical content from the current document.
RemoveEmbeddedFonts()	Removes embedded fonts from the current document. Please note that a PDF may display incorrectly after removing embedded fonts. Use with caution.
RemoveImages(IList<PdfImageInfo>)	Removes the specified images from the document. Images to be removed are defined by PdfImageInfo objects which may be obtained using one of GcPdfDocument.GetImages() method overloads. If an image's Locations and WidgetReferences properties are empty, the image will be removed from all locations.
ReplaceText(FindTextParams, string, OutputRange, Font, float?)	Replaces a specified text on all pages of the current document. Note that the results may be affected by the current value of the RecognitionAlgorithm property.
Save(Stream)	Saves the current PDF document to a Stream using the default mode (no incremental update, not linearized).
Save(Stream, SaveMode)	Saves the current PDF document to a Stream using the specified save mode.
Save(Stream, SavePdfOptions)	Saves the current PDF document to a Stream using a specified PDF save options.
Save(Stream, bool)	Saves the current PDF document to a Stream, optionally using incremental update mode.
Save(string)	Saves the current PDF document to a file using the default mode (no incremental update, not linearized).
Save(string, SaveMode)	Saves the current PDF document to a file using a specified save mode.
Save(string, SavePdfOptions)	Saves the current PDF document to a file using a specified PDF save options.
Save(string, bool)	Saves the current PDF document to a file, optionally using incremental update mode.
SaveAsBmp(string, OutputRange, SaveAsImageOptions)	Saves the document pages as images in BMP format, one page per output file. The `filePath` parameter is used as a .NET format string, with current page number (1-based) passed to it as the value to be formatted. Note that if `filePath` does not contain a format item (such as "{0}"), all pages will be saved into the same file name, the last page overwriting everything else.
SaveAsBmp(string, ViewState, OutputRange, SaveAsImageOptions)	Saves the document pages as images in BMP format, one page per output file. The `filePath` parameter is used as a .NET format string, with current page number (1-based) passed to it as the value to be formatted. Note that if `filePath` does not contain a format item (such as "{0}"), all pages will be saved into the same file name, the last page overwriting everything else.
SaveAsGif(string, OutputRange, SaveAsImageOptions)	Saves the document pages as images in GIF format, one page per output file. The `filePath` parameter is used as a .NET format string, with current page number (1-based) passed to it as the value to be formatted. Note that if `filePath` does not contain a format item (such as "{0}"), all pages will be saved into the same file name, the last page overwriting everything else.
SaveAsGif(string, ViewState, OutputRange, SaveAsImageOptions)	Saves the document pages as images in GIF format, one page per output file. The `filePath` parameter is used as a .NET format string, with current page number (1-based) passed to it as the value to be formatted. Note that if `filePath` does not contain a format item (such as "{0}"), all pages will be saved into the same file name, the last page overwriting everything else.
SaveAsImage(OutputRange, SaveAsImageOptions, SaveAsImageDelegate)	Iterates other the document pages and generates a GcBitmap for each page in the `pageRange`.
SaveAsImage(ViewState, OutputRange, SaveAsImageOptions, SaveAsImageDelegate)	Iterates over the document pages and generates a GcBitmap for each page in the `pageRange`.
SaveAsJpeg(string, OutputRange, SaveAsImageOptions)	Saves the document pages as images in JPEG format, one page per output file. The `filePath` parameter is used as a .NET format string, with current page number (1-based) passed to it as the value to be formatted. Note that if `filePath` does not contain a format item (such as "{0}"), all pages will be saved into the same file name, the last page overwriting everything else.
SaveAsJpeg(string, ViewState, OutputRange, SaveAsImageOptions)	Saves the document pages as images in JPEG format, one page per output file. The `filePath` parameter is used as a .NET format string, with current page number (1-based) passed to it as the value to be formatted. Note that if `filePath` does not contain a format item (such as "{0}"), all pages will be saved into the same file name, the last page overwriting everything else.
SaveAsPng(string, OutputRange, SaveAsImageOptions)	Saves the document pages as images in PNG format, one page per output file. The `filePath` parameter is used as a .NET format string, with current page number (1-based) passed to it as the value to be formatted. Note that if `filePath` does not contain a format item (such as "{0}"), all pages will be saved into the same file name, the last page overwriting everything else.
SaveAsPng(string, ViewState, OutputRange, SaveAsImageOptions)	Saves the document pages as images in PNG format, one page per output file. The `filePath` parameter is used as a .NET format string, with current page number (1-based) passed to it as the value to be formatted. Note that if `filePath` does not contain a format item (such as "{0}"), all pages will be saved into the same file name, the last page overwriting everything else.
SaveAsSvg(string, OutputRange, SaveAsImageOptions, XmlWriterSettings)	Saves the document pages as images in SVG format, one page per output file. The `filePath` parameter is used as a .NET format string, with current page number (1-based) passed to it as the value to be formatted. Note that if `filePath` does not contain a format item (such as "{0}"), all pages will be saved into the same file name, the last page overwriting everything else.
SaveAsSvg(string, ViewState, OutputRange, SaveAsImageOptions, XmlWriterSettings)	Saves the document pages as images in SVG format, one page per output file. The `filePath` parameter is used as a .NET format string, with current page number (1-based) passed to it as the value to be formatted. Note that if `filePath` does not contain a format item (such as "{0}"), all pages will be saved into the same file name, the last page overwriting everything else.
SaveAsTiff(Stream, OutputRange, SaveAsImageOptions, TiffFrameSettings)	Saves the document pages as images to a stream in TIFF format, one page per frame.
SaveAsTiff(Stream, ViewState, OutputRange, SaveAsImageOptions, TiffFrameSettings)	Saves the document pages as images to a stream in TIFF format, one page per frame.
SaveAsTiff(string, OutputRange, SaveAsImageOptions, TiffFrameSettings)	Saves the document pages as images to a file in TIFF format, one page per frame.
SaveAsTiff(string, ViewState, OutputRange, SaveAsImageOptions, TiffFrameSettings)	Saves the document pages as images to a file in TIFF format, one page per frame.
SetCustomProperty(string, string)	Adds a custom property with a specified value to this document. The property is added to DocumentInfo and to UserProps in "http://ns.adobe.com/pdfx/1.3/" namespace. If `value` is null or empty, and a custom property with the specified name exists in the document, it is removed. `name` must not be one of the standard property names Title, Author, Subject, Keywords, Creator, Producer, CreationDate, ModDate, and Trapped.
SetLicenseKey(string)	Sets the license key.
Sign(SignatureProperties, Stream)	Signs and saves the current document to a stream. Note that `stream` must support read and seek operations.
Sign(SignatureProperties, Stream, SaveMode)	Signs and saves the current document to a stream. Note that `stream` must support read and seek operations.
Sign(SignatureProperties, Stream, SavePdfOptions)	Signs and saves the current document to a stream. Note that `stream` must support read and seek operations.
Sign(SignatureProperties, Stream, bool)	Signs and saves the current document to a file. Note that `stream` must support read and seek operations.
Sign(SignatureProperties, string)	Signs and saves the current document to a file.
Sign(SignatureProperties, string, SaveMode)	Signs and saves the current document to a file.
Sign(SignatureProperties, string, SavePdfOptions)	Signs and saves the current document to a file.
Sign(SignatureProperties, string, bool)	Signs and saves the current document to a stream.
StartDoc(Stream)	Starts document generation in sequential mode. In this mode, the content of the document is written directly into the underlying stream as soon as it is created, without the use of temporary files. When all content has been added, call EndDoc() to finish creating the document.
TimeStamp(TimeStampProperties, Stream)	Adds a document time stamp and saves the current document to a stream.
TimeStamp(TimeStampProperties, Stream, SaveMode)	Adds a document time stamp and saves the current document to a stream.
TimeStamp(TimeStampProperties, Stream, SavePdfOptions)	Adds a document time stamp and saves the current document to a stream.
TimeStamp(TimeStampProperties, string)	Adds a document time stamp and saves the current document to a file.
TimeStamp(TimeStampProperties, string, SaveMode)	Adds a document time stamp and saves the current document to a file.
TimeStamp(TimeStampProperties, string, SavePdfOptions)	Adds a document time stamp and saves the current document to a file.

Events

Name	Description
SavingDocument	Occurs periodically when the document is being saved or exported. Can be used to implement a progress indicator.