DocumentViewer Commands

The DocumentViewer uses a command system to perform actions. Each command is a data structure that contains the unique name of the command, whether it can run at the current state of the Document Viewer, optional arguments and results. DocumentViewerCommands manages the commands of the DocumentViewer and can be accessed by the DocumentViewer.Commands property.

Commands are generally tied to a user interface element in the application. The command properties can be used to enable or disable the element (if the command cannot be run at this time), set its state (for example, a checked box), and run the action when the user select the element (such as clicking on a button or a menu item).

Purpose of Using Commands

The DocumentViewer contains many parts that must be kept synchronized. These parts use public LEADTOOLS classes and controls such as the ImageViewer class or the AnnAutomation class, and all actions are performed using the public and documented properties and methods of the classes.

For example, the application has a menu item that sets the current interactive mode of the view to Pan/Zoom.

Pan/Zoom is one of the interactive modes added to the DocumentViewer by default. Its ID is ImageViewerInteractiveMode.panZoomModeId. Here are the steps required:

How to Implement a Low-Level Command System

First, the application should update the enabled/disabled state of the element as follows:

• If the document viewer does not have a document set, then the element must be disabled
• If the current interactive mode is already Pan/Zoom, then the element must be disabled or checked and should not be invoked. This example will disable the element.

The above can be performed using this code snippet:

function updatePanZoomUIState() { 
   // First test 
   $("#panZoomElement").prop("disabled", !documentViewer.hasDocument); 
   if (documentViewer.hasDocument) { 
      // Find the Pan/Zoom interactive mode, see if it is already enabled 
      var panZoom = documentViewer.view.imageViewer.interactiveModes.findById(lt.Controls.ImageViewerInteractiveMode.pPanZoomMode); 
      // Second test, see if the mode is already enabled 
      $("#panZoomElement").prop("disabled", panZoom.isEnabled); 
   } 
} 

Next, when the user clicks the Pan/Zoom menu item, the application must perform the following:

• One cannot just call ImageViewerInteractiveModes.EnableById since this will disable all the other interactive modes. The developer has to keep Annotations and Page Links modes enabled because they can be enabled with Pan/Zoom. When the user clicks an annotation object, it should be automated. When the user clicks on a page link, it must run. Pan and zoom should only happen when the user clicks outside those objects. To accomplish this, enumerate all the modes to disable all except Pan/Zoom, Annotations, and Page Links.

• If the annotations mode is used, then cancel any current designers (for example, if the user is in the middle of a multi-click operation to draw a new polyline) and set the current object ID in the toolbar back to Select.

• Finally, call UpdatePanZoomUIState again to disable the menu item.

The above can be performed using this code snippet:

