AceText Variant Structure

When communicating with AceText through its COM automation interface, your application will send and receive clips, folders and collections through an OLE Variant. The Variant is an array, with a dynamic number of elements. Each element is another Variant, which can potentially be arrays of their own.

In Delphi, you can use the Variant type, which is a dynamic type. Just use the array syntax such as ClipText := MyVariant[5] and the Delphi compiler automatically performs the proper casting.

In C#, the AcePaste event’s Clip parameter is of type object. You need to explicitly cast the object into an object[]. Then you can access the elements in the array, which you will again need to cast explicitly. See the sample source code on how to do this.

When AceText passes a Variant to your application it uses the version of the structure reported by your application through the ClientVersion function (AceText 4) or the QuerySupportedVersion event handler (AceText 3 and prior) or the version reported AceText through the AceTextVersion function, whichever is less. Your application should do the same.

ClipID and LinkID

In all versions of AceText all clips, folders, and collections have an ID number that is guaranteed to be unique across all open collections during the current session of AceText. It is the first element (index 0) in every array in the variant structure. This is the number that you pass as the ClipID, FolderID, or CollectionID argument to AceText’s functions to indicate the clip, folder, or collection that you want the function to work on. If a collection is closed and reopened then the collection itself and all clips and folders in it get new CollectionID, ClipID, and FolderID numbers. So you can use this to uniquely reference an item in AceText, but only while its collection is open in AceText.

In AceText 4 clips and folders additionally have an immutable LinkID number. When you add a clip or folder AceText generates a new semi-random LinkID for it that is guaranteed to be unique within the collection and across all collections that are open in AceText when the LinkID is generated. When you duplicate a clip or folder the duplicate gets a new LinkID. The LinkID is stored in the AceText collection file. Because collection files can be copied and edited outside AceText, there is no guarantee that the LinkID remains unique. Use the LinkID if you want to keep a reference to an item in a collection that persists with the collection. Only the Link and GetClipFromLink functions in AceText’s COM automation interface use the LinkID.

AceText ignores the first element (index 0) and the LinkID element when you pass an OleVariant to a function. You should set both elements to 0. AceText will generate new ID numbers and ensure uniqueness. The only exception is the ReplaceClip() function which keeps the replaced clip's ClipID and LinkID unchanged if you put the same IDs that the clip already has in the OleVariant you pass to the Clip argument.

Variant Holding a Single AceText Clip

The AcePaste event handler will always send a Variant that holds a single clip. If you don’t use advanced AceText integration, this is all your application needs to support. For a single clip, the Variant is a flat array. All elements must be present.

Version 4

Version 2

Version 1

Version 1 of the Variant for a single clip is the same as version 2 but with 7 elements instead of 8. The last element with the date and time is not supported. The “web snippet” kind is also not supported.

Clip Kinds

The second element (index 1) in the variant array is an integer indicating the kind of clip. Some clip kinds are only supported by some versions.

In AceText 2, a clip can only have an URL if it is of type "web snippet". In AceText 4, all clips can have an URL, making the "web snippet" clip type redundant. But AceText 4 still supports clip kind #5 if you use version 2 of the variant structure.

Flags

The third element (index 2) in the variant array is a bit mask setting certain options for the clip. The table below indicates all possible combinations of the bit mask.

AceText 4 only expands parameters if the Parameters checkbox is ticked. AceText 3 and prior didn’t have this checkbox. They always expanded parameters. If you use version 4 of the variant structure then you determine the state of the Parameters checkbox via the flags. If you use version 1 or 2 of the variant structure to send a clip to AceText 4 then AceText 4 ticks the Parameters checkbox if (and only if) the clip’s text actually contains any parameters.

Link ID

The variant array for clips and folders stores the link ID as an unsigned 64-bit integer. You can convert this number to the ASCII string described in the Edit|Copy Link help topic using the following steps.

1. Store the ID as a big endian 64-bit number.
2. Convert the 8 bytes to 11 characters using base64url (which is the same as base64 but using - and _ instead of + and /) without padding.
3. Strip any leading A characters.

Variant Holding a Folder or Collection

The Variant that holds a folder is also an array. The total number of elements is variable. There is a fixed number of elements at the start of the array that must always be present. Their number depends on the version of the variant structure as listed in the tables below.

Then, for each element in the folder, the Variant has one element that is a variant array itself. In other words, a Variant defining a folder with two clips has 6 elements. The last two elements are variant arrays too. The array is not flattened. A Variant defining a folder with two clips has 6 elements, not 4 + 2*8 = 20 elements.

Version 4

Versions 1 and 2