DOKuStar Validation Programming Manual Océ Document Technologies GmbH
Océ Document Technologies GmbH Max-Stromeyer-Straße 116 D-78467 Konstanz - Germany Phone: ++49(0)75 31/87-0 Fax; ++40(0)7531/87-4567 E-Mail: sales@odt-oce.com www.odt-oce.com The reproduction, transmission or use of this document or its contents is not permitted without express written authority. Offenders will be liable for damages. All rights, including rights created by patent grant or registration of a utility model or design, are reserved. Availability and changes of technical information reserved.
Contents Introduction 1 Integration 2 Development Environments ......................................................................................................... 2 The Document Model: Overview................................................................................................. 7 Schema ......................................................................................................................................... 8 Manual Generation.............................................
DocumentTypes .............................................................................................................. 51 DocumentType................................................................................................................ 52 FieldTypes....................................................................................................................... 52 FieldType .................................................................................................................
Introduction This Programming Manual covers all topics related to programming in and around DOKuStar Validation. Usually, DOKuStar Validation shall be integrated into an existing environment. This could be a document capture workflow, where DOKuStar Validation could be used to manually enter index fields, or to correct fields read by a recognition engine.
Integration Development Environments There are different ways to start DOKuStar Validation. After DOKuStar Validation has been installed, a program group and optionally an icon on the desktop will appear for DOKuStar Validation. This is the obvious way to start the program. It will open in the Validation Operator Mode. This simply means: This is the way the validation operator will see the program.
Now open a DOS box, go to the bin directory of the DOKuStar Validation installation and start DOKuStar Validation with a command line parameter -a by entering: dsval –a: (dsval.exe is the executable for DOKuStar Validation). This will open DOKuStar Validation in Administrator Mode.
This is one place, where you can write code, no matter whether Integration Code or Scripting. This VBA studio will be described later. A completely different way of starting DOKuStar Validation is the following: DOKuStar Validation is a COM object. You can use it in any programming language and environment that can deal with COM objects, like Microsoft Visual Basic, Microsoft Visual C++, Borland Delphi, etc.
Now, create an instance of the DokuStarValidation.Application object and set its Visible property to true: Note: In this case, we placed these lines of code in the Form_Load event routine of a central Form object, but it is up to you, where you place it.
That’s all! Run this project, and DOKuStar Validation will be started from this small piece of code. When you choose to use DOKuStar Objects via this COM interface, you can write your integration code in the same environment as well. The DOKuStar Application object you created above an object that holds the data. You have full access to these objects and can fill them in your code. Also, all events are available in both worlds.
The Document Model: Overview In order to access fields, values, documents, etc., it is important to understand how data are organized in DOKuStar Validation. This data structure is called the Document Model. For a complete description of the document model, refer to the online reference. This document model is quite a large structure, and contains parts that you will probably never use. This manual concentrates on those items that are common to most applications.
Schema The schema holds the structure of the project. There are three ways how a schema can be generated: - manually within DOKuStar Validation itself - by software - by importing a DOKuStar Extraction project Each of these methods is described in the following sections. Manual Generation To generate a Schema manually: - Start DOKuStar Validation in Administrator Mode (dsval –a). - In the left window, switch to the Schema tab. - Use the command New of the File menu.
When you expand FieldClasses you will see two nodes named TextField and TableField. These denote the two different types of fields that exist in DOKuStar Validation. TextFields are basic fields that hold one single value, while TableFields hold a complete table, made up of rows and columns. Note that TextField has not the same meaning as the Text field in DOKuStar Extraction, where it stands for a basic reading area; Date fields, Amount fields, etc.
On the Invoice document, add two TextFields (TotalAmount and InvoiceDate) and one TableField (Details).
Now for the remaining two document types: As stated above, the sender is an information that belongs to the letter as a whole, so we assign this field to the Letter document type; the CoveringLetter will not be assigned any field: DOKuStar Validation Programming Manual Page • 11
Thus, we are finished with the document types and come to the hierarchical structure of our documents. This is done at the DocumentModel node: Expand it, and you will see a node named DocumentDescriptors.
Choose Letter, which shall become the topmost entity. This will generate a Letter node, which has two subnodes, named FieldDescriptors and again DocumentDescriptors.
The schema definition is finished. You can now save the project into a file using the Save command of the File menu. So, defining the schema is a two-step process: First, you define the document types and the index fields assigned to them. Second, you define the hierarchical structure. Note: Even if you don’t have a hierarchical structure within your documents, you must always define the DocumentModel part. The hierarchical structure is not limited in depth.
Generation by Software What we just did interactively can also be done through software, either in the VBA studio, or from the outside via the COM interface. We will do it now in Microsoft Visual Basic, expanding the small piece of code we had above (the VBA variant will be discussed later): Private Sub Form_Load() Dim MyApp As New DOKuStarDataset.Application DOKuStarValidation '* declare dataset part of '* make sure no project is open If Not MyApp.Project Is Nothing Then MyApp.Project.
Let us go through this step by step: Private Sub Form_Load() Dim MyApp As New DOKuStarDataset.Application DOKuStarValidation '* declare dataset part of '* make sure no project is open If Not MyApp.Project Is Nothing Then MyApp.Project.Close End If '* create the Project and fill the schema MyApp.CreateProject As before, we create an instance of DOKuStarValidationApplication.
docDescLetter.Descriptors.Add docTypeCovering docDescLetter.Descriptors.Add "Invoice" docDescLetter.Descriptors.Add docTypeVoucher ' add the subdocument ' alternative: add a subdocument by name Note that the Add method can either take a DocumentType object as the parameter (first line) or the name of the DocumentType object (second line). This convenience exists for many Add methods throughout the DokuStar Validation objects. Back in the main routine, we finally save the project: MyApp.Project.SaveAs App.
Data While the Schema object describes the structure, the Data object holds all the documents and their fields which shall be processed by the DOKuStar Validation operator. Again, there are three ways how DOKuStar Validation can be supplied with data - manually in the DOKuStar Validation itself - by software - by importing a DOKuStar Extraction result file. Each of these methods is described in the following sections.
In this way you can add as many documents and subdocuments as you like. Each time you select a (sub)document, the fields defined for this document type are displayed, and you can enter values for these fields: Note: There is no way to assign images to the documents manually.
Adding Data by Software Basics Usually, the data will reside somewhere in your system and will be imported into DOKuStar Validation by software. The following example first loads the project that we created above, and then fills the data with two documents: Private Sub Form_Load() Dim MyApp As New DOKuStarValidation.Application '* declare validation part of DOKuStarValidation '* make sure no project is open If Not MyApp.Project Is Nothing Then MyApp.Project.
The focus is on the first Letter document, and the field assigned to this hierarchy (Sender) is displayed.
Let us look at the code in detail: We now added a subroutine FillData that gets the data object of the DataSet as input. One document is then added: '* add a document Set doc = MyData.Documents.Add("Letter") doc.Fields("Sender").Value = "Océ Document Technologies" Set subdoc = doc.Documents.Add("CoveringLetter") Set subdoc = doc.Documents.Add("Invoice") subdoc.Fields("TotalAmount").Value = "100.00" The data object has a Documents collection with an Add method, through which you add documents.
The code for adding the second document is more or less the same as for the first one, so we skip explanations here. Up to now, we added two documents, but still things are missing: The image window and the snippet window are still empty, and we didn’t care about the table field yet. Let us now fill these gaps. Adding Data Sources Currently, data sources for documents are simply images. The term data source was chosen for future extensions (edocs etc.).
When the code is run again, you will get the following: The images are displayed as sub-nodes of the subdocuments. When you click on the subdocument node, always the first image will be displayed. Note that the Letter document itself has no images assigned to it, as we didn’t link any images to this document! It is up to you: If you also want the list of image nodes linked to the Letter node, add them to DataSource collection of the Letter node.
Dim Dim Dim Dim Dim doc As Document subdoc As Document imgDataSource As ImageDataSource fld As Field srcInfo As ImageSourceInfo '* '*** add a document '* Set doc = MyData.Documents.Add("Letter") doc.Fields("Sender").Value = "Océ Document Technologies" Set subdoc = doc.Documents.Add("CoveringLetter") '* add a datasource (image) to the subdoc "CoveringLetter" Set imgDataSource = MyData.DataSources.Add("dataset::ImageDataSource") imgDataSource.FileName = App.Path & "\Source_1.tif" subdoc.DataSources.
Table data We now fill the table field in our example. To keep the code short, we only add two rows: Private Dim Dim Dim Dim Dim Dim Dim Dim ' Sub FillData(dat As DOKuStarValidation.Data) doc As Document subdoc As Document imgDataSource As ImageDataSource fld As Field srcInfo As ImageSourceInfo tableFld As TableField row As TableRow cell As Field '* '*** add a document '* Set doc = MyData.Documents.Add("Letter") doc.Fields("Sender").Value = "Océ Document Technologies" Set subdoc = doc.Documents.
'* add two datasources (images) to the subdoc "Invoice" Set imgDataSource = MyData.DataSources.Add("dataset::ImageDataSource") imgDataSource.FileName = App.Path & "\Source_2.tif" subdoc.DataSources.Add imgDataSource '* add a row Set tableFld = subdoc.Fields("Details") Set row = tableFld.Rows.Add("Row1") '* add sourceinfo to a cell of the row Set cell = row("Quantity") cell.Value = "6" Set srcInfo = cell.CreateSourceInfo("dataset::ImageSourceInfo") srcInfo.DataSource = imgDataSource srcInfo.Zone.
cell.Value = "6" Set srcInfo = cell.CreateSourceInfo("dataset::ImageSourceInfo") srcInfo.DataSource = imgDataSource srcInfo.Zone.SetValue 1220, 1640, 100, 20 This makes it possible that different cells of the table reside on different pages of the document. The TableField object itself will not be assigned a Value or a SourceInfo.
Dim alt As Alternative '... Set fld = subdoc.Fields("TotalAmount") fld.Value = "547.47" '... '* add a sourceinfo Set srcInfo = fld.CreateSourceInfo("dataset::ImageSourceInfo") srcInfo.DataSource = imgDataSource srcInfo.Zone.SetValue 1650, 2020, 100, 20 '* add alternative Set alt = fld.Alternatives.Add("dataset::TextFieldAlternative", "TotalAmount_1") alt.Value = "471,96" Set srcInfo = alt.CreateSourceInfo("dataset::ImageSourceInfo") srcInfo.DataSource = imgDataSource srcInfo.Zone.
Scripting Introduction Scripting is the process where you add additional pieces of code to meet project-specific requirements. Scripting routines are preferably written in the built-in VBA studio, but could also be placed in the external Development Studio, if you use the COM interface. Scripting routines always come together with events: The routine shall be executed, when a certain event took place. For example: The validation operator entered something to a field.
Here is the source code for the example: Dim WithEvents Amount As FieldType Private Sub Application_OnProjectLoaded(ByVal App As Application) Set Amount = App.Project.DataSet.Schema.DocumentTypes("Invoice").FieldTypes("Amount") End Sub Private Function Amount_OnFieldChanging(ByVal Field As Field, ByVal SubField as Field, ByVal VerifyEventArgs As VerifyEventArgs) As Boolean Amount_OnFieldChanging = True 'Preset return value If Val(Field.Value) > 1000 Then If MsgBox("You entered a value > 1000.
Private Sub Application_OnProjectLoaded(ByVal App As Application) Set Amount = App.Project.DataSet.Schema.DocumentTypes("Invoice").FieldTypes("Amount") End Sub This subroutine will be called when the project is loaded. The only thing that is done here is that you assign the variable Amount, which you defined above, to the right field type: set to the FieldType Amount on the DocumentType Invoice.
In the event handling routine, we must therefore determine if we got the correct field by asking for the field’s name (Field.Name) and for the name of the corresponding document (Field.Document.Name). If these are Amount and Invoice, we open the dialog box. Which way of defining the event you prefer, depends very much on the project: Suppose there are many different document types, all of them having an Amount field, and the same code should be executed if any of these fields change.
The VBA Studio Yet, I didn’t mention one important thing: Where does all the code go? In most development environments, you have some file handling functionality, like File...Open/Close menus or something similar to that. The VBA studio is different here: When you look around in the studio, you will not find anything like it. So: Where is the code stored? The answer is simple: It all goes into a file with the same name as the DOKuStar Validation project but an extension .vps.
Events Concept Certain objects can get events. You will probably use the events defined for the FieldType and the DocumentType object, but there are many more objects which have the ability to get events. For example, an event may be assigned to a single Field (instead of the FieldType), e.g. to the amount field on the first document. So you could add code that would be executed if the user changed the amount on the first document, but not, if he changed the amount on one of the following documents.
- In the drop down list to the right, select the event handling routine wanted. The function body will then be added to the code automatically: In the following chapters, events are described in detail, always in the ...ed format.
Events for the FieldType Object OnFieldActivated This event will be fired when a field gets activated, either by keyboard entry, mouse click or by the scripting code itself. Definition: Private Sub fld_OnFieldActivated(ByVal Field As Field, ByVal PreviousField As Field) The parameter Field is the field that gets activated, PreviousField is the field that gets deactivated. When you return False in the OnFieldActivating, always the next field will be activated automatically.
Sub-field Events Sub-fields (e.g. table cells) have their own activation and deactivation events: OnSubFieldActivating, OnSubFieldActivated, OnSubFieldDeactivating and OnSubFieldDeactivated. These events get the Field (e.g. table), the Subfield (the cell), and the next (or previous respectively) sub-field as parameters.
TableFields Tables require additional features, because they are fields that are made up of rows, columns, and cells. an example, imagine a table in your document that has (among others) three columns Quantity, SinglePrice and TotalPrice. Whenever the user corrects a cell in the Quantity or SinglePrice column, the corresponding total price is recalculated (by: Quantity times SinglePrice) and compared against the value in the TotalPrice column.
Set t = Field This allows you to use methods and properties that only exist for TableFields. One of these methods is the Row method, that delivers the row in which the cell is in. The cell is passed as a parameter to this method. What we get is an object of type TableRow: Set row = t.row(SubField) Within this row, we can access the cells by indexing the row with the column name.
Event Order Field events occur in the following order: OnFieldActivating OnFieldActivated OnFieldChanging OnFieldChanged OnFieldDeactivating (old field) OnFieldActivating (next field) OnFieldDeactivated (old field) OnFieldActivated (next field) If any of the ...ing events is aborted, the events following this one will not be fired. Instead, you will get an ...ingCanceled event for this specific event.
For table fields, the event queue is as follows: OnFieldActivating (when the user steps into the table) OnFieldActivated OnSubFieldActivating (for the first cell) OnSubFieldActivated OnFieldChanging OnFieldChanged OnSubFieldDeactivating (for the first cell) OnSubFieldActivating (for the second cell) OnSubFieldDeactivated (for the first cell) OnSubFieldActivated (for the second cell) OnFieldChanging OnFieldChan
Events for the DocumentType Object OnField Events For the DocumentType object, the same OnField... events are available as for the FieldType object. These events will be fired for any field on the document. Definition (example OnFieldChanged): Private Sub doc_OnFieldChanged(ByVal Field As Field, ByVal SubField As Field) This is a convenient way of handling all fields of a certain document type together. Example: Suppose a document type TaxForm exists with several of amount fields.
OnDocumentActivated This event occurs whenever a new document is selected. This may happen explicitly (e.g. when the user selects a different document in the tree view) or implicitly (e.g. the user moves from field to a field and the document changes). Definition: Private Sub doc_OnDocumentActivated(ByVal Document As Document, ByVal PreviousDocument As Document) The current document and the previous document come as parameters.
OnDocumentCreated This event will be fired when a new document is created. This may happen explicitly (e.g. when the user splits a document in the tree view) or by scripting code. Definition: Private Sub doc_OnDocumentCreated(ByVal Document As Document) OnDocumentDataSourceChanged These will be called when one of the data sources of the document (i.e. one of the images) is changing.
OnDocumentDescriptorLost, OnDocumentDescriptorGot These events all occur when a document’s descriptor changes. The event might be caused by user action (the user changed the document type) or by a script itself. Changing the descriptor is a two-step process: A document looses his descriptor and then gets a new one. For each step, there is a pair of events.
Controller Events This object gets events when the active object changes, i.e. a field or document gets activated or deactivated. So here is another potential place to enter the (de)activation code. This is especially useful for routines that are common to all documents or all fields. OnDocumentActivated Will be fired for any document that gets activated.
OnDocumentDeleted Will be fired for any document that gets deleted. Definition: Private Sub ctrl_OnDocumentDeleted(ByVal Controller As Controller, ByVal Document As Document) Parameter Document is the document that gets deleted. OnDocumentCreated Will be fired for any document that is created. Definition: Private Sub ctrl_OnDocumentCreated(ByVal Controller As Controller, ByVal Document As Document) Parameter Document is the document that is created.
OnFieldChanged Will be fired for any field that gets changed. Definition: Private Sub ctrl_OnFieldChanged(ByVal Controller As Controller, ByVal Field As Field, ByVal SubField As Field) The parameter Field is the field itself. SubField may point to a subfield of the Field; OnCursorChanged Will be fired when a cursor changes. See below for a description of cursors.
Data Objects Dataset The Dataset is the topmost object in DOKuStar Validation concerning the data, and can be accessed from the Application object via: Application.Project.Dataset Every sub-object of the Dataset object has a property called Dataset, which delivers a pointer to its parent Dataset object. Example: Field.Dataset Furthermore, there are often properties that point to the parent(s) of an object.
Schema The Schema object describes the batch structure, i.e. the Document Types and Field Types. The Schema and belonging descendents will be used when defining events, e.g. if you want a ...Changed event for FieldType TotalAmount on DocumentType Invoice, if you want an event for every text field, etc. You will hardly use them within the event handling code.
DocumentType The DocumentType object describes one single document type and belongs to the Schema part of the Dataset. On the Data side, the Document object is an instance of the DocumentType object. Properties and methods of the DocumentType object (excerpt): Property/Method Returns Description FieldTypes FieldTypes Returns the collection of FieldTypes defined for this DocumentType Name String Name of the DocumentType. FieldTypes See the description for DocumentTypes.
Data The Data object is situated below the Dataset object, parallel to the Schema object. While the Schema holds the document definition, the Data object holds the data itself. The Data object provides access to various objects like Document, Field etc.. These objects have some common properties and methods; these are: Property/Method Returns Description Activate Boolean Activates the object; the object gets the focus. returns False if the object cannot be activated. See note below.
Documents Holds the collection of documents in this batch. An individual document can be accessed using the At method, which takes a Document as parameter.
Document Holds information about one document, especially the fields and the images. Furthermore, there is an Activate method which lets the document get activated. Properties and methods of the Document object (excerpt): Property/Method Returns Description Activate Boolean Activates the document. Returns True if successful. Activated Boolean Returns True if the document is currently activated. DataSources DocumentDataSources Returns the list of DataSource objects for this document.
Fields Holds a collection of Field objects. Individual Fields can be accessed either by name or object: Fields(MyField) Fields.At(MyField) Fields(„OrderDate“) Fields.
Field Properties and methods of the Field object (excerpt): Property/Method Returns Description Activate Boolean Activates the field. Returns True if successful. Activated Boolean Returns True if the field is currently activated. ActivateSubField Boolean Activates a sub-field. Returns True if successful. Can be used to jump to a specific cell of a table field. Parameter: SubField As Field ActiveSubField Field Returns the currently active subfield (i.e. table cell) of a field.
TableField A TableField is a special Field object. Being derived from Field, all Field’s properties and methods can be used. A TableField also has some additional properties and methods: Properties and methods of the TableField object (excerpt): Property/Method Returns Description Row TableRow Returns the row object for a given table cell. Parameter: Cell As Field Rows TableRows Returns a TableRows object, which is the collection of the tables‘ rows.
SourceInfo, ImageSourceInfo SourceInfo is the base class of ImageSourceInfo. Properties and methods of the ImageSourceInfo object (excerpt): Property/Method Returns Description DataSource ImageDataSource Holds the ImageDataSource object, which includes the images filename. Zone Zone Describes the box around the field. DataSource, ImageDataSource DataSource is the base class of ImageDataSource.
UserData UserData is an object that is linked to each field and document object. It serves as a container for additional data that you want to attach to the field or document. This data is organized as key/value pairs. You can attach as many of these key/value pairs to the document as you like. Example: Whenever the user changes the contents of a field, the original value shall be saved. When the field is activated again later on, the old contents shall be displayed in the status window.
VerifyEventArgs VerifyEventArgs is an object that is used with some events like OnFieldChanging. When such an event occurs, a VerifyEventArgs object is one of the parameters of the event handling function. VerifyEventArgs has two properties: Error, which is currently unused, and PreviousValue, which contains the old value before the user typed something in.
Controller The Controller object is the third sub-object of the Dataset, with the purpose of controlling the behavior of the application. Using the controller object enables to - activate and deactivate documents and fields, - administer the cursor. The Cursor object is described below in a separate chapter. With the controller object, a second way of activating fields or documents (the first one is the Activate method on the field and document object) is provided.
Cursors and Filters These topics are covered together, because there are some dependencies between them. Cursors control which fields and/or documents will get activated in the DOKuStar Validation’s user interface. They do not denote the shape of the cursor. Cursors are mainly defined by a set of filters. There are three types of filters defined in DOKuStar Validation: Field state filters, field confidence filters and document type filters.
The alternative is to create a new cursor and add filters, which may be the predefined two filters or newly created ones, as in the second example: Option Explicit Private Dim Dim Dim Dim Sub Application_OnProjectLoaded(ByVal App As Application) crs As Cursor fieldFilter As FieldStateFilter docFilter As DocumentTypeFilter docType As DocumentType '* add a new cursor and activate it Set crs = App.Project.DataSet.Controller.Cursors.Add("dataset::DefaultCursor", "MyCursor") App.Project.DataSet.Controller.
Properties and methods of the Cursor object (excerpt): Property/Method Returns Description Documents Documents Returns the list of documents with respect to the currently selected filters. Fields Fields Returns the list of fields with respect to the currently selected filters. Filters CursorFilters Returns the list of CursorFilters appended to this cursor. FirstDocument Document Returns the first document from the Documents list.
For the filter objects, there is a base class called CursorFilter. This class has few methods and properties, which you hardly will use. Derived from this base class there are the three classes DocumentTypeFilter, FieldStateFilter and FieldConfidenceFilter, where you define which document types and field states respectively are switched on and off. For the FieldConfidenceFilter, you can set a threshold value that ranges from 0 to 100.
Add-Ins Introduction Validation allows to modify its behavior using VBA. Because of some limitations of this method, Validation provides, starting with version 3.2, another way for interaction: add-ins . An add-in for Validation is an ActiveX Control. An add-in allows to add new menu entries or create and use one custom user control and one custom toolbar. In addition it is possible to easily handle the existing image control or to replace the existing edit and fields controls with your own controls.
Registry Key for Validation Add-Ins To be able to use a newly created add-in you must first add some information into the registry. It is useful to do this as a first step, because afterwards you are already able to test the add-in while you write the program code. Therefore Validation will use the following registry path (for version 3.2; for later versions replace this string by the actual version): HKEY_LOCAL_MACHINE\SOFTWARE\ODT-OCE\DOKuStarValidation\3.
In the following section we will create a library ValiTour.dll with an add-in that is represented by the class MyValidation. Therefore the program id, and thus the sub-key name for this example add-in is ValiTour.MyValidation: You will also find the default add-in ODT_F4.Module here. Important Note: If you work with your own add-ins, save the add-ins and export the corresponding registry entries, before installing a new release of DOKuStar Validation.
Creating an Add-In An add-in for DOKuStar Validation is always an ActiveX Control. You can write such an ActiveX Control in any programming language. In our example we use Visual Basic. In Visual Basic use the New Project command of the File menu and choose ActiveX Control from the appearing New Project dialog box: Now choose References from the Project menu.
for this class. It is called when the add-in has been initialized by Validation. Now type in the following code for the class MyValidation and generate ValiTour.dll.
Creating a Custom User Control In the previous section is described, how to create an add-in for Validation. In this section a new custom user control is added to Validation. The appropriate service is called UserCtrlBarData service. It is only possible to add one and only one custom user control. We will implement the custom user control for Validation using an add-in: As first step we have to add another reference. Use the command References of the Project menu.
Modify the code of our example in the following way and generate ValiTour.dll: There is also a special custom user control interface IUserCtrl. You must implement the function of the interface, otherwise the custom user control will not work properly. When you now start dsval.exe you will see that our custom user control appears on the Validation user interface. The View menu now allows activating or deactivating the custom user control.
DOKuStar Validation Programming Manual Page • 74
Creating a Custom Toolbar It is also possible to create one and only one custom toolbar for DOKuStar Validation. The appropriate service is called UserToolbarData service. First add a new user control to the project and name it Toolbar: Afterwards define the elements of the toolbar. For our example we add a toolbar and an image list to the form. To be able to add a ToolBar control, you have to add it to the ToolBox first.
As you can see, the toolbar is activated in the same way as the user control. The only difference is the type of service which has to be defined. There is also a special custom toolbar interface IUserToolbar. You must implement all three functions of the interface, otherwise the toolbar will not work properly. The first one sets the caption of the toolbar. It can be seen when the toolbar is dragged outside the toolbar area and changes into a window.
DOKuStar Validation Programming Manual Page • 77
Creating Menu Entries for Validation The programming interface allows to change the menu entries of DOKuStar Validation. The appropriate service is called Workspace service. New menu entries can be added, existing menu entries can be replaced or deleted. Now we will modify the menu using our add-in: First of all we have to define the workspace by the line Dim WithEvents workspaceSink As DOKuStarValidationServices.WorkspaceService. Then we have to get the specific service for processing workspaces.
After this code has been entered, generate ValiTour.dll and start dsval.exe.
The New command has been replaced and shows a submenu with two entries. Following the Export Data command the new command Import Extraction Result… appears. The only thing you have to do now is implementing what should happen if the new menus are used. For this purpose the Workspace service has two functions: workspaceSink_OnCommand and workspaceSink_OnCommandUpdate. Let us first look at workspaceSink_OnCommandUpdate. In our example we replace the existing New command with our own one.
The second function of the Workspace service, workspaceSink_OnCommand, is needed to specify the actions that should take place when the menu command is used. Here you must again use EventArgs.
If you enter the code shown above, generate ValiTour.dll, start dsval.exe, and open the File menu, the new menu items will be shown.
Workspaces In the previous section we used the Workspace service of Validation. In this section it is explained what a workspace is and how it is used. The workspace of Validation comprises the size and location of the various elements of the user interface of Validation within the main window. For example, if you drag custom user control of our example from the bottom of the main window to the top, you are changing the workspace of Validation. The same is true, if you change the order of the toolbars.
What happens? We have loaded the workspace default.vws at startup of Validation. In this workspace our custom user control is no longer at the bottom of the Validation window. Now enlarge our control until the Restore button appears and close Validation. If you now restart dsval.
Validation now comes up with the last changes you made in the workspace. Play a little around to get a feeling. You could remove the call to storeDefault and check that changes of workspace will no longer take effect. To write it to a file is probably not the best method to save a workspace. Therefore it is also possible to store the workspace information in the registry. The corresponding commands are workspaceSink.LoadWorkspaceFromRegistry and workspaceSink.SaveWorkspaceToRegistry.
Then we have to modify the functions loadDefault() and storeDefault(). In loadDefault() we first check whether the registry key already exists. If not we load the workspace from file, otherwise we fetch it from the registry. In storeDefault() we store the workspace to the registry and into a file. So, when dsval.exe is started for the first time, the workspace will be loaded from file. When Validation is closed the workspace will be written to the registry as well.
Handling Keyboard Strokes Keyboard strokes can also be handled by an add-in for DOKuStar Validation. The appropriate service is called Keyboard service. First you must provide the keyboard service of Validation. The keyboard service has two functions OnChar() and OnKeyDown(). In OnChar() you get the final code from the keyboard. That means if you press Shift-A, you get the final key code in OnChar(), in this case 65. In OnKeyDown() you get the code for Shift and a.
Now start now Validation with dsval ValiTour.vpj. The Validation window will look as follows: Press the F4 key and the message box will appear: Now try to enter numbers for the fields. Numbers will be suppressed but all other characters will appear normally.
Replacing Existing Controls In a previous section we created a custom user control. As was stated there, you can create only a single new user control, but you can replace existing controls, namely edit control and the fields control. In our example we will replace the edit control. The appropriate service is called UserEditData service. Let us replace the current edit control and use a new one for the text fields. First of all we create a new user control and name it Edit.
Now start Validation with the command dsval ValiTour.vpj. The Validation will look like this: The replaced edit control can be easily recognized by its changed color. If you move the cursor to the field Table, the color will disappear because this field is of the field type TableField and our new edit control was attached only to text fields.
Managing the Image Control The behaviour of the image control, like scrolling and zooming, can also be managed by an add-in. The appropriate service is called SourceCtrl service. Like the other services it must first be provided which is done by the lines Dim sourceCtrlSink As DOKuStarValidationServices.SourceCtrlService and Set sourceCtrlSink = dsValApp.Services("SourceCtrl"): Let us now implement a special behaviour of the image control.
Now start dsval ValiTour.vpj and try the key combinations to see the effects. Predefined Add-Ins There are two add-in modules which will be provided by DOKuStar Validation. ODT_F4.Module This default add-in is ready for use. It changes the layout of the DOKuStar Validation user interface from "normal" view to "table" view by using the Table Mode command of the View menu. DOKuStarValidation.Spy This add-in starts an event spy window. In the window all events fired by DOKuStar Validation will be listed.
Special Issues Events Caused by the File Menu One topic, that has not been discussed yet, is: When will the integration code be called? How does it interact with the Validation user interface? In the Validation user interface, there are some menu items that deal with projects and data: Standard actions take place when the validation operator uses the following commands of the File menu: New: Creates a new Validation project.
All these commands correspond to certain events: New => Application event OnProjectCreating, OnProjectCreated Open => Application event OnProjectLoading, OnProjectLoaded Close => Application event OnProjectClosed Save => Project event OnSaving, OnSaved ImportData => Data event OnPreImporting, OnPreImported, OnImported, OnPostImported ExportData => Data event OnPreExporting, OnPreExported, OnExported, OnPostExported It is assumed that the code that fills the Data object is linked to the OnPreImp
Information Bar The information bar is one of the windows of the Validation’s user interface; when the program starts, it is located above the field source bar (which displays the field’s snippet), but it can be moved around like any another window. This information bar can be filled by software, in order to display messages to the validation operator. To do so, there is a class StatusTextTransporter.
Validation Command Line Parameters Some of Validation’s command line parameters have already been described. You get the full list when, when you open a DOS box, go to the bin directory of the DOKuStar Validation installation and enter dsval -? Most command line options have a short and a long format, for example, dsval –a is equivalent to dsval –admin. Option Description --admin Start Validation in administrator mode --vba=FILE Loads a given VBA project from FILE.
Serialization of the Data The Data object can be exported into/imported from a file. To achieve this, there are special Importer and Exporter objects. Example: Sub ImportData(App As Application, filename As String) Dim ie As Importer Set ie = App.CreateObject("dataset::DataImporter") ie.Import filename, App.Project.dataset Set ie = Nothing End Sub Sub ExportData(App As Application, filename As String) Dim de As Exporter Set de = App.CreateObject("dataset::DataExporter") de.ExportData filename, App.Project.
Exchanging the Fields View In the Validation’s Fields View all fields of the current document are displayed together with their values. The fields are displayed one below the other, the active field is always highlighted. The appearance of this window can be exchanged individually for each document type. This is done by defining a HTML template for each document type. To do so, switch to the directory where your project file resides, and add a subdirectory named templates.
In this mode, you could also close the editing window. - Display Mode: In this mode, editing is still done in the editing window.
Note 1: You can also mix the modes: Use the editing mode for some fields, and the display mode for others Note 2: Tables can only be edited in the editing window, not in the HTML view. The HTML file itself can be created with any HTML editor (FrontPage etc.). To link it to the document model, you must use an attribute named id in your tags, which has the field name as value.
Character correction mode For editing single characters, you can use the character correction mode feature. This feature is realized by an additional ActiveX Control named ValRejectEdit, using the UserEditData service and will replace the default EditControl. The following example demonstrates the integration of the character correction mode feature and replaces the default Edit Window of a (user controlled) Validation user interface by the ValRejectEdit Control.
Step 3 Now we are ready for integrating the following code lines When the project is loaded, first we call InitRejectEditCtrl to connect all field classes of the schema to the RejectEditControl, with the exception of TableFields. TableFields are displayed in the DOKuStar Validation GUI by the TableEdit Control. Therefore we prevent the TableField class from registering by the RejectEditControl. So we are able for editing characters in TableFields by the TableEdit Control.
Remarks: You will find the above code lines, explaining the character correction mode, as a complete script (EZEC.vps) in your DOKuStar Validation installation path in the folder .\Examples\RejectEditControl So you can copy and implement the sample code for your own applications.
Properties and methods of the ValRejectEdit control: Property/Method Value Default Description AllowLeaveRejectMode True or False True Enable the editing of all characters, not only rejected ones. AllowRemoveDetail True or False True Enable the deleting of a rejected character AllToUppercase True or False False All entered characters will appear in upper case.
In the snippet view window the image of the index field is displayed, where the rejected character is highlighted; in the edit view you see the Reject Character ready for processing. • • FixedMode = True ShowDetailZone = True In the snippet view window only the image of the rejected character is displayed. This mode will be usefull to enlarge the image of the Reject Character to see further details.
How Do I… Set the Focus to the First Field You might want to set the focus in the Validation GUI to the first field after importing the data. This is done using the field’s Activate method. The first field should be identified with respect to the current filter settings, so we use the cursor object. The following piece of code sets the focus to the first field right after the Data object has been filled: Option Explicit Dim WithEvents Data As DOKuStarDataset.
Not Restore Old Contents When a scripting routine returns False in the OnFieldChanging event, the original contents of the field (before the user changed it) is restored. Sometimes however it might be better to keep what the user typed in, but still stay in the field and display an error message. This might be suitable for larger texts, where the user just made a spelling mistake. It is better then to let him correct what he typed than to let him enter it completely once again.
Display Multi-Line Status Texts Sometimes it might be necessary to display more than one line of text in the Information Bar. Using the StatusTextTransporter’s HTMLText property, this is no problem, because you will format everything yourself using the appropriate HTML tags. When you are not familiar with HTML and prefer the StatusTextTransporter’s Text property, you can still display more than one line of text.
Check All Fields Before Exporting When the user calls Export Data… from the menu, you might want to check if there all still erroneous fields. You place such a check in the Data objects OnPreExporting event. In the following example, all fields are checked if they have the state Empty or Error. If so, exporting is aborted and the first field of this kind is activated.
Check if the Last Field is reached When the user leaves the last field of the last document in the batch, you could perform some action like displaying a message box etc. The check for the last field should be done with respect to the current filter settings. If the user choose only to jump to empty fields, the last field is another one as if he jumped to all fields. The Cursor object provides a method LastField, so this is the easiest way to check for the last field.
Merge Table Rows The following example merges two table rows into one. The corresponding columns will be connected by adding the second cell’s value to the first one (strings put together separated by comma). The zone of the new cell will be the surrounding rectangle of the individual zones. It is assumed that the table field has three columns named “Description”, “SinglePrice” and “TotalPrice”. Whenever there is a table row that has only the “Description” filled, it shall be merged with the preceeding one.
Private Dim Dim Dim Sub mergeZones(firstFld As Field, secondFld As Field) firstSrcInfo As ImageSourceInfo secondSrcInfo As ImageSourceInfo fr, fb, sr, sb As Long Set firstSrcInfo = firstFld.SourceInfo Set secondSrcInfo = secondFld.SourceInfo fr = firstSrcInfo.Zone.X + firstSrcInfo.Zone.Width fb = firstSrcInfo.Zone.Y + firstSrcInfo.Zone.Height fr = secondSrcInfo.Zone.X + secondSrcInfo.Zone.Width fr = secondSrcInfo.Zone.Y + secondSrcInfo.Zone.Height If firstSrcInfo.Zone.X > secondSrcInfo.Zone.
Changing the Color of Documents Sometimes it may be necessary to inform the validation operator, which documents are always processed or which documents still contain errors after they have been processed by the operator. This can be done by changing the color of the document in the Tree View, using the ColorService. In the following example we use the OnDocumentDeactivated event as indicator that the validation operator changed to another document.
Private Dim Dim Dim Dim Sub colorDoc(doc As Document, bnOK As Boolean) lngRed As Long lngGreen As Long lngBlue As Long cs As ColorService Set cs = doc.Services("Color") lngRed = 0 lngGreen = 0 lngBlue = 0 ' display processed documents in different colors... If bnOK Then lngGreen = 255 cs.SetForeColor lngRed, lngGreen, lngBlue '...document without an empty field Else lngBlue = 255 cs.SetForeColor lngRed, lngGreen, lngBlue '...
