Miraplacid Home Contact UsStoreDownloadsMiraplacid NewsMiraplacid ForumSearch at Miraplacid.com
Miraplacid Publisher (Image Printer Driver)Miraplacid Text Driver (Text Printer Driver)Miraplacid Data ViewerMiraplacid Form
Bookmark this pageMiraplacid PublisherMiraplacid Text DriverMiraplacid Data Viewer / Binary DOMMiraplacid Company

Miraplacid Text Driver : Extract Text from Documents

 

Miraplacid Text Driver 3.1: SDK Documentation

Content:


Miraplacid Text Driver Profremmer's Manual covers following topics:

How to create custom Output Style


Note: Before implementing your output format, try XML plug-in. It might be easier to get same results from XML output with XML/XSLT processing or some other way.
Note: Please use Windows (\r\n or 0x0D, 0x0A) End-Of-Line style in plug-in output.
Output Styles are actually plug-ins implemented as COM components.
Plug-in must implement interface IMTD_PLUGIN and must be listed in COM category CATID_MIRAPLACID_MTD_PLUGINS (see file include\catid.h)
To implement plug-in mtd_sdk_sample_plugin in Microsoft Visual Studio 6.0 we have followed these steps:
  • Create new ATL project mtd_sdk_sample_plugin (DLL with all default settings)
  • Insert new ATL object, Simple Object, name=MTD_SDK_Plugin, all default settings
  • Choose Unicode configuration (remove extra and non-Unicode ones)
  • Add "..\..\include" input directory to C++ and MIDL
  • Add to mtd_sdk_sample_plugin.idl
    import "imtd_plugin.idl";
    remove interface IMTD_SDK_Plugin replace in coclass line IMTD_SDK_Plugin with IMTD_PLUGIN;
  • In MTD_SDK_Plugin.h removes line with IMTD_SDK_Plugin - IdispatchImpl line from base classes list and IMTD_SDK_Plugin line from COM_MAP
  • Add to project file ..\..\imtd_plugin.idl
  • Unload project and load it back
  • In Class View unload right click on the class CMTD_SDK_Plugin and choose "Implement Interface". Check interface "IMTD_PLUGIN"
  • Add to MTD_SDK_Plugin.h include file
    #include "catids.h"
  • Add to class CMTD_SDK_Plugin Category Map
    BEGIN_CATEGORY_MAP(Cimtd_plugin_plain)
       IMPLEMENTED_CATEGORY(CATID_MIRAPLACID_MTD_PLUGINS)

    END_CATEGORY_MAP()
  • Add to class CComBSTR values for plugin name, config, config purpose and output value
  • Add FinalConstruct with plugin name and config purpose initialization
  • Replace "return E_NOTIMPL;" in methods with actual implementation - see MTD_SDK_Plugin.h for details
  • Try to build the project. It will make file imtd_plugin_i.c
  • Add to project file imtd_plugin_i.c, in project settings set "Precomiled headers" : "Not Using Precomiled Headers" for this file.
  • Build the project - it will register the plug-in
  • Start mtd_ui.exe and check the Output Formats drop-down. New plug-in "MTD SDK Plug-in" is listed there. Select it. Print to the Miraplacid Printer Driver and try to change the delimiter. Text in preview window will change accordingly.

How to manage Miraplacid Text Driver via COM interface


Technically, there are two ways how you can manage Miraplacid Text Driver via COM interface. Simple way is just create an instance of class MTD and work through interface IMTD. You can subscribe on events, call methods, get and set properties. There are two limitations. First, you have to start mtd_ui.exe prior to your software and close it after you close your software. Second, you cannot call method OpenJob() and shall be very careful with other properties or methods cause you can break the mtd_ui.exe and driver. Miraplacid neither guarantee that this approach will work nor provide any samples or documentation on it. The right way to work with Miraplacid Text Driver via COM interface is to implement your User Interface module and specify it under registry key
//HKEY_LOCAL_MACHINE/SOFTWARE/Miraplaclid/TextDriver/CurrentUI
(replace current value)
MTD SDK includes UI example on C++ (ATL) "MTD_UI_Quiet" and VB 6.0 "vb_ui" with sources. You can modify and use them as you need.
This module does not have to actually have any user interface. For example, sample MTD_UI_Quiet does not have it at all.

MTD_UI_Quiet sample


MTD_UI_Quiet is C++ ATL batch-mode UI with no user interaction. It saves printed document and when there is no other printed documents, it unloads.
All the MTD-specific code collected in UI_Quiet.cpp and UI_Quiet.h.
There is Event Sink (to work with IMTD Connection Points) with events OnStartJob, OnError, OnPageRendered and OnAllPagesRendered.
On start it creates object MTD and query interface IID_IMTD. Then it tries to Open Job. If OpenJob succeeded, it waits for event OnPageRendered. Otherwise, if there are no pending printed documents, it waits for event OnStartJob.
As soon as a page has been formatted (OnPageRendered event), UI_Quiet tries to save it (gets number of formatted pages then calls IMTD::SavePage for those that have not been saved yet).
When all the pages are saved (after event OnAllPagesRendered), UI tries to open the next print job. If there is no pending printed job, application exits.

VB_UI Sample


