Document Viewer Commands

DocumentViewer uses the commands 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).

Why Use Commands

DocumentViewer contains many parts that must be kept in sync. These parts uses public LEADTOOLS classes and controls such as ImageViewer or AnnAutomation and all actions is performed using the public and documented properties and methods of the classes.

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

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

1. The application updates 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 set to Pan/Zoom, then the element must be disabled (or checked and should not be invoked), but disabled will be used for this example.

   The above can be performed using this code snippet:

void UpdatePanZoomUIState() { 
   // First test 
   panZoomElement.Enabled = documentViewer.HasDocument; 
   if(panZoomElement.Enabled) { 
      // Find the Pan/Zoom interactive mode, see if it is already enabled 
      var panZoom = documentViewer.View.ImageViewer.InteractiveModes.FindById(ImageViewerInteractiveMode.PanZoomMode); 
      // Second test, see if the mode is already enabled 
      panZoomElement.Enabled = !panZoom.IsEnabled; 
   } 
} 

1. When the user clicks the Pan/Zoom menu item, the application must perform the following:

   • Not just calling ImageViewerInteractiveModes.EnableById since this will disable all the other interactive modes. Annotations and Page Links modes should be kept enabled because they can be used along Pan/Zoom.

     When the user clicks an annotation object, it gets automated. When the user clicks on a page links, it must run and panning and zoom only happens when the user clicks outside these objects. So the process must loop through all the modes, disable all but Pan/Zoom, Annotations and Page Links.

   • If annotations is used, then any current designers must be canceled (For example, if the process run in the middle of a multi-click operation to draw a new polyline) and the current object ID in the toolbar back must set to Select.

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

   The above can be performed using this code snippet:

void SetPanZoom() { 
   // First action 
   foreach (var mode in documentViewer.View.ImageViewer.InteractiveModes) { 
      mode.IsEnabled = 
         mode.Id == ImageViewerInteractiveMode.PanZoomMode ||  
         mode.Id == DocumentViewer.AnnotationsInteractiveModeId || 
         mode.Id == 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 = AnnObject.SelectObjectId; 
   } 
   // Third action 
   UpdatePanZoomUIState(); 
} 

Running Commands

The above code must be exactly right to get all the parts of the document viewer in sync and this is only for a single simple action: Setting the current interactive mode.

DocumentViewer comes with a built-in command that sets the pan/zoom interactive mode. The name of the command is %"Interactive.PanZoom":F:Leadtools.Documents.UI.DocumentViewerCommands.InteractivePanZoom%. The commands system can be used to shortened the above two methods code into one line as the following:

void UpdatePanZoomUIState() { 
   panZoomElement.Enabled = documentViewer.Commands.CanRun(DocumentViewerCommands.InteractivePanZoom, null); 
} 
void SetPanZoom() { 
   documentViewer.Commands.Run(DocumentViewerCommands.InteractivePanZoom, null); 
} 

The built-in commands handle more complex actions cleanly and ensure all parts of the document viewer are kept in sync. Any command can be identified by a unique simple constant string, and thus, binding commands with the user interface can be achieved easily.

Command Parameters and Results

The null parameters passed to the CanRun and Run methods are because InteractivePanZoom does not take any parameters. Some commands such PageGoto required as a parameter (the page number in this case) and must be invoked like this:

// Goto page number 10 in the viewer 
documentViewer.Commands.Run(DocumentViewerCommands.PageGoto, 10); 

The parameters of a command is a generic object type. The command will perform the necessary conversion if required - to an integer value in the case of PageGoto.

CanRun will also take a parameter for these commands:

value = documentViewer.Commands.CanRun(DocumentViewerCommands.PageGoto, 10);

And "value" will be true if a document contains at least 10 pages or more and the current page number is not 10 already. Otherwise; false.

Run always return the result from running the command and this result is also a generic object. The commands discussed above all return null since they do not return any results. Some commands like TextExport will return the text of a page (or the document) as a string object. Note that TextExport also accepts the page number as a parameter, or if null or 0 passed, will return the text for all the pages:

// Get the text for page number 10 as a string 
string text = (string) documentViewer.Commands.Run(DocumentViewerCommands.TextExport, 10); 

State Commands

In addition to CanRun and Run, some commands contain a boolean state. For example, the InteractiveAutoPan can be used to enable/disable auto-panning that is used along the other interactive modes. The user interface element these commands usually uses a check mark to indicate the state. The application can use this command as follows:

void UpdateAutoPanUItate() { 
   // Can we run the command? 
   autoPanElement.Enabled = documentViewer.Commands.CanRun(DocumentViewerCommands.InteractiveAutoPan, null); 
   // Get the command 
   var command = documentViewer.Commands.GetCommand(DocumentViewerCommands.InteractiveAutoPan); 
   // Use its current state 
   autoPan.Checked = command.State; 
} 
void 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(DocumentViewerCommands.InteractiveAutoPan, null); 
} 

