SDK:Tagged Data

From Vectorworks Developer
Jump to navigation Jump to search

.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:

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) );
}

See Also

SDK:The VectorWorks Environment | SDK:User Data