←Select platform

DocumentViewerAnnotations Class

Summary

Manages the annotations support in this document viewer.

Syntax

C#
VB
C++
public class DocumentViewerAnnotations : IDisposable 
Public Class DocumentViewerAnnotations 
public: 
   ref class DocumentViewerAnnotations

Remarks

DocumentViewerAnnotations can be accessed by the DocumentViewer.Annotations property.

This class manages the automation support of the annotation containers in the Document set in the document viewer. The annotations are obtained from the document using DocumentPage.GetAnnotations.

When the Document Viewer is created

If the value of DocumentViewerCreateOptions.UseAnnotations is false, then annotations support is not required by the application. DocumentViewerAnnotations is not created and the value of DocumentViewer.Annotations is null and should not be used.

Otherwise, the following occurs:

  1. An internal class that implements IAnnAutomationControl is created with to handle the interaction between the annotations automation and the image viewer including updating the transformation matrices and rendering of the annotation container of each page on the viewer items. This automation control can be retrieved with the AutomationControl property.

  2. AnnotationsInteractiveMode is created. This is a custom interactive mode to handle the mouse/touch events used for drawing and editing annotations objects. This interactive mode is added to the ImageViewer of the view interactive modes list and can be retrieved using the InteractiveMode property.

  3. AnnAutomationManager is created and can be retrieved using the AutomationManager property.

When the Document Viewer is destroyed

  1. The AnnAutomationManager and IAnnAutomationControl objects are destroyed

  2. All resources are freed

When a new Document is set

The following occurs when a new Document object is set in the DocumentViewer using DocumentViewer.SetDocument. The following is performed if a previous document was set in the document viewer:

  1. The background thread is aborted and destroyed if still loading.

  2. The Operation event is fired with DocumentViewerOperation set to false to allow the application to remove any events from the automation object and release the resources. This is described in more details in the Application Interaction section below.

  3. When the background thread finishes, an AnnAutomation object is created and various required events are subscribed to. This object is then passed as Data1 to an Operation event with DocumentViewerOperation.CreateAutomation. The application must subscribe to this event to load the annotations resources and create any related user interface elements as well as subscribe to any of AnnAutomation events required.

  4. If the application did not abort the operation, then the annotation containers are added to the Containers size and resolution being used to set the annotation container size and mapper properties. The AnnContainer.PageNumber property each container is also updated with the corresponding page number.

  5. The AnnAutomation.Active property is set to true and annotations automation is ready to be used.

Application Interaction

The application can handle the Operation event with CreateAutomation and DestoryAutomation to perform extra operations not handled by the document viewer. For example, the LEADTOOLS Document Viewer Demo subscribes to the event and performs the following: When the application starts, all the user interface elements related to annotations support are disabled. This stay disabled when a new document is set in the DocumentViewer. The application must wait for the annotations containers to be obtained before they can be used. When a new document is set in the viewer, the application can respond to the Operation event with Operation set to DocumentViewerOperation.CreateAutomation and IsPostOperation set to true. This event occurs after the background thread has finished loading all the containers and AnnAutomation object is created. This object will be set in the Data1 property of the event data. The Document Viewer demo subscribes to some of the object events to handle extra functionality not provided by the document viewer, such as setting the cursors to be used or showing custom annotation object properties dialog. And then enable the annotations specified user interface elements. When the current document is removed from the viewer, the application can respond to the Operation event with Operation set to DocumentViewerOperation.DestroyAutomation and IsPostOperation set to false. This event occurs before the AnnAutomation is destroyed. The Document Viewer demo unsubscribes from the events previously used and disable the annotations specific user interface elements.

Operations and Commands

DocumentViewerAnnotations automatically handles many of the annotations automation operations, these include:

  • Automatically update the Author, Created and Modified metadata of the annotation objects when they modified by the user using the DocumentViewer.UserName property and the current date and time.

  • Replaces the AnnDrawDesigner of AnnTextReviewObject derived types with a custom object that can handle text selection.

  • Renders the annotations containers on the view and thumbnails image viewer controls.

All the operations are reported using the Operation event. Refer to Document Viewer Commands and DocumentViewer-Operations for more information on the above and how to set and customize the behavior.