Slow Commands

Although most of the actions performed on the document viewer are instant, some operations might take a considerable amount of time depending on the viewer state and the data requested.

For example, the TextExport command discussed above 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 caches the DocumentPageText objects for the pages internally once they are obtained. The first time the text of a page might be slow, but subsequent requests are instant.

TextExport performs the following (simplified and ignoring the DocumentViewer.Operation events involved):

1. Checks if Text has a DocumentPageText object for the requested page cached, if so, it will parse the text and return the result and exits - this operation is instant.

2. Next, it will check the value Text.AutoGetText, if this value is false, then the application requested that DocumentPage.GetText not to be invoked instantly. Thus the method returns an empty string - this operation is instant.

3. If the value of Text.AutoGetText is true, then DocumentPage.GetText is invoked and if the original document does not support SVG (such as a TIFF or raster PDF document), then the operation will use OCR and might take a few seconds to return. Text will wait for this to finish, caches the DocumentPageText before parses the data from it and returning - this operation is slow.

4. The next time TextExport is called on this same page, and as described in the first step, the text is parsed from the cached data and the result is returned. DocumentPage.GetText is not called - this operation is instant.

From the above, calling Run with TextExport may not return control to the application immediately. If this command is to be performed from a user interface element directly then the UI thread of the application will freeze and not be responsive till the method return.

One solution is to perform the following when the user select 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 have the negative effect of showing/hiding this busy dialog always, even if the command will be instant (as in most of the cases described above). In most applications this will result in the undesirable action of the screen flickering for a moment.

The other option is to use the DocumentViewerCommands.IsSlow method. Each command will return true or false based on its internal current state and calculation. As described above in the case of TextExport. Here is the solution described above to handle Text Export UI element but with using IsSlow:

1. Call documentCommands.IsSlow(DocumentViewerCommands.TextExport, 10)

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

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

This will eliminate the flickering problem described above but not showing the busy dialog unless required.

Running Commands Asynchronously

In addition to DocumentViewerCommands.Run, the DocumentViewerCommands.RunAsync method can be used to run a command asynchronously. This is useful for especially for slow commands and will perform the action of creating a thread to run the command, handle errors and clean up easily.

Using the same TextExport command from before, here's how to run it asynchronously:

// Create a new DocumentViewerAsyncOperation object 
var async = new DocumentViewerAsyncOperation(); 
// Set the delegate to be called if an error occurs 
async.Error = (DocumentViewerAsyncOperation operation, Exception error) => { 
   HandleError(error); 
}; 
// Set the delegate to be called after the run, successfully or when an error occurs 
async.Always = (DocumentViewerAsyncOperation operation) => { 
   // Hide the busy dialog 
   HideBusyDialog(); 
}; 
// Show the busy dialog 
// Run the command asynchronously in a worker thread 
documentViewer.Commands.RunAsync(async, DocumentViewerCommands.TextCopy, 10); 

Or with using IsSlow:

var isSlow = _documentViewer.Commands.IsSlow(DocumentViewerCommands.TextExport, 10); 
if (isSlow) { 
   // Command is slow, run asynchronously 
   // Create a new DocumentViewerAsyncOperation object 
   var async = new DocumentViewerAsyncOperation(); 
   // Set the delegate to be called if an error occurs 
   async.Error = (DocumentViewerAsyncOperation operation, Exception error) => { 
      HandleError(error); 
   }; 
   // Set the delegate to be called after the run, successfully or when an error occurs 
   async.Always = (DocumentViewerAsyncOperation operation) => { 
      // Hide the busy dialog 
      HideBusyDialog(); 
   }; 
   // Show the busy dialog 
   // Run the command asynchronously in a worker thread 
   _documentViewer.Commands.RunAsync(async, DocumentViewerCommands.TextCopy, 10); 
} else { 
   // Command is not slow, run directly 
   _documentViewer.Commands.Run(DocumentViewerCommands.TextCopy, 10); 
} 

DocumentViewerCommand Class

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

All the built-in commands are instance of DocumentViewerCommand objects that are initialized and ready to use. The callbacks are what gets used with DocumentViewerCommands.Run, DocumentViewerCommands.CanRun and DocumentViewerCommands.IsSlow are called.

DocumentViewerCommands Class

DocumentViewerCommands 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 document viewer. The key is the command unique name and the value is the corresponding DocumentViewerCommand object. It has the following members:

Built-in Commands

DocumentViewer 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

These commands use DocumentViewer.GotoPage

View Commands

These commands use DocumentViewerView and its ImageViewer

Layout Commands

These commands use pre-defined ImageViewerViewLayout objects to set in the view's ImageViewer

Interactive Commands

These commands use pre-defined ImageViewerInteractiveMode objects to set in the view's ImageViewer

Text Commands

These commands use methods from DocumentViewerText.

Annotation Commands

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