Returns an URL pointing to the clip, folder or collection indicated by ClipID as would be generated by
Edit|Copy Link.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.
AceText’s event interface has four events. Your application must provide event handlers or event sinks for all of them.
QuerySupportedVersion(out uint Version)
If you do not call ClientVersion first then AceText fires this event when you call ConnectWindow. You must set the Version parameter to 1, 2, or 4 to indicate the version of the AceText Clip Variant Structure that your application supports. The version you request should not be greater than the version returned by AceTextVersion. If you request a greater version then AceText will actually use the version returned by AceTextVersion.
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 then 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. The clip may be a temporary clip that is not stored in any collection if AceText had to substitute any parameters in the clip. If your application needs to store the pasted clip it should store the Variant passed to AcePaste and not rely on the ID number in the Variant as that ID may not exist anywhere else.
CollectionChanged(unit CollectionID)
Fired when the user switches between collections in AceText or edits the active collection. Handle this event if you want your application to show a live copy of the collection that is active in AceText. Call GetCollection to actually retrieve collection.
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 for that window. Calling ConnectWindow triggers the QuerySupportedVersion event if you did not first call ClientVersion.
DisconnectWindow(uint Wnd)
Call DisconnectWindow whenever you hide a window that you called ConnectWindow for.
AceTextVersion: int
This function returns the version of the API that the user’s copy of AceText supports. It will also support all previous versions but those may not be able to store all the data that a clip may hold. AceText 1.x.x returns 1. AceText 2.x.x and 3.x.x return 2. AceText 4.x.x returns 4. Future versions may return 4 or a higher number.
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 a FolderID number. 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. It returns the ClipID or FolderID of the replacement. If the clip or folder ID that you pass in the variant structure is the same as that of the original clip or folder, then the replacement clip or folder keeps that ID. Otherwise ReplaceClip() generates a new ID just like AddClip() does. When replacing a folder that contains other clips or folders, those nested clips or folders keep their IDs if the Clip variant structure contains the same number of nested clips and folders and they have the same IDs. Link IDs can be preserved in the same way.
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 and LinkID remain the same. MoveClip can move clips inside a single collection and between different collections.
CanModify(uint ClipID): uint
Returns 1 if the clip or folder identified by ClipID can be modified. Returns 0 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 1 if the folder or collection indicated by FolderID can contain other folders. Returns 0 otherwise. All collections and folders can contain other folders, except the ClipHistory. CanContainFolders returns 1 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.
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.
ExpandParameters(uint ClipID): OleVariant
Looks up the clip indicated by ClipID. Returns that clip if it does not have parameters. Returns a copy of the clip with parameters substituted if it does. Prompts the user to supply values for custom parameters if needed. If AceTextVersion returns 4 or greater then you should call HasParameters before calling ExpandParameters. If you do not call HasParameters then ExpandParameters will still work correctly. But the Substitute Parameters dialog may get stuck behind other Windows. The user will then have to activate it by clicking on AceText’s taskbar window.
These functions are only available if AceTextVersion returns 4 or greater.
ClientVersion(ref int Version)
If AceTextVersion returns 4 or greater then you should call ClientVersion to indicate which version of the variant structure that you want to use. You should set Version to 4 to support all the clip features in AceText 4. But AceText 4 (and future versions) do allow you to set Version to 1 or 2. If you do so, AceText 4 will use version 1 or 2 of the variant structure. You will still be able to call all the functions that AceTextVersion indicates support for. The Version argument is passed by reference to enable forward compatibility. Future versions of AceText may define API levels higher than 4. If you request a version that is greater than the version supported by the user’s copy of AceText then AceText will change the Version parameter to the highest version that is actually available.
HasParameters(uint ClipID): int
Checks whether the clip identified by ClipID has an parameters. Returns 0 if the clip does not exist. Returns 1 if the clip does not have any parameters. You can then retrieve the clip by calling GetClip or ExpandParameters. Returns 2 if the clip has parameters but does not require a prompt. Call ExpandParameters to retrieve a copy of the clip with all parameters substituted. Returns 3 if AceText needs to show the Substitute Parameters dialog. In this case HasParameters makes AceText visible. Your application should call the SetForegroundWindow Win32 API function and pass it the result of AceText’s GetWindowHandle function. Then call ExpandParameters to make AceText show the Substitute Parameters dialog. If AceText was hidden before you called HasParameters then ExpandParameters hides AceText again. ExpandParameters also calls SetForegroundWindow to reactivate the window that had keyboard focus when HasParameters was called.
GetWindowHandle: uint
If your application has keyboard focus and it wants to move keyboard focus to AceText then you should call the SetForegroundWindow Win32 API function and pass it the result of the GetWindowHandle function. If your application is 64-bit then it should convert the 32-bit unsigned integer returned by GetWindowHandle into a 64-bit handle by zero-extending the number so that the upper 32 bits of the 64-bit handle are zero and the lower 32 bits are the 32-bit number returned by AceText.
LinkIDtoString(uint64 LinkID): BSTR
Converts the LinkID that is present as an unsigned 64-bit integer in the variant structure of a clip or folder into a string of up to 11 base64url characters. You can create a minimal URL to point to the clip or folder by appending the result of LinkIDtoString to acetext:clip/. This string is also how Link IDs are stored in the XML of AceText collection files. LinkIDtoString does not check whether the LinkID actually exists. It simply converts the 8 bytes of the LinkID parameter in big endian format to base64url without any leading letters A.
LinkToClip(uint ClipID): OleVariant
Returns an URL pointing to the clip, folder or collection indicated by ClipID as would be generated by Edit|Copy Link.
GetClipFromLinkID(uint64 LinkID): OleVariant
Returns the clip, folder or collection indicated by LinkID. In case of a folder or collection, all clips and folders inside it are also present in the returned variant structure. You should only look up clips by LinkID if your application needs to keep a reference to clips that persists between AceText sessions. Otherwise you should use GetClip to look up the clip by ClipID which is guaranteed to be unique within the AceText session but will change when the collection is closed and reopened.
GetClipFromLinkString(BSTR LinkString): OleVariant
Look up a clip clip, folder or collection using a string returned by LinkIDtoString or LinkToClip.
CanContainSecrets(uint FolderID): uint
Returns 1 if the folder or collection indicated by FolderID can contain secret clips. Returns 0 otherwise. Only collections that are encrypted with a password (and folders within those collections) can contain secret clips.