Example

This example will show to create a functional DocumentViewer with annotations support in your application.

C#
VB
using Leadtools; 
using Leadtools.Controls; 
using Leadtools.Documents; 
using Leadtools.Documents.UI; 
using Leadtools.Documents.Converters; 
using Leadtools.Codecs; 
using Leadtools.Caching; 
using Leadtools.Annotations.Core; 
using Leadtools.Annotations.Automation; 
using Leadtools.Annotations.WinForms; 
using Leadtools.Annotations.Designers; 
using Leadtools.Forms.DocumentWriters; 
using Leadtools.Forms.Ocr; 
 
public void DocumentViewerWithAnnotations_Example() 
{ 
   // New Form to be used as our application 
   var form = new MyForm(); 
   form.ShowDialog(); 
} 
 
class MyForm : Form 
{ 
   public MyForm() 
   { 
      this.Size = new Size(800, 800); 
      this.Text = "LEADTOOLS Document Viewer Example"; 
   } 
 
   protected override void OnLoad(EventArgs e) 
   { 
      if (!DesignMode) 
         Init(); 
 
      base.OnLoad(e); 
   } 
 
   // Our document viewer instance 
   private DocumentViewer _documentViewer; 
 
   private void Init() 
   { 
      // Initialize the user interface 
      InitUI(); 
 
      // Init the cache. This is optional, but it can speed up viewing of large documents 
      // if not needed, remove this section 
      DocumentFactory.Cache = new FileCache(); 
 
      // Init the document viewer, pass along the panels 
      var createOptions = new DocumentViewerCreateOptions 
      { 
         // The middle panel for the view 
         ViewContainer = this.Controls.Find("middlePanel", false)[0], 
         // The left panel for the thumbnails 
         ThumbnailsContainer = this.Controls.Find("leftPanel", false)[0], 
         // Using annotations in this example 
         UseAnnotations = true 
      }; 
 
      // Create the document viewer 
      _documentViewer = DocumentViewerFactory.CreateDocumentViewer(createOptions); 
 
      // We prefer SVG viewing 
      _documentViewer.View.PreferredItemType = DocumentViewerItemType.Svg; 
 
      // Initalize the annotations 
      InitAnnotations(); 
 
      // Load a document 
      var fileName = @"C:\Users\Public\Documents\LEADTOOLS Images\Leadtools.pdf"; 
      var document = DocumentFactory.LoadFromFile( 
         fileName, 
         new LoadDocumentOptions { UseCache = DocumentFactory.Cache != null }); 
 
      // Set it in the viewer 
      _documentViewer.SetDocument(document); 
 
      // Run pan/zoom 
      var interactiveComboBox = this.Controls.Find("interactiveComboBox", true)[0] as ComboBox; 
      interactiveComboBox.SelectedItem = DocumentViewerCommands.InteractivePanZoom; 
   } 
 
