LEADDocument Class

Encapsulates a multipage document with support for raster and SVG images, bookmarks, annotations, and text data.

The LEADDocument class provides uniform support for any type of document. The actual data behind it can be a PDF document, Microsoft Word document, TIFF image, an AutoCAD DWG drawing, or any other of the hundreds of different raster, document, or vector file formats supported by LEADTOOLS. LEADDocument encapsulates the common functionality needed to uniformly access this data with the same properties, methods, and data structures.

Document Viewer

LEADDocument is used as an input to the DocumentViewer, which can be used to view the document and its pages and includes thumbnail, virtualization, text search, and annotation support.

Document Converter

LEADDocument can also be used as an input to the DocumentConverter, to convert the document to any other file format, with or without using OCR technology.

Creating a Document Class

A LEADDocument instance can be obtained using any of the following methods:

After the document is obtained, InternalObject will be the internal LEADTOOLS object used with the document.

Encryption

In most cases, the LEADDocument is ready to use after it has been obtained. However, some documents such as PDF can be encrypted and require a password before it can be parsed and used. Most of the properties and methods of LEADDocument will throw an error if the document has not been decrypted. IsEncrypted can be used to check if the document is encrypted and if so, Decrypt must be called with the password obtained from the user to unlock the document. When that happens, the value of IsDecrypted becomes true and the document is ready to be used.

Note that IsEncrypted will stay true to indicate the original state of the document.

Saving a Document Class

The SaveToFile and SaveToUri methods can be used to save the document to a disk file or remote URL. These methods support saving the document to a raster image format, not a document. In most cases, converting a document should be performed using the DocumentConverter class, which has more options and control.

Document Identifier

Each document has a unique identifier that is set at creation time by the framework. It is stored in the DocumentId property. The ID is important when using the document with the cache system. The ID is the only value needed to completely re-construct the document from the cache.

The document ID can be set manually by the user by calling the LoadDocumentOptions.DocumentId, CreateDocumentOptions.DocumentId, or UploadDocumentOptions.DocumentId options used when loading, creating or uploading the document. If DocumentId is left to null, the factory will generate a new random ID and associate it with the document using a DocumentFactory.NewCacheId.

Caching

Documents can contain many pages and huge amounts of data. Storing all this data in the physical memory is not feasible in most situations. Therefore, the LEADDocument class was designed to use an external caching system to store the modified data. Refer to DocumentFactory.Cache for more information.

HasCache determines if this document is using the cache system. Call SaveToCache to save a document to the cache and re-load it using DocumentFactory.LoadFromCache. AutoDeleteFromCache and AutoSaveToCache can be used to determine what happens to the cache data associated with the document when the document is disposed.

Structure and Table of Contents

DocumentStructure manages the structure of the document. This structure includes the bookmarks that represents the table of contents. Access it through the Structure property of LEADDocument.

Pages

DocumentPages manages the pages of the document. Access it through the Pages property of LEADDocument.

DocumentPages derives from LeadCollection<T> and thus can implement System.Collections.ObjectModel.Collection. You can use any of the collection methods to add, remove, insert, get, set, and iterate through the pages.

DocumentPages contains a collection of DocumentPage objects, each containing the data for a single page in the document. The page item is the main entry point for using the documents in a viewer or converter application. DocumentPage contains functions to retrieve or update the raster or SVG image of the page, text data, annotations, and hyperlinks. Refer to DocumentPage for more information.

Documents

DocumentDocuments manages the child documents of the document. Access it through the Documents property of LEADDocument.

DocumentDocuments derives from LeadCollection<T> and thus can implement System.Collections.ObjectModel.Collection. You can use any of the collection methods to iterate through the documents. This collection is read-only, however, so you cannot add, remove, or change the items. Instead, use Pages to add or remove pages that belong to a separate document to this one. The LEADDocument.Documents collection automatically gets updated to reflect which child documents are currently held in the document.

History Tracking

Document modification history and tracking can be enabled and accessed through the DocumentHistory object. It can be accessed through the History property of LEADDocument.

Metadata

The metadata includes the default values added by the DocumentFactory when the document is loaded or created, as well as any other data extracted from the document file itself, such as author, subject, and any keywords stored by other applications.

