Automation Interface Reference

The information below is intended for programmers who want to make their software AceText-aware. Once you understand the basic principles of using AceText's COM automation interface, use the reference below to learn exactly how to handle the events AceText will fire, and which functions you can call to control AceText.

AceTextEventIntf event interface

AceText's event interface has four events. Your application must provide event handlers or event sinks for all of them.

QuerySupportedVersion(out uint Version)
AceText will fire this event as soon as your application connects to AceText. Your application must set Version to 2. This is the version of the AceText Clip Variant Structure that your application supports (i.e. the one described in this help file). This makes sure future versions of AceText know how to communicate with your application.

ShutDownNotification()
This event is fired when the user attempts to shut down AceText, while your application is still connected to it. AceText cannot shut down while an application is still connected to it. Your application should call DisconnectWindow() for each window still connected, and then disconnect the COM automation link itself. If your application fails to do this, AceText cannot shut down, and will minimize to the tray instead.

QueryAceType(uint Wnd, out BSTR AceType)
Fired when the user presses the AceType hotkey while the top-level window with handle Wnd has keyboard focus. Set AceType to the word the text cursor points to, or to the selected text. Whatever you assign to AceType is used as the default abbreviation. If a clip with the exact abbreviation exists, it will be pasted instantly. Set AceType to an empty string if your application cannot provide a meaningful default.

AcePaste(uint Wnd, OleVariant Clip)
Fired when the user completes an AcePaste or AceType operation. Paste the clip stored in the variant into the active control of the top-level window with handle Wnd. If you fail to paste the clip, AcePaste will not work with your application.

AceTextIntf interface

AceText's automation interface provides many functions that you can call to provide tight integration between AceText and your software. However, for most purposes, you will only implement the four event handlers above, and only call the first two methods below. The remaining methods are for advanced integration. All JGsoft applications implement the basic AceText integration, but only EditPad Pro uses the advanced integration.

ConnectWindow(uint Wnd)
You must call ConnectWindow() for each top-level window (i.e. form) your application shows. Only then will AceText know that this window is AceText-aware, and call any of the events above for that window.

DisconnectWindow(uint Wnd)
Call DisconnectWindow() whenever you hide a window that you called ConnectWindow() for.

AceTextVersion: int
This function returns the latest version of the AceText Clip Variant Structure that the user's copy of AceText supports. Only versions 1 and 2 are defined at this time of writing. Thus your application can only support versions 1 and 2. AceTextVersion will always return a number equal to or greater than 1. This function is reserved for future use, enabling your application to check if the user's copy of AceText is up to date. When your application supports version 2, and AceTextVersion returns 1, you can either tell the user to upgrade his or her copy of AceText, or let your application fall back to version 1.

StartAcePaste(uint Wnd)
Activate AcePaste, as if the user had pressed the AcePaste hotkey. Use this function to add an AcePaste button or menu item to your application. Set Wnd to the handle of the top-level window that has input focus when the user selects the AcePaste. AceText will send the pasted clip to that window. Make sure to specify the top-level window, and not the active edit control.

StartAceType(uint Wnd)
Works just like StartAcePaste, but initiates AceType instead.

ShowAceText(int Flags)
Make AceText show itself. The value of Flags determines whether the AceText Editor, the AceText Tower, or both are shown. 1 shows only the editor, 2 shows only the tower, 3 shows both editor and tower. 5 shows the editor, leaving the tower visible if it was visible last time. 6 shows the tower, leaving the editor visible if it was visible last time. If Flags is 0, AceText will show whichever windows were visible last time. Usually, you should specify 0.

HideAceText()
Tell AceText to hide itself. AceText will only hide if it was made visible by your call to ShowAceText() in the first place.

OpenCollection(BSTR Filename): uint
Opens the AceText Collection. Filename must be a full path. Returns the CollectionID for the collection, or zero if the collection could not be opened. If the collection is already open, its tab is simply activated. The collection will not be re-read from disk.

