Textract Scenarios: Scenario Editor and TextrextScenarioExec()

Textract Scenarios: Scenario Editor and TextrextScenarioExec() function

Downloads: Current Textract supports Scenarios: textra.exe. Textract beta with Scenarios.NET support: textrabeta.exe.

Scenarios are the extension to the basic Textract API. Technically, Scenarios are represented by Scenario Editor and TextrextScenarioExec() function. Scenario Editor is a GUI program that you use to form a kind of prescriptions, named Scenarios and Scenario Groups, for the TextrextScenarioExec() function.

Basic Textract text capture library is presented by Textract API (Textract.DLL, TxtrOCX.dll OCX) and it operates with screen through window handles (HWND) or absolute coordinates. Thus any changes in window position such as its movement, resizing, and application reopening can mislead Textract to capture improper area. Basic Textract API requires thorough support from the program that uses it.

Capture: Thus we introduce capture as a description of window search method that is not based on HWND window handle or rectangle position on the screen. Rectangular Capture is specified (visually, using mouse, from within Scenario Editor) when application intended for text capturing is at real work. Application window can be placed in various ways on a desktop and capture follows these changes. It is tightly coupled with application window. Capture options are manyfold to provide capturing that is independent of window placement, to take into account application reopening, window maximization, movement of splitters, MDI and child windows.

Capture search function is based on analysis of tree of windows (HWND) so that it is possible to use strict comparison of window's title and class name as well as use regular expression as a template for window's title and class name. Also it can be specified for search function to skip some windows in the tree hierarchy or not use window's title or class name in searching process.

Anchor: Another problem that can be solved using scenarios is a false capture. It is possible the situation when several places (including incorrect ones) on the screen meet capture specifications, if search criteria is too soft. To prevent such an incorrect capture the anchor is introduced. Anchor is a visual screen element (bitmap) that must be present on screen to allow scenario to be executed. It can be a toolbar button, an icon or some other window element.

Scenario: From the point of view of an application that uses Textract, one screen capture has to return several strings of captured text. Thus the scenario is introduced. Scenario includes one or more captures specified for several rectangles on the screen. Scenario is designed as the entity to use in your application. The main Textract Scenario function TextrextScenarioExec() receives one or more scenarios and returns an array of named strings.

Terminal windows and Regexes: In some cases application needs substrings of a large captured text and it is not possible to predict a placement of these substrings in terms of rectangles inside windows. Typical example is a capture of terminal session from the terminal window. The most appropriate solution for this case would be to capture the whole terminal window content and then to extract required substrings. To fulfill substring extraction regular expressions can be utilized. Regular expressions are widely known among programmers and can be a satisfactory solution in most cases. Another approach is a text analysis by string functions (strstr(), etc.) or using Yacc-like grammar tools. Any of these approaches can be implemented in your application but Textract Scenarios support regular expressions only. To use other text-parsing tool you should capture all the text and then analyze it in your application. It is recommended to try to use regular expressions provided by scenarios. It can be the most simple, straightforward and quick solution.

Scenario Type: Lets consider a situation when your application has to support several third-party applications that are sources for a text capturing. For example, one of these applications can be a terminal window, another one is a dialog window and one more is a MDI application. On the other hand, all you need to get from them are several strings, for example, client name, client ID and some related fields (address, amount, diagnosis, comment�). Thus we introduce scenario type that provides results that are independent of text source application. Scenario of some scenario type guarantees that TextrextScenarioExec() returns expected strings defined for this scenario type. For example, all scenarios of type "ClientAddress" return client name and address strings and your application shouldn't care about the specific scenario in use. The only requirement is that scenario has to be of specified scenario type.

New scenarios can be created using Scenario Editor after your application is ready and even deployed. Then new scenario can be assigned to your application. No recompilation of your application is required.

The Role of Technician. Beside the end user and programmer scenarios scheme admit another role to be involved in the process, the role of technician. The idea is that technician, who is not a programmer, could create new scenarios, which can be used to capture text from the applications that are not known in advance. We call it technician, while different people can perform this role - somebody who goes to client side for a system installation, an advanced user, your reseller and, of course, the programmer. Thus your application can be unleashed from text source applications, to cover all usage cases, and without extra programming effort. Technician uses Scenario Editor as a tool to bind your application to the new text source.

Scenario Groups can be used to automatically recognize situation on the screen and select appropriate scenario type. Let us assume that user activates your application using hot key or system tray icon (this functionality is provided by HotIcon class from Textrext extension) when he/she decides that there is appropriate situation on the screen. For example, teller can activate cash dispensing or activate the work day summation, both being activated by the same hot key. The task of your application is to determinate the action depending on the screen content. Textract Scenarios provide the capability to solve this task. Several scenarios of different scenario types are combined into scenario group. In this case your application pass the scenario group to TextrextScenarioExec() and appropriate scenario will be selected and executed. Type of executed scenario is returned along with captured strings so that your application can decide the action upon the captured text.