SDK:Tagged Data
.SDK|SDK ..SDK:Types|SDK Types ..SDK:Using the SDK|Using the SDK ..VCOM:VCOM (Vectorworks Component Object Model)|VCOM Basics ..VCOM:Class Reference|VCOM Class Reference
What is this?
Tagged Data is more complex mechanism for storing data into objects than SDK:User Data.
It is used to store typed data into memory block. This typed data is recognized by VectorWorks.
For example if you store Color Reference index in the data block, when the object in whose AUX list this Tagged Data is attached is copy-pasted into another document, VectorWorks will translate the Color Reference index so it matches the same color in the new document.
Tagged Data objects are identified by Four Char Code (or in other works a Uint32) identifier. That identifier identifies data container object. This means that you can have many data container objects (User Data Objects) inside single VectorWorks object.
Inside the data container there are tags (or fields) of data. Each tag is an array of values of the same type.
There are the following functions for tagged data:
- ISDK::TaggedDataCreate
- ISDK::TaggedDataRemoveContainer
- ISDK::TaggedDataRemoveTag
- ISDK::TaggedDataGetNumElements
- ISDK::TaggedDataGet
- ISDK::TaggedDataSet
The following data tag value types are supported:
Type Constant Name | Value | Data type | Description |
---|---|---|---|
kTaggedDataByteArrayTypeID | 1 | Uint8 | Array of single byte type. |
kTaggedDataFlagsContainerTypeID | 2 | - | Not implemented yet! Boolean flags array. Up to 32 flags per tag. |
kTaggedDataDoubleArrayTypeID | 6 | double | Array of double number type. |
kTaggedDataTramsformMatrixTypeID | 7 | TransformMatrix | One transformation type. |
kTaggedDataUint32ArrayTypeID | 8 | Uint32 | Array of Sint32 number type. |
kTaggedDataColorRefArrayTypeID | 13 | ColorRef | Array of Color Reference index. |
kTaggedDataObjectRefArrayTypeID | 15 | InternalIndex | Array of indexes to VectorWorks objects. |
Sample
Data
Create tagged data with two tagged values:
// define the tag constants #define kMyContainerID (OSType)'MyTD' #define kTag1ID 1 // Create tagged data and set one tag value // Creates two Uint32 values inside a tag 'kTag1ID' gSDK->TaggedDataRemoveContainer( hObject, kMyContainerID ); if ( gSDK->TaggedDataCreate( hObject, kMyContainerID, kTaggedDataUint32ArrayTypeID, kTag1ID, 2 ) ) { Uint32 data1 = 1234; Uint32 data2 = 5678; // set the two tag values gSDK->TaggedDataSet( hObject, kMyContainerID, kTaggedDataUint32ArrayTypeID, kTag1ID, 0, & data1 ); gSDK->TaggedDataSet( hObject, kMyContainerID, kTaggedDataUint32ArrayTypeID, kTag1ID, 1, & data2 ); }
Reading the values:
// Read a tag value from tagged data Uint32 data1 = 0; Uint32 data2 = 0; // prepare reading pointer. // Tag reading returns Uint32* pData = NULL; // read the first tag value if ( gSDK->TaggedDataGet( hObject, kMyContainerID, kTaggedDataUint32ArrayTypeID, kTag1ID, 0, & pData ) ) { data1 = *pData; } // read the second tag value if ( gSDK->TaggedDataGet( hObject, kMyContainerID, kTaggedDataUint32ArrayTypeID, kTag1ID, 1, & pData ) ) { data2 = *pData; }
Reading the values as array:
// reading the entire array long dataLen = 0; gSDK->TaggedDataGetNumElements( hObject, kMyContainerID, kTaggedDataUint32ArrayTypeID, kTag1ID, & dataLen ); Uint32* pData = NULL; if ( dataLen == 2 && gSDK->TaggedDataGet( hObject, kMyContainerID, kTaggedDataUint32ArrayTypeID, kTag1ID, 0, & pData ) ) { data1 = pData[ 0 ]; data2 = pData[ 1 ]; }
TXString
Creating tagged data for a string:
// define the tag constants #define kMyContainerID (OSType)'MyTD' #define kTag1ID 1 TXString myString = "Hello world!"; // Create tagged data for a string gSDK->TaggedDataRemoveContainer( hObject, kMyContainerID ); if ( gSDK->TaggedDataCreate( hObject, kMyContainerID, kTaggedDataByteArrayTypeID, kTag1ID, myString.GetLength() ) ) { // set the value Uint8* pData = NULL; if ( gSDK->TaggedDataGet( hObject, kMyContainerID, kTaggedDataByteArrayTypeID, kTag1ID, 0, & pData ) ) { // treat it as zero terminated string (C style) myString.CopyInto( (char*) pData ); } }
Reading the string:
TXString myString; // reading the string long dataLen = 0; gSDK->TaggedDataGetNumElements( hObject, kMyContainerID, kTaggedDataByteArrayTypeID, kTag1ID, & dataLen ); myString.Clear(); Uint8* pData = NULL; if ( dataLen > 0 && gSDK->TaggedDataGet( hObject, kMyContainerID, kTaggedDataByteArrayTypeID, kTag1ID, 0, & pData ) ) { myString = TXString( (const char*) pData, size_t(dataLen) ); }