Properties

The following properties are part of LEADDocument and contain useful information:

• DocumentId: The unique identifier of this document.
• Name: The name of this document.
• DocumentType: The document type.
• MimeType: The MIME type of the document.
• Uri: The URL to the original document's physical location. If this is a newly created document, then Uri will be null.
• CacheUri: The URL to the original document's image data if it was stored in the cache.
• IsDownloaded: Determines if the document was downloaded into the cache or a temporary file.
• IsReadOnly: Determines if the document is read-only and cannot be changed.
• UserId: User ID or name associated with this document.
• UserData: User-defined data associated with this document.
• GetDocumentFileName: Gets the path to the file holding the original document.
• GetDocumentStream: Gets a stream to the original data of the document.
• GetAnnotationsFileName: Gets the path to the file holding the original annotations.
• GetAnnotationsStream: Gets a stream to the original annotations.
• FileLength: The length of the original document file or URL in bytes.
• CacheStatus: The status of this document in the cache.

Access to the original document data depends on how the document was created and its cache status, as follows:

• Result of LoadFromFile: GetDocumentFileName will contain the original the name of the file passed to the method. GetDocumentStream will return null.

• Result of LoadFromUri when caching is not used: GetDocumentFileName will return the name of the temporary file used to store the data.

• Result of LoadFromUri when caching is used: if the cache supports external resources (disk-access), then GetDocumentFileName will contain the name of the file holding the cache item in disk. If the cache does not support external resources (disk-access), then GetDocumentFileName will return null, and GetDocumentStream will return a valid read-only stream that can be used to access the data.

• Result of LoadFromCache(ObjectCache,string): Caching is used naturally and the same rules as LoadFromUri apply.

Global Document Settings

The LEADDocument class contains the following objects to manage global settings used throughout the document.

• Images: Manages the raster and SVG image settings of the document.
• RasterCodecs: The RasterCodecs object to use when loading and saving RasterImage and SvgDocument objects.
• Annotations: Manages the annotation settings of the document.
• Text: Manages the text and OCR recognition settings of the document.
• Barcodes: Manages the barcode settings of the document.

Document Units

LEADDocument uses independent units of 1/720 of an inch for all items. This value is stored in the UnitsPerInch constant (720). Refer to Document Library Coordinate System for more information.

Disposing

LEADDocument implements System.IDisposable and must be disposed of after it has been used. Refer to System.IDisposable in .NET for more information. The document can be re-constructed as is after it has been disposed of if it was saved into the cache, (AutoSaveToCache was set to true, or SaveToCache was used).

This example loads a document and shows all its information.

using Leadtools; 
using Leadtools.Codecs; 
using Leadtools.Document.Writer; 
using Leadtools.Svg; 
using LeadtoolsExamples.Common; 
using Leadtools.Document; 
using Leadtools.Caching; 
using Leadtools.Annotations.Engine; 
using Leadtools.Ocr; 
using Leadtools.Barcode; 
using Leadtools.Document.Converter; 
 
public static ObjectCache GetCache() 
{ 
   // Create a LEADTOOLS FileCache object 
 
   var cacheDir = Path.Combine(ImagesPath.Path, "cache"); 
   if (Directory.Exists(cacheDir)) 
      Directory.Delete(cacheDir, true); 
 
   Directory.CreateDirectory(cacheDir); 
 
   var cache = new FileCache(); 
   cache.CacheDirectory = cacheDir; 
 
   return cache; 
} 
 
