Document Viewer Operations

DocumentViewer fires the DocumentViewer.Operation event before and after it performs any operation to allow the user to monitor, modify or abort the action as well as update the application state when an operation is run.

The operation mechanism allows the application to modify the behavior when the action happens through the end-user interaction with the document viewer and not directly by the application calling a method.

The Operation event will receive data of type DocumentViewerOperationEventArgs that contains the following members:

Member	Description
Operation	DocumentViewerOperation enumeration member that identifies the operation.
IsPostOperation	Indicates if the operation is about to run (false) or that the operation has been run (true).
Data1	First optional generic data object associated with the operation. The type and value of this depends on the operation.
Data2	Second optional generic data object associated with the operation. The type and value of this depends on the operation.
PageNumber	Page number associated with this operation. 0 if this operation is for the whole document.
Error	The exception object if an error occurred during running of the operation.
Abort	Can be set by the application to abort running the application.

Example

When the user clicks the mouse on an entry in the bookmarks container, the DocumentViewer.GotoBookmark method is called internally by the DocumentViewer. The application itself does not initiate the call and without the operation mechanism, it has no way of knowing what the user did. Instead, Operation is called and the application has a chance to log, modify or even abort the action.

Here are the steps:

The user clicks the entry in the bookmarks container.
Operation fires with the following members:

Member	Value	Description
Operation	DocumentViewerOperation.GotoBookmark	The operation type indicates what is about to happen. In this case, the DocumentViewer.GotoBookmark method is about to be called.
IsPostOperation	false	The action has not occurred yet. The document viewer is informing the application that it is about to call GotoBookmark.
PageNumber	0	Since this is an operation for the whole document.
Data1	DocumentBookmark instance	This is the DocumentBookmark object being passed to GotoBookmark is in Data1, the application can perform any action here, including modifying the behavior based on certain bookmarks.
Data2	null	Not used.
Error	null	Ignored. Error is never set to a value when IsPostOperation is false. The action has not happen yet to throw an error.
Abort	false	The application has the chance to gracefully abort this action. This can done as a result of prompting the user or to perform a custom action and overriding the default behavior of the operation.

When the event returns to the document viewer, it checks the value of Abort, and it is not false, it will proceed to call GotoBookmark using the bookmark object in Data1.
After the method returns, the Operation event fires again with the following members:

Member	Value	Description
Operation	DocumentViewerOperation.GotoBookmark	Same operation type from before. Indicating the action that had just happened
IsPostOperation	true	The action has run. The document viewer is informing the application that GotoBookmark had run and the content of the bookmark had been applied
PageNumber	0	Since this is an operation for the whole document
Data1	DocumentBookmark instance	The same DocumentBookmark object passed to GotoBookmark
Data2	null	Not used
Error	null or a value	If this value is null, then the operation was performed successfully, otherwise it will contain an exception object with the error details. The application can use this to show an error message to the user
Abort	Not used	The operation has run and we cannot abort it anymore

Operations

The following is a list of the document viewer operations, when do they occur and the value of Data1 and Data2. All the operations are members of the DocumentViewerOperation enumeration that are separated into logical categories below.

Operation	Occurs	Data1	Data2	PageNumber	IsPostOperation false action	IsPostOperation true action
SetDocument	DocumentViewer.SetDocument is called	The new Document object passed to the method	Not used	Not used (0)	Setting Abort to true will cancel replacing the new document in the viewer	The document is set in the viewer
GotoPage	DocumentViewer.GotoPage is being as the result of the user clicking on the thumbnails container	Not used	Not used	Page number	Setting Abort to true will leave the current page as is	The view moves to the new page
PagesAdded	User added pages to the Document object in the DocumentViewer	The 0-based start index of the first page added	A collection of DocumentPage objects being added	Undefined behavior: Setting Abort to true will cancel adding to the viewer only and the document and viewer will be out of sync.	The pages are added to the viewer. The view, thumbnails, annotations, text and bookmarks parts of the viewer are be updated.
PagesRemoved	User removed pages from the Document object in the DocumentViewer	The 0-based start index of the first page removed	A collection of DocumentPage objects being removed	Undefined behavior: Setting Abort to true will cancel removing from the viewer only and the document and viewer will be out of sync.	The pages are removed from the viewer. The view, thumbnails, annotations, text and bookmarks parts of the viewer are be updated.