   private void InitAnnotations() 
   { 
      // The annotations toolbar will be added here 
      var rightPanel = this.Controls.Find("rightPanel", true)[0]; 
 
      // Get the automation manager from the document viewer 
      var automationManager = _documentViewer.Annotations.AutomationManager; 
      // Create the manager helper. This sets the rendering engine 
      var automationManagerHelper = new AutomationManagerHelper(automationManager); 
      // Tell the document viewer that automation manager helper is created 
      _documentViewer.Annotations.Initialize(); 
 
      // Craete the toolbar 
      automationManagerHelper.ModifyToolBarParentVisiblity = true; 
      automationManagerHelper.CreateToolBar(); 
      var toolBar = automationManagerHelper.ToolBar; 
      toolBar.Dock = DockStyle.Fill; 
      toolBar.AutoSize = true; 
      toolBar.BorderStyle = BorderStyle.None; 
      toolBar.Appearance = ToolBarAppearance.Flat; 
      rightPanel.Controls.Add(toolBar); 
      toolBar.BringToFront(); 
 
      // Handler for showing the context menu when the user right clicks on an annotation object 
      EventHandler<AnnAutomationEventArgs> onShowContextMenu = (sender, e) => 
      { 
         // Get the object type 
         var automationObject = e.Object as AnnAutomationObject; 
         if (automationObject == null) 
            return; 
 
         // Convert the point to client coordinates 
         var imageViewer = _documentViewer.View.ImageViewer; 
         var position = imageViewer.PointToClient(Cursor.Position); 
         var automation = _documentViewer.Annotations.Automation; 
 
         // Show its context menu 
         var contextMenu = automationObject.ContextMenu as ObjectContextMenu; 
         if (contextMenu != null) 
         { 
            contextMenu.Automation = automation; 
            contextMenu.Show(imageViewer, position); 
         } 
      }; 
 
      // Handler for show the object properties dialog 
      EventHandler<AnnAutomationEventArgs> onShowObjectProperties = (sender, e) => 
      { 
         // Get the automation object from the document viewer 
         using (var dlg = new AutomationUpdateObjectDialog()) 
         { 
            dlg.UserName = _documentViewer.UserName; 
            dlg.Automation = sender as AnnAutomation; 
            dlg.ShowDialog(this); 
            e.Cancel = !dlg.IsModified; 
         } 
      }; 
 
      // Handle extra annotations using the Operation event 
      _documentViewer.Operation += (sender, e) => 
      { 
         switch (e.Operation) 
         { 
            case DocumentViewerOperation.LoadingAnnotations: 
               // Disable the panel where we put the toolbar when we are loading, enable when we are done 
               rightPanel.Enabled = e.IsPostOperation; 
               break; 
 
            case DocumentViewerOperation.CreateAutomation: 
               if (e.IsPostOperation) 
               { 
                  // Automation object has been created, use it to perform any extra task not handled by the 
                  // document viewer by default 
                  // We will handle showing the context menu when the user right clicks on an object and when they 
                  // select properties 
                  _documentViewer.Annotations.Automation.OnShowContextMenu += onShowContextMenu; 
                  _documentViewer.Annotations.Automation.OnShowObjectProperties += onShowObjectProperties; 
               } 
               break; 
 
            case DocumentViewerOperation.DestroyAutomation: 
               if (!e.IsPostOperation) 
               { 
                  // Automation is about to be destroyed, remove any events we used 
                  _documentViewer.Annotations.Automation.OnShowContextMenu -= onShowContextMenu; 
                  _documentViewer.Annotations.Automation.OnShowObjectProperties -= onShowObjectProperties; 
               } 
               break; 
 
            default: 
               break; 
         } 
      }; 
   } 
 
   private void InitUI() 
   { 
      // Add a panel on the left for the document viewer thumbnails part 
      var leftPanel = new Panel(); 
      leftPanel.Name = "leftPanel"; 
      leftPanel.Width = 200; 
      leftPanel.Dock = DockStyle.Left; 
      leftPanel.BackColor = Color.Gray; 
      leftPanel.BorderStyle = BorderStyle.FixedSingle; 
      this.Controls.Add(leftPanel); 
 
      // Add a panel to the right, this will work for the bookmarks or annotations part 
      var rightPanel = new Panel(); 
      rightPanel.Name = "rightPanel"; 
      rightPanel.Width = 200; 
      rightPanel.Dock = DockStyle.Right; 
      rightPanel.BackColor = Color.LightBlue; 
      rightPanel.BorderStyle = BorderStyle.FixedSingle; 
      this.Controls.Add(rightPanel); 
 
      // Add a panel to fill the rest, for the document viewer 
      var middlePanel = new Panel(); 
      middlePanel.Name = "middlePanel"; 
      middlePanel.BackColor = Color.DarkGray; 
      middlePanel.BorderStyle = BorderStyle.None; 
      middlePanel.Dock = DockStyle.Fill; 
      this.Controls.Add(middlePanel); 
 
      // Add a top panel to host our application controls 
      var topPanel = new Panel(); 
      topPanel.Name = "topPanel"; 
      topPanel.Height = 100; 
      topPanel.Dock = DockStyle.Top; 
      topPanel.BorderStyle = BorderStyle.FixedSingle; 
      this.Controls.Add(topPanel); 
 
      middlePanel.BringToFront(); 
 
      // Add buttons for the UI 
 
      // Combo box for interactive modes 
      var interactiveComboBox = new ComboBox(); 
      interactiveComboBox.Name = "interactiveComboBox"; 
      interactiveComboBox.DropDownStyle = ComboBoxStyle.DropDownList; 
      // The command names for the items so we can just run them 
      interactiveComboBox.Items.Add(DocumentViewerCommands.InteractivePanZoom); 
      interactiveComboBox.Items.Add(DocumentViewerCommands.InteractiveSelectText); 
      interactiveComboBox.SelectedIndexChanged += (sender, e) => 
      { 
         var commandName = interactiveComboBox.SelectedItem as string; 
         _documentViewer.Commands.Run(commandName); 
      }; 
      topPanel.Controls.Add(interactiveComboBox); 
 
      // Generic label for information used by the examples 
      var infoLabel = new Label(); 
      infoLabel.Name = "infoLabel"; 
      infoLabel.Text = "Info..."; 
      infoLabel.AutoSize = false; 
      infoLabel.Width = 400; 
      infoLabel.Left = interactiveComboBox.Right + 20; 
      topPanel.Controls.Add(infoLabel); 
 
      var exampleButton = new Button(); 
      exampleButton.Top = interactiveComboBox.Bottom + 2; 
      exampleButton.Name = "exampleButton"; 
      exampleButton.Text = "&Example"; 
      exampleButton.Click += (sender, e) => Example(exampleButton); 
      topPanel.Controls.Add(exampleButton); 
   } 
 
