References ▼
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's 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 whether 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 entire document |
| error |
The exception object if an error occurs during the running of the operation |
| abort |
Can be set by the application to abort running the application |
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 entire document: |
| data1 | DocumentBookmark instance |
This is the DocumentBookmark object being passed to gotoBookmark as 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 happened 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 override the default behavior of the operation |
When the event returns to the document viewer, it checks the value of abort, and if 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 as from before, indicating the action that 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 entire 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 cannot be aborted anymore |
The following is a list of the document viewer operations, when 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 |
|---|---|---|---|---|---|---|
| runCommand |
commands is running any of the built-in or custom commands |
DocumentViewerCommand object being run |
The optional value passed to DocumentViewerCommands.run |
Not used (0) |
Setting abort to true will cancel running the command |
The command is run |
| operation | Occurs | data1 | data2 | pageNumber | isPostOperation false action | isPostOperation true action |
|---|---|---|---|---|---|---|
| SetDocument | DocumentViewer.setDocument is called | The new LEADDocument object passed to the method | The old LEADDocument, if any | Not used (0) | Setting abort to true will cancel replacing the new document in the viewer | The document is set in the viewer |
| detachFromDocument | DocumentViewer.setDocument is called and a current DocumentViewer.document must be removed. | The old LEADDocument, if any | The new LEADDocument object passed to the method | Not used (0) | Setting abort to true will cancel replacing the new document in the viewer | The old LEADDocument is detached but still set to DocumentViewer.document |
| attachToDocument | DocumentViewer.setDocument is called and a new DocumentViewer.document must be bound. | The new LEADDocument object passed to the method | The old LEADDocument, if any | Not used (0) | Setting abort to true will have no effect | The document is set in the viewer |
| gotoPage |
DocumentViewer.gotoPage is being called as the result of the user clicking 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 |
| printPages |
DocumentViewer.print is preparing page images for printing |
DocumentPrintData for this print operation |
null |
Page number |
Setting abort to true will abort the entire operation. |
The DocumentPrintPageData is finalized. |
| 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 |
Not used (0) |
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 |
Not used (0) |
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 is calling DocumentPage.GetImageElement, DocumentPage.GetSvgElement, or DocumentPage.GetSvgBackImageElement to obtain the image data for a page that has come into view, or DocumentViewer.Print is requesting page data to print with |
The ImageLoader instance used for loading if loading the image, but null if loading a back image or the page has no image data associated with it |
The ImageLoader instance used for loading if loading the back image, or the DocumentPrintPageData if used for printing. Otherwise, null |
Page number |
Setting abort to true will cancel this operation and the image data of this page not be used in the view. If DocumentViewer.Print is the caller, the printing page will have no image data. |
The page image data is updated |
| RenderItemPlaceholder |
view is rendering the place holder of a page that does not have its image data loaded. The default behavior is rendering the text |
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 |
| renderViewPage | view is rendering a DocumentPage | When isPostOperation is true, a boolean to indicate whether the render was internally canceled because a new render was queued; otherwise, not used | Not used | Page number | Setting abort to true will not cancel the render. | The DocumentPage is fully rendered |
| runLink |
The user has clicked a link on a page using DocumentViewerPageLinksInteractiveMode and DocumentViewer.runLinkTarget is about to be called |
DocumentLink object. runLinkTarget handles link targets that are locations within 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 whether 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 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 a 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, the result is DocumentViewerView.itemType being set to a new value. The LEADTOOLS Document Viewer uses this value to update the |
New value for DocumentViewerView.itemType |
Not used |
Not used (0) |
Setting abort to true will cancel this operation and the item type is not changed. |
The item type is changed. |
| pageRotate | When the user rotates one or more pages using rotatePages. | Not used | Not used | Page number | Setting abort to true will cancel this operation and the page will not be rotated. | The page is rotated. |
| pageDisabled | When the user marks a page as disabled using disablePages. | Not used | Not used | Page number | Setting abort to true will cancel this operation and the page will not be affected. | The page is marked as disabled. |
| pageEnabled | When the user marks a page as enabled using enablePages. | Not used | Not used | Page number | Setting abort to true will cancel this operation and the page will not be affected. | The page is marked as enabled. |
| pagesDisabledEnabled | When the user is marking one or more pages as enabled or disabled using enablePages or disablePages. | Not used | Not used | Array of page numbers | Setting abort to true will cancel this operation and the pages will not be affected. | The pages are enabled or disabled. |
| currentPageNumberChanged | When the DocumentViewer.currentPageNumber (used in applications to reference the page number to which certain commands will be applied) is changing. | An instance of CurrentPageNumberChangeData describing the change | Not used | Not used (0) | Setting abort to true will cancel this operation and the DocumentViewer.currentPageNumber will not change. | DocumentViewer.currentPageNumber is updated. |
| 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 will not be loaded |
All thumbnails are loaded and the background thread exists. DocumentViewerThumbnails.isLoading will be false. |
| GetThumbnail |
The Thumbnails is calling DocumentPage.getThumbnailImageElement for a page |
The thumbnail image when DocumentViewerThumbnails.useGrids is true and isPostOperation is true; otherwise, the ImageLoader used in the request | When DocumentViewerThumbnails.useGrids is true, the first page number loaded in the grid; otherwise, not used | When DocumentViewerThumbnails.useGrids is true, the last page number loaded in the grid; otherwise, the page number of the thumbnail image |
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 |
| renderThumbnailPage | thumbnails is rendering a DocumentPage | When isPostOperation is true, a boolean to indicate whether the render was internally canceled because a new render was queued; otherwise, not used | Not used | Page number | Setting abort to true will not cancel the render. | The DocumentPage is fully rendered |
| 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 will not be 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 of the annotations user interface until createAutomation occurs. Setting abort to true will cancel starting the thread and the annotation containers will not be loaded. DocumentViewerAnnotations.IsLoading will be true |
All the annotation containers are loaded and read. CreateAutomation operation will occur next. DocumentViewerAnnotations.IsLoading will be false |
| getAnnotations |
annotations background thread is retrieving the annotations for all pages |
null The annotation container when isPostOperation is true |
Not used |
Not used (0) |
Setting abort to true will cancel this operation and the page will not have an annotation container associated with it |
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 AnnAutomation object when isPostOperation is true |
Not used |
Not used (0) |
Setting abort to true will cancel cth creation of 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 it 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 |
Not used |
Not used (0) |
Application must unhook 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 will not be 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 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 only 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 |
| findText |
DocumentViewerText.find has begun or is completed for a given page or all pages |
A clone of the provided DocumentViewerFindText options |
The results of the search, which will be null if isPostOperation is false or there are no matches |
Page Number |
Setting abort to true will cancel the operation and the default action does not occur |
Search has completed for the page(s) |
| RenderFoundText |
A repaint occurs after a DocumentViewerText.find completes successfully with results |
ImageViewerRenderEventArgs containing the target context to use for rendering the found text |
A list of DocumentViewerTextItem that contains the rendering found text items |
Page Number |
Setting abort to true will cancel the operation and the default action does not occur |
The found text is rendered on the page |