NewCollection(BSTR Filename): uint
Creates a blank AceText Collection. Either set Filename to a full path to use a default file name, or leave Filename blank. If you specify a default, and auto save it on, the collection will be automatically saved at regular intervals. Otherwise, the collection will not be saved until the user choses a file name.

CloseCollection(uint CollectionID)
Closes the collection indicated by CollectionID. Set CollectionID to the value returned by OpenCollection or NewCollection. If autosave is off, and the collection was modified, the user will be asked to save it.

GetCollection(uint CollectionID): OleVariant
Returns an AceText Variant Structure holding the entire collection identified by CollectionID. Set CollectionID to the value returned by OpenCollection or NewCollection, or specify one of the standard collections. 0 retrieves the active collection, 1 retrieves the ClipHistory, 2 retrieves all collections, and 3 retrieves the recycle bin.

CheckCollectionModified(uint CollectionID): DATE
Returns and OLE date indicating the time the collection identified by CollectionID was last modified. Use this function to avoid needless calls to GetCollection().

AddClip(uint ParentFolderID, uint PrevClipID, OleVariant Clip): uint
Adds the AceText Variant Structure (a folder with or without contents, or a clip) to an AceText collection. ParentFolderID must either be a CollectionID, or the ID of a folder from a variant structure. PrevClipID must be either zero, or the ID of a clip or a folder inside ParentFolderID. Returns the ID of the newly added clip or folder. Note that AceText will ignore any IDs specified on the Clip variant. All the items in the variant will get a new ID.

DeleteClip(uint ClipID)
Deletes the clip or folder identified by ClipID. If it is a folder, all clips and folders help by it are deleted as well. You cannot delete entire collections this way. Deleted clips and folders are NOT added to the recycle bin.

ReplaceClip(uint ClipID, OleVariant Clip): uint
Efficient way of deleting a clip or folder, and then inserting another one at the same position. Like AddClip, it returns the newly assigned ID.

MoveClip(uint ClipID, uint ParentFolderID, uint PrevClipID)
Efficient way of deleting a clip or folder, and then re-inserting the same clip or folder at another position. Since the clip is moved, its ClipID remains the same. MoveClip can move clips inside a single collection, or between different collections.

CanModify(uint ClipID): uint
Returns one if the clip or folder identified by ClipID can be modified. Returns zero otherwise. "Modifying" means editing the clip or folder itself, or adding clips or folders to the folder. You can modify all clips and folders, except those on the All Collections and Recycle Bin tabs.

CanContainFolders(uint FolderID): uint
Returns one if the folder or collection indicated by FolderID can contain other folders. Returns zero otherwise. All collections and folders can contain other folders, except the ClipHistory. CanContainFolders() returns one for the All Collections and Recycle Bin tabs, even though you cannot add folders to them (because they can contain folders nonetheless).

GetActiveClip: uint
Returns the ClipID of the clip that is currently being displayed by AceText. Returns 0 if a folder is active, or if nothing is active.

GetActiveFolder: uint
Returns the FolderID of the folder that is currently selected in AceText. This means the user can readily edit the folder's label. Returns 0 if a clip is active, or if nothing is active.

SetActive(uint ItemID)
Activates the clip, folder or collection indicated by ItemID. If the item is inside a collection other than the active one, that collection is made active.

GetClip(uint ClipID): OleVariant
Returns the clip, folder or collection indicated by ClipID. In case of a folder or collection, all clips and folders inside it are also present in the returned variant structure.

New Functions in AceText 2.0 And Later

These functions are only available if AceTextVersion returns 2 or greater.

GetActiveCollection: BSTR
Returns the full path to the file where the active collection is saved. Returns an empty string when the active collection is unsaved, and when the Clipboard tab is active.

GetAllCollections: BSTR
Returns a list of all open collections, including special ones like the ClipHistory and All Collections. The list is delimited by line breaks. Each collection is indicated with a caption=id pair. The caption is what appears on the collection's tab in AceText. The ID is the value you can pass as the CollectionID parameter to GetCollection or SetActive.