function setPanZoom() { 
   // First action 
   for (var i = 0; i < documentViewer.view.imageViewer.count; i++) { 
      var mode = documentViewer.view.imageViewer.interactiveModes[i]; { 
      mode.isEnabled = 
         mode.id == lt.Controls.ImageViewerInteractiveMode.panZoomMode || 
         mode.id == lt.Documents.UI.DocumentViewer.annotationsInteractiveModeId || 
         mode.id == lt.Documents.UI.DocumentViewer.pageLinksInteractiveModeId; 
   } 
   // Second action 
   // We cannot just call .automation, the annotations might not be loaded yet, so we must check for that 
   if(documentViewer.annotations != null && documentViewer.annotations.automation != null) { 
      documentViewer.annotations.automation.cancel(); 
      documentViewer.annotations.automationManager.currentObjectId = lt.Annotations.Engine.AnnObject.selectObjectId; 
   } 
   // Third action 
   updatePanZoomUIState(); 
} 

How to Implement a High-Level Command System

The main advantage of implementing a high-level command system is that LEADTOOLS handles the command "plumbing". LEADTOOLS provides several built-in commands that can simplify code and reduce development time. The built-in commands handle more complex actions cleanly and ensure that all parts of the DocumentViewer are kept in sync. All commands are identified by unique simple string constants, so binding built-in commands to the user interface is easy.

The DocumentViewer comes with a built-in command that sets the pan/zoom interactive mode. The name of the command is lt.Documents.UI.DocumentViewerCommands.interactivePanZoom. We can use the command system to replace the code in the two methods' "Low-Level Implementation" by using one line of code:

function updatePanZoomUIState() { 
   $("#panZoomElement").prop("disabled", !documentViewer.commands.canRun(lt.Documents.UI.DocumentViewerCommands.interactivePanZoom, null)); 
} 
function setPanZoom() { 
   documentViewer.commands.run(lt.Documents.UI.DocumentViewerCommands.interactivePanZoom, null); 
} 

Command Parameters and Results

The value null is passed to the canRun and run methods because interactivePanZoom does not take any parameters. Some commands such pageGoto require a parameter (the page number) and must be invoked like this:

// Go to page number 10 
documentViewer.commands.run(lt.Documents.UI.DocumentViewerCommands.pageGoto, 10); 

The parameters of a command are a generic object type. The command will perform the necessary conversion, if required. In the case of pageGoto, the parameter will be converted to an integer.

canRun will also take a parameter for these commands:

value = documentViewer.commands.canRun(lt.Documents.UI.DocumentViewerCommands.pageGoto, 10); 

If the document has at least 10 pages, and the current page number is not 10 already, value will be true; otherwise, value will be false.

The run method always returns the result of running the command as a generic object. Some commands, such as textExport, return the text of a page or the document as a string object. Note that textExport also accepts the page number as a parameter. If null or 0 is passed, it will return the text for all the pages:

// Get the text for page number 10 as a string 
var text = documentViewer.commands.run(lt.Documents.UI.DocumentViewerCommands.textExport, 10); 

State Commands

In addition to canRun and run, some commands contain a boolean state property. For example, the interactiveAutoPan command is used to enable/disable auto-panning. usually use a check mark as a user interface element to indicate the state. For example:

function updateAutoPanUIState() { 
   // Can we run the command? 
   $("#autoPanElement").prop("disabled", !documentViewer.commands.canRun(lt.Documents.UI.DocumentViewerCommands.interactiveAutoPan, null)); 
   // Get the command 
   var command = documentViewer.commands.getCommand(lt.Documents.UI.DocumentViewerCommands.interactiveAutoPan); 
   // Use its current state 
   $("#autoPanElement").prop("checked", command.state); 
} 
function flipAutoPan() { 
   // Just call Run, the command knows it has a state and will flip it automatically, enabling or disabling auto-pan accordingly 
   documentViewer.commands.run(lt.Documents.UI.DocumentViewerCommands.interactiveAutoPan, null); 
} 

Long Running Commands

Although most of the actions performed on the DocumentViewer are performed instantly, some operations can take a considerable amount of time, depending on the viewer state and the data requested.

For example, the textExport command parses the text from the DocumentPageText object of a page obtained using DocumentPage.getText. This method parses the text from the page using either SVG or OCR technologies and, especially in the latter case, can take seconds to return. DocumentViewerText internally caches the DocumentPageText objects once they are obtained. The first request for page text will take longer than subsequent requests, which are relatively instant.

textExport performs the following (simplified and ignoring the DocumentViewer.operation events involved):

1. Checks if Text has a DocumentPageText object cached for the requested page. If so, it will parse the text and return the result; this operation is instant. If not, continue to the next step.

2. Checks the value of Text.AutoGetText.

   • If this value is false, then the application has requested that DocumentPage.GetText not to be automatically invoked. This method returns an empty string; this operation is instant.
   • If this value is true, then DocumentPage.GetText is invoked. If the original document does not support SVG (such as a TIFF or raster PDF document), then the operation will use OCR. Text will wait for this to finish, cache the DocumentPageText before parsing the data and returning; this operation is long-running. These commands

Based on the steps above, calling run with textExport may not immediately return control to the application. If this command is to be performed directly from a user interface element, then the UI thread of the application will be unresponsive until the method returns.

One solution is to perform the following when the user selects the Text Export UI element:

1. Show a busy dialog

2. Run the command in a separate thread

3. When the command returns, hide the busy dialog

This will work, but will have the negative effect of always showing/hiding a busy dialog, even if the command is instant. In most applications, this will result in an undesirable screen flicker.

Another option is to use the DocumentViewerCommands.isSlow method. Each command will return true or false based on its internal current state and calculations. The following a solution to handle the Text Export UI element using the IsSlow method:

1. Call documentCommands.isSlow(DocumentViewerCommands.textExport, 10)

2. If the result is true, show a busy dialog, run the command in a separate thread, then hide the busy dialog on completion

3. If the result is false, run the command in the UI thread

This will eliminate the screen-flicker problem described above by only showing the busy dialog when required.

DocumentViewerCommand Class

The DocumentViewerCommand class holds the data for each command. This class contains the following members:

All of the built-in commands are instances of DocumentViewerCommand objects that are initialized and ready to use. The callbacks are called when DocumentViewerCommands.Run, DocumentViewerCommands.CanRun, and DocumentViewerCommands.isSlow are called, respectively.

DocumentViewerCommands Class

The DocumentViewerCommands class manages the commands of the DocumentViewer and can be accessed by the DocumentViewer.Commands property. Internally, it stores a dictionary of all the commands of the DocumentViewer. The key is the command's unique name, and the value is the corresponding DocumentViewerCommand object. It has the following members:

Built-in Commands

The DocumentViewer class comes with the following built-in commands that can used right away. All the commands are initialized when DocumentViewer is created and stored in the DocumentViewerCommands class.

Page Commands

Page commands use DocumentViewer.gotoPage.

View Commands

View commands use the DocumentViewerView and its imageViewer control.

Layout Commands

Layout commands use pre-defined ImageViewerViewLayout objects to set in the view's ImageViewer control.

Interactive Commands

Interactive commands use pre-defined ImageViewerInteractiveMode objects to set in the view's ImageViewer control.

Text Commands

Text commands use methods from the DocumentViewerText object.

Annotation Commands

Annotation commands use methods from the DocumentViewerAnnotations and AnnAutomation objects. These commands provide the necessary checks to make sure the methods can be called without errors.

See Also

Using the LEADTOOLS DocumentViewer

DocumentViewer Operations

Document Library Features

Load Documents Using the LEADTOOLS Document Library

Create Documents Using the LEADTOOLS Document Library

Document Toolkit and Caching

Document View and Convert Redaction