Operation	Occurs	Data1	Data2	PageNumber	IsPostOperation false action	IsPostOperation true action
GetPage	View virtualizer is calling DocumentPage.GetImage or DocumentPage.GetSvg to obtain the image data for a page that has come into view	null when IsPostOperation is false The image data when IsPostOperation is true	Not used	Page number	Setting Abort to true will cancel this and the image data of this page not be used in the view	The page image data is updated
RenderItemPlaceholder	View virtualizer is rendering the place holder of a page that does not have the image data loaded. Default behavior is rendering the text `"Loading..."` on the page item in ImageViewer using ImageViewerRenderEventArgs set in Data1	ImageViewerRenderEventArgs that contains the rendering context to be used	Not used	Page number	Setting Abort to true will cancel the default behavior. Usually applications uses this to perform custom rendering of place holders	The default behavior of rendering `"Loading..."` is performed
RunLink	The user has clicked on a link on a page using DocumentViewerPageLinksInteractiveMode and DocumentViewer.RunLinkTarget is about to be called	DocumentLink object. RunLinkTarget handles link targets that are locations in the same document DocumentLinkType.TargetPage. If the value of LinkType is DocumentLinkType.Value, then the document viewer will not perform any action. The application can use this operation to check for this value and then custom handle DocumentLink.Value - for example, by checking if it is a hyperlink and starting a web browser instance pointing to it	The InteractiveEventArgs containing the mouse or touch current position and button status.	Page number	Setting Abort to true will cancel this and the link is not run	DocumentViewer.RunLinkTarget is called
HoverLink	The user has hovered the mouse over (entered) or hovered out of (left) a link area using on a page using DocumentViewerPageLinksInteractiveMode	DocumentLink object if the mouse is over a link or null if the mouse is not over any links. The application can use this operation to show rich user experience such as tool tip with the link value.	The InteractiveEventArgs containing the mouse or touch current position and button status.	Page number	Setting Abort to true will cancel this	Nothing
ItemTypeChanged	When a new document is set to the viewer and DocumentViewerView.PreferredItemType cannot be used, resulting in DocumentViewerView.ItemType being set to a new value. The LEADTOOLS Document Viewer uses this value to update the `View As Image` and `View As SVG` menu items	New value for DocumentViewerView.ItemType	Not used	Not used (0)	Setting Abort to true will cancel this and item type is not changed.	The item type is changed.

Operation	Occurs	Data1	Data2	PageNumber	IsPostOperation false action	IsPostOperation true action
LoadingThumbnails	Thumbnails is starting the background thread to get the thumbnail images from the document	Not used	Not used	Not used (0)	Setting Abort to true will cancel starting the thread and the thumbnails are not loaded	All thumbnails are loaded and the background thread exists. DocumentViewerThumbnails.IsLoading will be false.
GetThumbnail	Thumbnails background thread is calling DocumentPage.GetThumbnailImage for a page	Not used when IsPostOperation is false The thumbnail image when IsPostOperation is true	Not used	Page number	Setting Abort to true will cancel this and the page will not have an associated image in the thumbnails container	The page thumbnail image is updated

Operation	Occurs	Data1	Data2	PageNumber	IsPostOperation false action	IsPostOperation true action
LoadingBookmarks	Bookmarks is starting the background thread to parse the document and get the bookmark items	Not used	Not used	Not used (0)	Setting Abort to true will cancel starting the thread and the bookmarks are not parsed	All bookmarks are parsed and the background thread exists. DocumentViewerBookmarks.IsLoading will be false.
GotoBookmark	DocumentViewer.GotoBookmark is being called either directly or as a result of the user clicking an item in the bookmarks container	DocumentBookmark object	Not used	Not used (0)	Setting Abort to true will cancel the operation and the bookmarks target will not be applied	The bookmark target is applied