   private void Example(Button exampleButton) 
   { 
      // Add the example code here 
      MessageBox.Show(this, "Ready"); 
   } 
Imports Leadtools 
Imports Leadtools.Controls 
Imports Leadtools.Documents 
Imports Leadtools.Documents.UI 
Imports Leadtools.Documents.Converters 
Imports Leadtools.Codecs 
Imports Leadtools.Caching 
Imports Leadtools.Annotations.Core 
Imports Leadtools.Annotations.Automation 
Imports Leadtools.Annotations.WinForms 
Imports Leadtools.Annotations.Designers 
Imports Leadtools.Forms.DocumentWriters 
Imports Leadtools.Forms.Ocr 
 
Public Sub DocumentViewerWithAnnotations_Example() 
   ' New Form to be used as our application 
   Dim form As New MyForm() 
   form.ShowDialog() 
End Sub 
 
Class MyForm 
   Inherits Form 
   Public Sub New() 
      Me.Size = New Size(800, 800) 
      Me.Text = "LEADTOOLS Document Viewer Example" 
   End Sub 
 
   Protected Overrides Sub OnLoad(e As EventArgs) 
      If Not DesignMode Then 
         Init() 
      End If 
 
      MyBase.OnLoad(e) 
   End Sub 
 
   ' Our document viewer instance 
   Private _documentViewer As DocumentViewer 
 
   Private Sub Init() 
      ' Initialize the user interface 
      InitUI() 
 
      ' Init the cache. This is optional, but it can speed up viewing of large documents 
      ' if not needed, remove this section 
      DocumentFactory.Cache = New FileCache() 
 
      ' Init the document viewer, pass along the panels 
      Dim createOptions As New DocumentViewerCreateOptions() 
      ' The middle panel for the view 
      createOptions.ViewContainer = Me.Controls.Find("middlePanel", False)(0) 
      ' The left panel for the thumbnails 
      createOptions.ThumbnailsContainer = Me.Controls.Find("leftPanel", False)(0) 
      ' Using annotations in this example 
      createOptions.UseAnnotations = True 
 
      ' Create the document viewer 
      _documentViewer = DocumentViewerFactory.CreateDocumentViewer(createOptions) 
 
      ' We prefer SVG viewing 
      _documentViewer.View.PreferredItemType = DocumentViewerItemType.Svg 
 
      ' Initalize the annotations 
      InitAnnotations() 
 