VB_UI sample functionality is very close to the MTD_UI.exe. It contains same controls, preview window and information window.
On start it creates object MTD and query interface IID_IMTD. Then it tries to Open Job. If OpenJob succeeded, it waits for event OnPageRendered. Otherwise, if there are no pending printed documents, it waits for event OnStartJob.
Every incoming event is indicated in the events window. As soon as page is formatted (event OnPageRendered), it gets available for preview in the preview window. It is possible to save current page or all pages and even update page content.

Appendix A: Interface IMTD


User Interface works with driver via interface IMTD. Interface contains methods and properties to manage the driver and events to notify User Interface about the changes in print job status.
 
Method Parameters Description
Start void This function call informs Miraplacid Text Driver engine that UI has been started.
OpenJob [out, retval] long * job_id UI shall call either Start or OpenJob immediately after start up. It tells driver that the UI has been properly started. Besides, UI shall call this method when previous print job has been handled and when UI is idle and event OnStartJob arrived. OpenJob returns print job id or "-1". If print job id is -1, UI shall turn to idle mode and wait for Fire_OnStartJob or unload. Otherwise UI shall handle the job.
SavePage [in] long page_number Saves specified page to output file. Page will be saved as it is stored in "pages". Codepage and End Of Line Style applied immediately before saving.
UpdatePage [in] long page_id, [in BSTR new_text Update specified page with new text. Changing properties "plugin" and "plugin_id" causes re-processing of the text. All the changes on all pages made by UpdatePage will be lost.
CancelJob void Cancels the job. If there are pending print jobs, OnStartJob event will be fired.
Property Type Description
plugin_id long (get, put) Select plug-in ("Output Style"). Causes text re-formatting.
plugin IMTD_PLUGIN * (get, put) Get or set plug-in. Causes text re-formatting.
plugin_names IBSTR_Collection * (get) Returns plug-in names list
document_name BSTR (get) Returns original name of the printed document
charset E_CHARSET (get, put) Character set, see mtd_core.idl
writemode E_WRITEMODE (get, put) Append or Overwrite mode, see mtd_core.idl
total_pages long (get) Returns total number of pages in the printed document or 0 if this number is not known. This value is not guaranteed to be correct.
job_status long (get) status of current job.
0x01 - job has been opened
0x02 - job has been completely printed
0x04 - job has been completely formatted (no more pages expected). OnAllPagesRendered fires at this point.
0x08 - job has been disposed
UNIX_EOL long (get, put) End Of Line style
0 means "Windows" EOL style (\r\n or 0x0D, 0x0A)
1 means "UNIX" EOL style (\n or 0x0A)
pages IBSTR_Collection * (get) returns collection of currently formatted pages. Event OnAllPagesRendered and (job_status & 0x04) guarantee, that all the pages has been formatted and no more pages expected.
filename BSTR (get, put) Output Filename. {{DATE}},{TIME}}, and {{IDENTITY}} will be replaced with current date, time and unique number respectively.
Event Type Description
OnStartJob void Fires when new print job arrives after unsuccessful IMTD::OpenJob call. Unsuccessful means there was no print job and method returned job_id=-1
OnError [in] long error_code, [in] BSTR message Fires when error occurred. Error code ranges:
0x100 - 0x1FF: Invalid Filename
0x200- 0x2FF: Cannot Create Output File
0x300- 0x3FF: Cannot Write to Output File
0x400- 0x4FF: Internal Error
OnPageRendered [in] long page_id Page has been formatted and could be retrieved or saved
OnAllPagesRendered void All pages have been formatted and could be retrieved or saved

Appendix B: Interface IMTD_PLUGIN


Miraplacid Text Driver plug-ins implement interface IMTD_PLUGIN. All the communications between the Driver and Plug-ins go through this interface.
 
Method Parameters Description
StartPage void Clean up the plug-in and get it ready for new page
Add ([in] long x0, [in] long y0, [in] long x1, [in] long y1, [in] BSTR text Add text block
Render [out, retval] BSTR *pVal Format the text and return the result
Property Type Description
plugin_name BSTR (get) Plug-in Name
config_purpose BSTR (get) If plug-in has no settings, leave it blank. Otherwise, specify text to be displayed below the "Output Style" drop-down in the MTD dialog.Plain Text Plug-in has configuration "Delimiter"
config BSTR (get, put) - configuration string. If config_purpose is not blank, user can type configuration string into textbox under the "Output Style" drop-down in the MTD dialog

Appendix C: Interface IBSTR_Collection


Miraplacid Text Driver use interface IBSTR_Collection exchange information with User Interface. IBSTR_Collection implements standard collection interface plus some additional methods. It is simple and convenient to work with this interface from both VB and C++. Unfortunately, "foreach" works in VB 6.0 only for objects collection while IBSTR_Collection is string collection, but "for" works properly.
 
Method Parameters Description
Item [in] VARIANT index, [out, retval] VARIANT* pItem Standard Collection "Item" method. There is an alternative method "GetItem" for C++ programmers.
Add [in] BSTR newVal Add String to the end of collection
Replace [in] long idx, [in] BSTR newVal Replace String
RemoveAll void Remove All Items from collection
GetItem [in] long idx, [out,retval] BSTR *item Returns string by index. Use Item from VB instead.
Property Type Description
Count long (get) Standard collection "Count" property. Returns number of collection items.
_NewEnum LPUNKNOWN (get) Standard collection "_NewEnum" property. Returns enumeration of collection items.

See also:

Copyright © 2001 - 2024 by Miraplacid.  Legal Notices