Working with Connectable Objects

Some of the objects in ABBYY FineReader Engine are so-called "connectable objects." This means that they implement the IConnectionPointContainer interface. Connectable objects support communication between ABBYY FineReader Engine and its clients.

Each of the ABBYY FineReader Engine connectable objects provides connection points of two types — one that uses a dispatch interface and one that uses the interface derived from IUnknown. The dispatch interface is designed for automatic use in Visual Basic and similar environments, while the vtbl-based interface is suitable for use in C++.

In the table below, you can find the list of connectable objects in ABBYY FineReader Engine and corresponding callback interfaces (dispinterfaces):

Object	Callback Interface (Dispinterface)
FRDocument	IFRDocumentEvents (DIFRDocumentEvents)
FRPages	IFRPagesEvents (DIFRPagesEvents)
FRPage	IFRPageEvents (DIFRPageEvents)
ImageDocument	IImageDocumentEvents (DIImageDocumentEvents)

Visual Components

Object	Callback Interface (Dispinterface)
ImageViewer	IImageViewerEvents (DIImageViewerEvents)
ZoomViewer	IZoomViewerEvents (DIZoomViewerEvents)
DocumentViewer	IDocumentViewerEvents (DIDocumentViewerEvents)
TextEditor	ITextEditorEvents (DITextEditorEvents)
TextValidator	ITextValidatorEvents (DITextValidatorEvents)
ComponentSynchronizer	IComponentSynchronizerEvents (DIComponentSynchronizerEvents)
Commands	ICommandEvents (DICommandEvents)

ABBYY FineReader Engine client application that wants to receive notifications of certain events in ABBYY FineReader Engine should implement interfaces of a specific type and "advise" the objects implementing these interfaces to the corresponding connectable objects.

See details for your development tool below.

Visual Basic .NET

Simply declare the connectable object WithEvents and implement the methods of the corresponding callback interface. You will also need to explicitly specify the event handler associated with the event.

For the FRDocument object, the procedure will be the following:

Declare the FRDocument object WithEvents:

Private WithEvents document As FREngine.FRDocument

Implement the necessary methods of the DIFRDocumentEvents dispinterface in the Sub similar to the following.

If you want to start and stop event handling at any time during program execution (using AddHandler and RemoveHandler statements):

Private Sub document_RecognitionOnProgress(ByVal sender As FREngine.FRDocument, _
                                           ByVal Percentage As Integer, _
                                           ByRef cancel As Boolean)
...
End Sub

or simply specify that this procedure handles a particular event (use the Handles keyword when defining):

Private Sub document_RecognitionOnProgress(ByVal sender As FREngine.FRDocument, _
                                           ByVal Percentage As Integer, _
                                           ByRef cancel As Boolean) Handles document.OnProgress
...
End Sub

Connect the implemented event handler to the event source, use the FRDocument object for processing, then disconnect the handler:

document = Engine.CreateFRDocument
document.AddImageFile("D:\Demo.tif")
AddHandler document.OnProgress, AddressOf Me.document_RecognitionOnProgress
document.Process()
RemoveHandler document.OnProgress, AddressOf Me.document_RecognitionOnProgress
or simply use the FRDocument object for processing if you define the event handling methods with Handles keyword:
document = Engine.CreateFRDocument
document.AddImageFile("D:\Demo.tif")
document.Process()

C++

In C++, you need to implement the necessary interface, obtain a connection point, and "advise" object implementing the interface to the corresponding connectable objects. We will use the FRDocument object as an example.

Implement the IFRDocumentEvents interface. As it is derived from the IUnknown interface, the client object should also implement the IUnknown methods:

class CFRDocumentEventsListener : public IFRDocumentEvents {
public:
...
    // Provide IUnknown methods simple implementation. They may also be
    // implemented by inheritance from some standard class with COM support
    ULONG AddRef();
    ULONG Release();
    HRESULT QueryInterface(REFIID riid, void** ppvObject)
    {
        if( ppvObject == 0 )
            return E_INVALIDARG;
        if( riid == __uuidof(IFRDocumentEvents) ) {
            *ppvObject = static_cast<IFRDocumentEvents*>( this );
        } else if( riid == IID_IUnknown ) {
            *ppvObject = static_cast<IUnknown*>( this );
        } else {
            *ppvObject = 0;
            return E_NOINTERFACE;
        }
        AddRef();
        return S_OK;
    }
    // Provide IFRDocumentEvents methods implementation
 HRESULT STDMETHODCALLTYPE OnProgress(
  IFRDocument* sender, int percentage, VARIANT_BOOL* cancel );
 HRESULT STDMETHODCALLTYPE OnWarning(
  IFRDocument* sender, int index, BSTR tip, VARIANT_BOOL* cancel );
 HRESULT STDMETHODCALLTYPE OnPageProcessed(
  IFRDocument* sender, int index, PageProcessingStageEnum stage ) { return S_OK; }
};

Then the CFRDocumentEventsListener class can be used to receive notifications from the FRDocument object. Advise this object to the notifications source (error handling is omitted):

// Suppose that we have already received the FRDocument object
IFRDocument* document;
// Query for IConnectionPointContainer on the FRDocument object
IConnectionPointContainer* pContainer=0;
document->QueryInterface(IID_IConnectionPointContainer, (void**)&pContainer);
// Obtain a pointer to the IConnectionPoint interface on a connection point within the connectable object
IConnectionPoint* pPoint=0;
pContainer->FindConnectionPoint(__uuidof(IFRDocumentEvents),
                                &pPoint);
// Establish a connection between the CFRDocumentEventsListener class and the connection point
CFRDocumentEventsListener listener;
IUnknown* listenerUnknown=0;
listener.QueryInterface(IID_IUnknown, (void**)&listenerUnknown);
// Advise listener to the notifications source
DWORD cookie; // A variable to store the cookie returned from the IConnectionPoint::Advise method
pPoint->Advise(listenerUnknown, &cookie);
// Process the document
...
// After notification, the listener is no longer needed and should be unadvised
pPoint->Unadvise(cookie);

C#

Refer to documentation on COM for a more detailed description of connectable objects.

You can also refer to the EventsHandling sample provided for C#, C++ with the Native COM Support, raw C++, Visual Basic .NET.

17.09.2024 15:14:40

Your use of this site is conditioned on Your continued compliance with the Terms of Use.

Terms of Use

Disclaimer of Warranty

Limitation of Liability

Transmission and Submission of Information

Downloads

Use of Content

Trademarks

Links to Third-Party Sites

Foreign Legislation

Subscription Terms

Partner Subscription Terms

Working with Connectable Objects

Visual Basic .NET

C++

C#