Automation Interface

The information below is intended for programmers who want to make their software AceText-aware.

In addition to adding support for AceText's clipboard format to your application, you should implement AceText's COM Automation to enable your application and AceText to communicate. Then, AceText can send AcePaste and AceType events directly to your application.

Download the AceText Client Demos to get sample source code that you can use as the basis for your own applications. One demo is written in C# using the .NET framework, and the other is written in Delphi using the Win32 API.

AceText automatically registers its automation interface with Windows. So if AceText has been run at least once on a computer, the automation interface is available. To automate AceText via COM, you need to import its type library. It is stored in AceText.exe, which is installed under C:\Program Files\JGsoft\AceText by default.

Below, you can find the basic instructions for making your application AceText-aware, once for Borland Delphi, and once for C# and the .NET framework. If you use another development tool, you need to perform the same tasks, but the actual methods may differ, depending on your development tool's support for COM automation.

Borland Delphi (Win32)

Select Project|Import Type Library from the menu. Import "AceText API", and install the unit into a package. A new component called TAceTextIntf appears on the component palette. This component implements the methods and events you can use to communicate with AceText. Drop this component on a form or data module. Call the component's Connect() method to connect to AceText. If AceText is not yet running, Windows will start it.

In the OnShow event handler of all forms in your application, call TAceTextIntf.ConnectWindow(). Specify the Handle property of the form as the parameter. In the OnHide event handler of all your forms, call TAceTextIntf.DisconnectWindow(). This ensures that AceText knows which windows belong to your application.

The TAceTextIntf component has four events. You must assign event handlers to all of them. The event handler for OnQuerySupportedVersion must set the Version parameter to 1. This makes sure future versions of AceText know which version of the clip variant structure your application supports, and makes your application forward compatible. In the event handler OnShutdownNotification, you must call DisconnectWindow() for each form that is still connected. Then you must call TAceTextIntf.Disconnect() to terminate the connection between your application and AceText.

The OnQueryAceType event is fired when the user presses the AceType hotkey. It gives your application a chance to set a default abbreviation. You should set it to the word that the text cursor is pointing at, if any.

OnAcePaste is fired when the user completes an AcePaste or AceType operation. The event sends your application the clip to be pasted as a variant structure. This way, the clip can be pasted without using the Windows clipboard, preserving the data it holds.

That is all it takes to make your application fully AceText-aware. The additional methods of the automation interface are intended for advanced integration with AceText. You can use them if you want.

C# (.NET framework)

In Visual Studio.NET, right-click on "References" in the Solution Explorer, and pick "Add Reference". Switch to the COM tab, and choose "AceText API". In Borland C#Builder, do the same from the Project Manager. After adding the reference, import the AceText namespace. Then you can easily access the AceTextIntfClass class. Create a new object from this class to connect your application to AceText.

Whenever your application displays a form, call AceTextIntfClass.ConnectWindow(). Specify the Handle property cast to a uint as the parameter. When hiding the form, call DisconnectWindow(). This ensures that AceText knows which windows belong to your application.

AceTextIntfClass has four events. You must assign event handlers to all of them. The event handler for QuerySupportedVersion must set the Version parameter to 1. This makes sure future versions of AceText know which version of the clip variant structure your application supports, and makes your application forward compatible. In the event handler ShutdownNotification, you must call DisconnectWindow() for each form that is still connected. Then you destroy all instances of AceTextIntfClass that you created, to terminate the COM connection.

The QueryAceType event is fired when the user presses the AceType hotkey. It gives your application a chance to set a default abbreviation. You should set it to the word that the text cursor is pointing at, if any.

AcePaste is fired when the user completes an AcePaste or AceType operation. The event sends your application the clip to be pasted as a variant structure. This way, the clip can be pasted without using the Windows clipboard, preserving the data it holds.

That is all it takes to make your application fully AceText-aware. The additional methods of the automation interface are intended for advanced integration with AceText. You can use them if you want.