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.
You can download the AceText 4 Client Demos to get sample source code that you can use as the basis for your own applications.
EditPad Lite and EditPad Pro are real-world examples of applications that fully integrate with AceText. If you have AceText installed, the Clip Collection panel in EditPad shows the collection that is active in AceText. This allows you to directly work with your AceText collection within EditPad.
AceText’s installer automatically registers AceText’s automation interface with Windows. The uninstaller automatically unregisters it. You can also do this manually. If you installed AceText for all users, open a command prompt with administrator privileges. Then run AceText with the /regserver or /unregserver parameter to register or unregister it. If you installed AceText for your own user account only, open a command prompt under your own user account and run AceText with /regserverperuser or /unregserverperuser.
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\Just Great Software\AceText by default.
In Delphi, select Component|Import Component from the menu. Select “Import a Type Library” and click Next. Select “AceText API” version “4.0” from AceText.exe and click Next. Choose a palette page and a directory, make sure Generate Component Wrappers is ticked, and click Next. Install into a new or existing package as you prefer. A new component called TAceTextIntf appears on the component palette. This components implements the methods and events you can use to communicate with AceText.
Drop TAceTextIntf 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. Call the AceTextVersion method to ask which version of the API AceText supports. It may return 1, 2, or 4. Future versions of AceText may return a greater number. The number determines which TAceTextIntf methods you can call.
If AceTextVersion returns 4 or greater then call ClientVersion(4) to tell AceText that you support version 4 of the clip variant structure. Do not make this call if AceTextVersion returns 1 or 2.
To support AceText 1 or 2, double-click the OnQuerySupportedVersion event of the TAceTextIntf component in the Object Inspector. This event is only triggered if you don’t call ClientVersion before calling ConnectWindow. If you followed the above instructions then this can only be when AceTextVersion returned 1 or 2. Set the Version parameter in the event handler to the same value 1 or 2 to indicate you support version 1 or 2 of the clip variant structure.
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. You should also assign the other event handlers of the TAceTextIntf component to make your application fully AceText-aware.
After calling ClientVersion or ConnectWindow you the TAceTextIntf methods that take an OleVariant as a parameter or return one. You must always use the version of the variant structure that you indicated support for. If you followed the above instructions then AceText will do the same.
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”. After adding the reference, import the AceText namespace. Then you can easily access the AceTextIntf interface. Create a new instance of this interface to connect your application to AceText. This will cause Windows to start AceText if it is not yet running. Call AceTextIntf.AceTextVersion() to ask which version of the API AceText supports. It may return 1, 2, or 4. Future versions of AceText may return a greater number. The number determines which TAceTextIntf methods you can call.
If AceTextVersion returns 4 or greater then call ClientVersion(4) to tell AceText that you support version 4 of the clip variant structure. Do not make this call if AceTextVersion returns 1 or 2.
To support AceText 1 or 2 create an instance of the delegate IAceTextEventIntf_ShutdownNotificationEventHandler and add it to the ShutdownNotification event of the AceTextIntf instance. The event is triggered when you call ConnectWindow and you didn’t call ClientVersion. If you followed the above instructions then this can only be when AceTextVersion returned 1 or 2. Set the Version parameter in the event handler to the same value 1 or 2 to indicate you support version 1 or 2 of the clip variant structure.
Whenever your application displays a window, call AceTextIntfClass.ConnectWindow(). For a WinForms application, specify the Handle property cast to a uint as the parameter. For a WPF application, instantiate a new WindowInteropHelper for your WPF window. Cast its Handle property to a uint and pass it to ConnectWindow(). When hiding the window, call DisconnectWindow() passing the same handle cast to a uint. This ensures that AceText knows which windows belong to your application. Casting an IntPtr to a uint is safe if the IntPtr is a top-level window handle. Windows ensures window handles never exceed 32 bits.