Therefore Programming Interface 3.0

1

Start Microsoft Visual Studio and create a new class library project

2

Add a Reference to the Thereforeâ„¢ API

In the Solution Explorer right-click Reference and click on Add Reference.

In the .NET tab choose "The.API.Interop" and click OK.

If you cannot find "The.API.Interop" in your .NET you can also use "Therefore API 3.0 Type Library" in the COM tab, or open the Browse tab and select "The.API.Interop.dll" or "TheAPI.dll" in your Thereforeâ„¢ directory. Please see "Add Reference in Visual Studio" for details.

3

Add using/Imports statements for Therefore.API and System.Runtime.InteropServices

Open your AddIn class implementation file. In the beginning of the file add the following lines after other using or Imports statements.

Visual Basic .NET

Imports System.Runtime.InteropServices

Imports Therefore.API

4

Create and Insert a GUID

Open the GUID creation tool (Tools / Create GUID).

Select "4. Registry Format" and click the Copy button.

Paste the created GUID between the quotation marks of the GUID tag and delete the curly brackets {} around the generated GUID. Now your class looks like this:

Visual Basic .NET

<Guid("34B32BFD-C91D-44e6-B1C2-468635C1059F"), ComVisible(True)> 

Public Class MyAddInClass

    Implements ITheAddIn

End Class

5

Implement ITheAddIn

In the code file mark the position after Implements ITheAddin and press enter to create an empty interface implementation. If your VB .NET version does not support this feature just copy and paste the code below. Your implementation file should now look like this:

Visual Basic .NET

Imports System.Runtime.InteropServices

Imports Therefore.API

<Guid("34B32BFD-C91D-44e6-B1C2-468635C1059F"), ComVisible(True), ClassInterface(ClassInterfaceType.None)> _

Public Class MyAddInClass

    Implements ITheAddIn

    Public Sub GetHandledEvents(ByVal nClient As The.API.TheClientType, ByVal pEventSet As The.API.TheEventSet) Implements The.API.ITheAddIn.GetHandledEvents

         Throw New NotImplementedException()

    End Sub

    Public Function HandleEvent(ByVal pEvent As The.API.TheEvent) As Integer Implements The.API.ITheAddIn.HandleEvent

        Throw New NotImplementedException()

    End Function

End Class

6

Implement a Simple Test AddIn

Add a reference to System.Windows.Forms (in the Solution Explorer right-click References / Add Reference; in the .NET tab choose System.Windows.Forms and click OK) and make the following changes to your code:

Visual Basic .NET

Imports System.Runtime.InteropServices

Imports System.Windows.Forms

Imports Therefore.API

<Guid("34B32BFD-C91D-44e6-B1C2-468635C1059F"), ComVisible(True), ClassInterface(ClassInterfaceType.None)> _

Public Class MyAddInClass

    Implements ITheAddIn

    Public Sub GetHandledEvents(ByVal nClient As The.API.TheClientType, ByVal pEventSet As The.API.TheEventSet) Implements The.API.ITheAddIn.GetHandledEvents

        MessageBox.Show("MyAddInClass successfully registered.")

    End Sub

    Public Function HandleEvent(ByVal pEvent As The.API.TheEvent) As Integer Implements The.API.ITheAddIn.HandleEvent

        Throw New NotImplementedException()

    End Function

End Class

pEventSet.AddAll() will tell the Thereforeâ„¢ AddIn system that we want to receive all occurring events.

In HandleEvent we display a message box with a string representation of the incoming event. We return the default return code (0), thereby telling the AddIn system to continue as usual. Please check the various events for the event-specific meaning of different return codes.

7

Build your AddIn DLL

In Visual Studio click on the menu Build / Build Solution or Build / Rebuild Solution. Check the output window to make sure your DLL compiled successfully, if not debug your code and repeat this step.

8

Register the Assembly (RegAsm)

Open a Windows command prompt (click Start / Run - type "cmd" - click OK). Navigate to the directory containing your AddIn DLL. Type regasm <YourDLL>

(e.g. regasm myaddinlibrary.dll) The command prompt should say Types registered successfully.

   D:\TestProjects\MyAddInLibrary\MyAddInLibrary\bin\Debug>regasm myaddinlibrary.dll

   Microsoft (R) .NET Framework Assembly Registration Utility 2.0.50727.1433

   Copyright (C) Microsoft Corporation 1998-2004.  All rights reserved.

   Types registered successfully

9

Configure the AddIn in the Windows Registry

Open the Windows Registry Editor (Start / Run / regedit). Find or create the key HKEY_LOCAL_MACHINE/Software/Therefore/AddIns and/or HKEY_CURRENT_USER/Software/Therefore/AddIns and create the following subkeys: All, Capture, CategoryDialog, Navigator and Viewer.

10

Test your AddIn

Start Thereforeâ„¢ Navigator or Capture or Viewer and you should see a message box "MyAddInClass successfully registered.". Afterwards your application should run as usual.

This concludes your first test of the Thereforeâ„¢ AddIn system. Please read the remaining sections of this guide for more useful applications of the Thereforeâ„¢ AddIn system.