      ' Load a document 
      Dim fileName As String = "C:\Users\Public\Documents\LEADTOOLS Images\Leadtools.pdf" 
      Dim loadOptoins As New LoadDocumentOptions() 
      loadOptoins.UseCache = Not IsNothing(DocumentFactory.Cache) 
      Dim Document As Document = DocumentFactory.LoadFromFile(fileName, loadOptoins) 
 
      ' Set it in the viewer 
      _documentViewer.SetDocument(Document) 
 
      ' Run pan/zoom 
      Dim interactiveComboBox As ComboBox = CType(Me.Controls.Find("interactiveComboBox", True)(0), ComboBox) 
      interactiveComboBox.SelectedItem = DocumentViewerCommands.InteractivePanZoom 
   End Sub 
 
   Private Sub InitAnnotations() 
      ' The annotations toolbar will be added here 
      Dim rightPanel As Control = Me.Controls.Find("rightPanel", True)(0) 
 
      ' Get the automation manager from the document viewer 
      Dim automationManager As AnnAutomationManager = _documentViewer.Annotations.AutomationManager 
      ' Create the manager helper. This sets the rendering engine 
      Dim automationManagerHelper As New AutomationManagerHelper(automationManager) 
      ' Tell the document viewer that automation manager helper is created 
      _documentViewer.Annotations.Initialize() 
 
      ' Craete the toolbar 
      automationManagerHelper.ModifyToolBarParentVisiblity = True 
      automationManagerHelper.CreateToolBar() 
      Dim toolBar As ToolBar = automationManagerHelper.ToolBar 
      toolBar.Dock = DockStyle.Fill 
      toolBar.AutoSize = True 
      toolBar.BorderStyle = BorderStyle.None 
      toolBar.Appearance = ToolBarAppearance.Flat 
      rightPanel.Controls.Add(toolBar) 
      toolBar.BringToFront() 
 
      ' Handler for showing the context menu when the user right clicks on an annotation object 
      Dim onShowContextMenu As EventHandler(Of AnnAutomationEventArgs) = 
         Sub(sender, e) 
            ' Get the object type 
            Dim automationObject As AnnAutomationObject = e.Object 
            If automationObject Is Nothing Then Return 
 
            ' Convert the point to client coordinates 
            Dim imageViewer As ImageViewer = _documentViewer.View.ImageViewer 
            Dim position As Point = imageViewer.PointToClient(Cursor.Position) 
            Dim automation As AnnAutomation = _documentViewer.Annotations.Automation 
 
            ' Show its context menu 
            Dim contextMenu As ObjectContextMenu = CType(automationObject.ContextMenu, ObjectContextMenu) 
            If Not IsNothing(contextMenu) Then 
               contextMenu.Automation = automation 
               contextMenu.Show(imageViewer, position) 
            End If 
         End Sub 
 
      ' Handler for show the object properties dialog 
      Dim onShowObjectProperties As EventHandler(Of AnnAutomationEventArgs) = 
         Sub(sender, e) 
            ' Get the automation object from the document viewer 
            Using dlg As New AutomationUpdateObjectDialog() 
               dlg.UserName = _documentViewer.UserName 
               dlg.Automation = CType(sender, AnnAutomation) 
               dlg.ShowDialog(Me) 
               e.Cancel = Not dlg.IsModified 
            End Using 
         End Sub 
 
      ' Handle extra annotations using the Operation event 
      AddHandler _documentViewer.Operation, 
         Sub(sender, e) 
            Select Case e.Operation 
               Case DocumentViewerOperation.LoadingAnnotations 
                  ' Disable the panel where we put the toolbar when we are loading, enable when we are done 
                  rightPanel.Enabled = e.IsPostOperation 
 
               Case DocumentViewerOperation.CreateAutomation 
                  If e.IsPostOperation Then 
                     ' Automation object has been created, use it to perform any extra task not handled by the 
                     ' document viewer by default 
                     ' We will handle showing the context menu when the user right clicks on an object and when they 
                     ' select properties 
                     AddHandler _documentViewer.Annotations.Automation.OnShowContextMenu, onShowContextMenu 
                     AddHandler _documentViewer.Annotations.Automation.OnShowObjectProperties, onShowObjectProperties 
                  End If 
 