Operation	Occurs	Data1	Data2	PageNumber	IsPostOperation false action	IsPostOperation true action
LoadingAnnotations	Annotations is starting the background thread to load the annotation containers for each page from the document	Not used	Not used	Not used (0)	Application must disable all the annotations user interface till CreateAutomation occurs. Setting Abort to true will cancel starting the thread and the annotation containers are not loaded. DocumentViewerAnnotations.IsLoading will be true	All the annotation containers are and read. CreateAutomation operation will occur next. DocumentViewerAnnotations.IsLoading will be false
GetAnnotations	Annotations background thread is calling DocumentPage.GetAnnotations for a page	null when IsPostOperation is false The annotation container when IsPostOperation is true	Not used	Page number	Setting Abort to true will cancel this and the page will not have an associated annotation container	The annotations container for the page is saved internally
CreateAutomation	Annotations has finished loading the annotation containers for all the pages and is about to create the Automation object	null when IsPostOperation is false AnnAutomation object when IsPostOperation is true	Not used	Not used (0)	Setting Abort to true will cancel create the Automation object and annotations automation support will not work	The Automation object has been created, the annotations containers for the pages are added to it and is ready to use. Application must enable the annotations user interface elements and use AnnAutomation events if needed
DestroyAutomation	The current Document object in the viewer has been replaced or set to null	AnnAutomation object when IsPostOperation is false null when IsPostOperation is true	Not used	Not used (0)	Application must unhook for all the events subscribed in CreateAutomation and the annotations user interface elements must be disabled. Setting Abort to true will cancel the operation and the automation object is not destroyed	AnnAutomation is destroyed
AutomationStateChanged	The current designer or user mode of the AnnAutomation has been changed	Not used	Not used	Not used (0)	Cannot be aborted	The application can check the values of AnnAutomation and update the user interface element

Operation	Occurs	Data1	Data2	PageNumber	IsPostOperation false action	IsPostOperation true action
GetText	Text is calling DocumentPage.GetText to get the DocumentPageText object for a page	null when IsPostOperation is false The DocumentPageText object when IsPostOperation is true	Not used	Page number	Setting Abort to true will cancel getting the text for the page. Application can show a busy dialog to the user and disable the user interface	Application can remove the busy dialog and re-enable the user interface. All text operations for this page are available now
TextSelectionChanged	The selected text in the document is changing.	Not used	Not used	Not used (0)	Setting Abort to true will cancel changing the document text selection	Document viewer de-selects the annotations objects since either this or the text can be selected at one time
PageTextSelectionChanged	The selected text in a page has changed	Not used	Not used	Page number	Setting Abort to true will cancel changing the page text selection	Document viewer will invalidate the page in the View to highlight the selected text
RenderSelectedText	The selected text of a page is highlighted on the View	ImageViewerRenderEventArgs containing the target context to use for highlighting the text	A list of DocumentViewerTextItem that contains the new selected text items	Page Number	Setting Abort to true will cancel the operation and the default action does not occur. Application can use this to perform custom rendering of the selected text	The selected text is highlighted on the page
SelectedTextToReviewObject	The user has drawn a new AnnTextReviewObject derived annotation object on a page	Object that derives from AnnTextReviewObject	Not used	Page Number	Setting Abort to true will cancel the operation and the default action does not occur.	The selected text item rectangles are set in the object. The object is added to the page annotation container and is selected

Document Viewer Operations

Example

Operations

Command Operations

DocumentViewer Operations

View Operations

Thumbnails Operations

Bookmarks Operations

Annotations Operations

Text Operations

Reference