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 Borland Delphi, you can use the Variant type, which is a dynamic type. Just use the array syntax, e.g. AceText := 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 will use the version of the structure reported by your application through QuerySupportedVersion or by AceText through AceTextVersion, whichever is less. Your application should do the same.

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. The format is quite straightforward.

The Variant is an array with eight elements:

0: An integer with the ID of the clip. Ignore in the AcePaste event handler. You can use this ID with the advanced functions that expect a ClipID. When you tell AceText to add a clip, it will ignore whatever ID you pass. So simply pass zero.
1: An integer indicating the kind of clip. 1 = plain text; 2 = rectangular text; 3 = binary data; 4 = before and after text; 5 = web snippet
2: An integer with options. 0 = none; 1 = indented clip
3: An OLE string with the clip's label. Can be an empty string.
4: An OLE string with the clip's AceType abbreviation. Can be an empty string.
5: An OLE string with the clip's text, or the before text in case of a "before and after" clip. Can be an empty string.
6: An OLE string with the either the clip's "after" text, or the clip's URL, in case of a "before and after" or "web snippet" clip, respectively. This element must be present in the array, even if the clip is not a "before and after" or "web snippet" clip. In that case, just pass an empty string.
7: An OLE date/time stamp with the clip's date and time.

The above describes version 2 of the variant structure, which is a minor expansion of the first version. Version 1 of the structure has only seven elements. The last element with the date and time is not supported. The "web snippet" kind is also not supported.

Variant holding a folder or collection

The same structure is used for a folder and for an entire AceText collection. Again, the Variant is an array, this time with a variable length. There are always at least 4 elements.

0: An integer with the ID of the clip. Ignore in the AcePaste event handler. You can use this ID with the advanced functions that expect a ClipID. When you tell AceText to add a clip, it will ignore whatever ID you pass. So simply pass zero.
1: An integer indicating the kind of item. Must be zero to denote a folder. Use this element to check if the variant holds a clip or a folder.
2: An OLE string with the folder's label. Can be an empty string.
3: An integer indicating the number of items in the folder. Can be zero.

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.

Note that the array is not flattened. A variant defining a folder with two clips has 6 elements, not 4 + 2*8 = 20 elements.

The variant structure for folders is unchanged between version 1 and version 2 of the variant structure.