               Case DocumentViewerOperation.DestroyAutomation 
                  If Not e.IsPostOperation Then 
                     ' Automation is about to be destroyed, remove any events we used 
                     RemoveHandler _documentViewer.Annotations.Automation.OnShowContextMenu, onShowContextMenu 
                     RemoveHandler _documentViewer.Annotations.Automation.OnShowObjectProperties, onShowObjectProperties 
                  End If 
            End Select 
         End Sub 
   End Sub 
 
   Private Sub InitUI() 
      ' Add a panel on the left for the document viewer thumbnails part 
      Dim leftPanel As New Panel() 
      leftPanel.Name = "leftPanel" 
      leftPanel.Width = 200 
      leftPanel.Dock = DockStyle.Left 
      leftPanel.BackColor = Color.Gray 
      leftPanel.BorderStyle = BorderStyle.FixedSingle 
      Me.Controls.Add(leftPanel) 
 
      ' Add a panel to the right, this will work for the bookmarks or annotations part 
      Dim rightPanel As New Panel() 
      rightPanel.Name = "rightPanel" 
      rightPanel.Width = 200 
      rightPanel.Dock = DockStyle.Right 
      rightPanel.BackColor = Color.LightBlue 
      rightPanel.BorderStyle = BorderStyle.FixedSingle 
      Me.Controls.Add(rightPanel) 
 
      ' Add a panel to fill the rest, for the document viewer 
      Dim middlePanel As New Panel() 
      middlePanel.Name = "middlePanel" 
      middlePanel.BackColor = Color.DarkGray 
      middlePanel.BorderStyle = BorderStyle.None 
      middlePanel.Dock = DockStyle.Fill 
      Me.Controls.Add(middlePanel) 
 
      ' Add a top panel to host our application controls 
      Dim topPanel As New Panel() 
      topPanel.Name = "topPanel" 
      topPanel.Height = 100 
      topPanel.Dock = DockStyle.Top 
      topPanel.BorderStyle = BorderStyle.FixedSingle 
      Me.Controls.Add(topPanel) 
 
      middlePanel.BringToFront() 
 
      ' Add buttons for the UI 
 
      ' Combo box for interactive modes 
      Dim interactiveComboBox As New ComboBox() 
      interactiveComboBox.Name = "interactiveComboBox" 
      interactiveComboBox.DropDownStyle = ComboBoxStyle.DropDownList 
      ' The command names for the items so we can just run them 
      interactiveComboBox.Items.Add(DocumentViewerCommands.InteractivePanZoom) 
      interactiveComboBox.Items.Add(DocumentViewerCommands.InteractiveSelectText) 
      AddHandler interactiveComboBox.SelectedIndexChanged, 
         Sub(sender, e) 
            Dim commandName As String = CType(interactiveComboBox.SelectedItem, String) 
            _documentViewer.Commands.Run(commandName) 
         End Sub 
      topPanel.Controls.Add(interactiveComboBox) 
 
      ' Generic label for information used by the examples 
      Dim infoLabel As New Label() 
      infoLabel.Name = "infoLabel" 
      infoLabel.Text = "Info..." 
      infoLabel.AutoSize = False 
      infoLabel.Width = 400 
      infoLabel.Left = interactiveComboBox.Right + 20 
      topPanel.Controls.Add(infoLabel) 
 
      Dim exampleButton As New Button() 
      exampleButton.Top = interactiveComboBox.Bottom + 2 
      exampleButton.Name = "exampleButton" 
      exampleButton.Text = "&Example" 
      AddHandler exampleButton.Click, Sub(sender, e) Example(exampleButton) 
      topPanel.Controls.Add(exampleButton) 
   End Sub 
 
   Private Sub Example(exampleButton As Button) 
      ' Add the example code here 
      MessageBox.Show(Me, "Ready") 
   End Sub

Requirements

Target Platforms

Help Version 19.0.2017.10.27
Products | Support | Contact Us | Copyright Notices
© 1991-2017 LEAD Technologies, Inc. All Rights Reserved.

Leadtools.Documents.UI.WinForms Assembly
Introduction
Getting Started
Namespaces
Leadtools.Documents.UI Namespace
Assemblies