public static void PrintOutDocumentInfo(LEADDocument document) 
{ 
   Console.WriteLine("General"); 
   Console.WriteLine("  DocumentId:" + document.DocumentId); 
   if (document.Uri != null) 
      Console.WriteLine("  Uri:" + document.Uri); 
   Console.WriteLine("  Name:" + document.Name); 
   Console.WriteLine("  CacheStatus:" + document.CacheStatus); 
   Console.WriteLine("  LastCacheSyncTime:" + document.LastCacheSyncTime); 
   Console.WriteLine("  IsReadOnly:" + document.IsReadOnly); 
   Console.WriteLine("  IsLocal:" + document.IsLocal); 
   Console.WriteLine("  MimeType:" + document.MimeType); 
   Console.WriteLine("  IsEncrypted:" + document.IsEncrypted); 
   Console.WriteLine("  IsDecrypted:" + document.IsDecrypted); 
   Console.WriteLine("  UserData:" + document.UserData); 
   Console.WriteLine("Cache"); 
   Console.WriteLine("  HasCache:" + document.HasCache); 
   Console.WriteLine("  AutoDeleteFromCache:" + document.AutoDeleteFromCache); 
   Console.WriteLine("Metadata"); 
   foreach (var item in document.Metadata) 
      Console.WriteLine("  {0} {1}", item.Key, item.Value); 
 
   Console.WriteLine("Documents"); 
   Console.WriteLine("  Count:" + document.Documents.Count); 
   foreach (var childDocument in document.Documents) 
   { 
      Console.WriteLine("    Name:" + childDocument.Name); 
   } 
 
   Console.WriteLine("Pages"); 
   Console.WriteLine("  Count:" + document.Pages.Count); 
 
   for (var pageNumber = 1; pageNumber <= document.Pages.Count; pageNumber++) 
   { 
      var page = document.Pages[pageNumber - 1]; 
 
      Console.WriteLine("    PageNumber:" + pageNumber); 
      Console.WriteLine("      OriginalPageNumber:" + page.OriginalPageNumber); 
      Console.WriteLine("      OriginalDocumentName:" + page.Document.Name); 
      Console.WriteLine("      Size:{0}", page.Size); 
   } 
 
   Console.WriteLine("--------"); 
} 
 
public static void DocumentExample() 
{ 
   var cache = GetCache(); 
 
   var policy = new CacheItemPolicy(); 
   policy.AbsoluteExpiration = DateTime.Now + new TimeSpan(0, 0, 1); 
   policy.SlidingExpiration = new TimeSpan(0, 0, 1); 
 
   var options = new LoadDocumentOptions(); 
   options.CachePolicy = policy; 
   options.Cache = cache; 
 
   string documentId = null; 
 
   using (var document = DocumentFactory.LoadFromFile(Path.Combine(ImagesPath.Path, "Leadtools.pdf"), options)) 
   { 
      document.AutoDeleteFromCache = false; 
 
      PrintOutDocumentInfo(document); 
 
      documentId = document.DocumentId; 
      document.SaveToCache(); 
   } 
 
   System.Threading.Thread.Sleep(2000); 
 
   var loadFromCacheOptions = new LoadFromCacheOptions(); 
   loadFromCacheOptions.Cache = cache; 
   loadFromCacheOptions.DocumentId = documentId; 
   using (var document = DocumentFactory.LoadFromCache(loadFromCacheOptions)) 
   { 
      if (null == document) 
      { 
         Console.WriteLine("Cached document was expired and deleted!"); 
      } 
   } 
} 

Imports Leadtools 
Imports Leadtools.Codecs 
Imports Leadtools.Document.Writer 
Imports Leadtools.Svg 
Imports Leadtools.Document 
Imports Leadtools.Caching 
Imports Leadtools.Annotations.Engine 
Imports Leadtools.Barcode 
Imports Leadtools.Ocr 
Imports LeadtoolsDocumentExamples.LeadtoolsExamples.Common 
Imports Leadtools.Document.Converter 
 
Public Shared Function GetCache() As ObjectCache 
   ' Create a LEADTOOLS FileCache object 
 
   Dim cacheDir As String = Path.Combine(ImagesPath.Path, "cache") 
   If Directory.Exists(cacheDir) Then 
      Directory.Delete(cacheDir, True) 
   End If 
 
   Directory.CreateDirectory(cacheDir) 
 
   Dim cache As New FileCache() 
   cache.CacheDirectory = cacheDir 
 
   Return cache 
End Function 
 
Public Shared Sub PrintOutDocumentInfo(ByVal document As LEADDocument) 
   Console.WriteLine("General") 
   Console.WriteLine("  DocumentId:" + document.DocumentId) 
   If Not IsNothing(document.Uri) Then 
      Console.WriteLine("  Uri:" + document.Uri.ToString()) 
   Else 
      Console.WriteLine("  Name:" + document.Name) 
   End If 
 
   Console.WriteLine("  CacheStatus:" + document.CacheStatus.ToString()) 
   Console.WriteLine("  LastCacheSyncTime:" + document.LastCacheSyncTime.ToString()) 
   Console.WriteLine("  IsReadOnly:" + document.IsReadOnly.ToString()) 
   Console.WriteLine("  IsLocal:" + document.IsLocal.ToString()) 
   Console.WriteLine("  MimeType:" + document.MimeType) 
   Console.WriteLine("  IsEncrypted:" + document.IsEncrypted.ToString()) 
   Console.WriteLine("  IsDecrypted:" + document.IsDecrypted.ToString()) 
   If Not IsNothing(document.UserData) Then 
      Console.WriteLine("  UserData:" + document.UserData.ToString()) 
   End If 
   Console.WriteLine("Cache") 
   Console.WriteLine("  HasCache:" + document.HasCache.ToString()) 
   Console.WriteLine("  AutoDeleteFromCache:" + document.AutoDeleteFromCache.ToString()) 
   Console.WriteLine("Metadata") 
   For Each item As KeyValuePair(Of String, String) In document.Metadata 
      Console.WriteLine("  {0} {1}", item.Key, item.Value) 
   Next 
 
   Console.WriteLine("Documents") 
   Console.WriteLine("  Count:" + document.Documents.Count.ToString()) 
   For Each childDocument As LEADDocument In document.Documents 
      Console.WriteLine("    Name:" + childDocument.Name) 
   Next 
 
   Console.WriteLine("Pages") 
   Console.WriteLine("  Count:" + document.Pages.Count.ToString()) 
 
   For pageNumber As Integer = 1 To document.Pages.Count 
      Dim page As Leadtools.Document.DocumentPage = document.Pages(pageNumber - 1) 
 
      Console.WriteLine("    PageNumber:" + pageNumber.ToString()) 
      Console.WriteLine("      OriginalPageNumber:" + page.OriginalPageNumber.ToString()) 
      Console.WriteLine("      OriginalDocumentName:" + page.Document.Name) 
      Console.WriteLine("      Size:{0}", page.Size.ToString()) 
   Next 
 
   Console.WriteLine("--------") 
End Sub 
 
Public Shared Sub DocumentExample() 
   Dim cache As ObjectCache = GetCache() 
 
   Dim policy As CacheItemPolicy = New CacheItemPolicy() 
   policy.AbsoluteExpiration = DateTime.Now + New TimeSpan(0, 0, 1) 
   policy.SlidingExpiration = New TimeSpan(0, 0, 1) 
 
   Dim options As LoadDocumentOptions = New LoadDocumentOptions() 
   options.CachePolicy = policy 
   options.Cache = cache 
 
   Dim documentId As String = Nothing 
 
   Using document As LEADDocument = DocumentFactory.LoadFromFile(Path.Combine(ImagesPath.Path, "Leadtools.pdf"), options) 
      document.AutoDeleteFromCache = False 
 
      PrintOutDocumentInfo(document) 
 
      documentId = document.DocumentId 
      document.SaveToCache() 
   End Using 
 
   System.Threading.Thread.Sleep(2000) 
 
   Dim loadFromCacheOptions As New LoadFromCacheOptions 
   loadFromCacheOptions.Cache = cache 
   loadFromCacheOptions.DocumentId = documentId 
   Using document As LEADDocument = DocumentFactory.LoadFromCache(loadFromCacheOptions) 
      If document Is Nothing Then 
         Console.WriteLine("Cached document was expired and deleted!") 
      End If 
   End Using 
End Sub 

Target Platforms

Reference

• LEADDocument Members
• Leadtools.Document Namespace
• Document Library Features
• Loading Using LEADTOOLS Document Library
• Creating Documents with LEADTOOLS Document Library
• Document Toolkit and Caching
• Document Library Coordinate System
• Loading Encrypted Files Using the Document Library
• Parsing Text with the Document Library
• Barcode processing with the Document Library
• Using LEADTOOLS Document Viewer
• Using LEADTOOLS Document Converters
• Document View and Convert Redaction