Note: The files for this article are available from the Bentley Developer Network Example Code archive that is in the Bentley Developer Network Download Category of SELECTservices Online. New in MicroStation V8 XM Edition is the addition of XAttributes as a method of storing additional information with elements. XAttributes consist of information stored in a DGN file that is "connected" to graphical elements in that file. They are somewhat similar to the traditional method of linkage (or user) data that is appended to elements. XAttributes are different in that the data itself is not stored in the element structure but rather separately and "connected" to the element through the transaction manager. The advantage to XAttributes is that the element itself is not modified when the information is appended or otherwise modified. This makes the system more efficient when updates occur. This also allows the format of the data to be more flexible and allows it to hold different and more types of information. The mechanics for connecting XAttributes leverage the ElementRef and ElemHandles data types as well as MicroStation's transaction manager. The data stored can consist of just about any type of information that you need as it relates to an element. To identify that data to MicroStation requires the use of a two-part HandlerID. The first part is the same ID that applications have traditionally used for Linkage data. The second part is an ID that the developer controls to identify this data structure. This allows the data to be related to the developer and the exact data structure is identified only to the developer. After the HandlerID has been set, we need to create the element that will be connected to our XAttributes. We need to get the element reference to use with the XAttributes API. This can be done a number of ways; in this sample we will use the transaction manager to add the element, which will give us back an element reference. The element reference and the XAttributeHandler are then used by the transaction manager AddXAttribute method. This method then adds the XAttribute to the DGN file. ` Private ElementRef CreateXAtterElement ( char *sampleString ) { MSElement el; DPoint3d pt; pt.x = 1000; pt.y = 2000; pt.z = 0; mdlText_create (&el,NULL,sampleString,&pt,NULL,NULL,NULL,NULL); EditElemHandle eh (&el, ACTIVEMODEL); ElementRef ref = NULL; TXNMGR.AddElement (ref, ACTIVEMODEL, eh.GetElemDescrP()); return ref; } /----------+//
char XattrSampleString[512]; if (*unparsed) strcpy (XattrSampleString,unparsed); else strcpy (XattrSampleString,"mark"); ElementRef refEl = CreateXAtterElement (XattrSampleString); XAttributeHandlerId myhandler (999,0); EditElemHandle eh (refEl,mdlModelRef_getActive()); strcpy( dataStruct.pString,XattrSampleString); Xattrsexample_getElmOrigin(eh,&dataStruct.ptData); TXNMGR.AddXAttribute (refEl,myhandler,0,&dataStruct,sizeof dataStruct); mdlSystem_saveDesignFile(); ` The next phase is to extract the XAttributes from the element. To do that, you first need to find the element and then interrogate it to determine whether it has XAttributes. Once you know the element has the correct XAttribute, you then need to look at the data. Assuming that you are looking through the DGN file for a basic element type, you need to get an element handle once you have an element. The element handle class has a method for getting the XAttributes as an iterator. As you loop through the iterator, check the HandlerID for that XAttribute and if it is yours, then use the PeekData method to look at the XAttribute data. It is important to note here that when looking at this data you should not change the "const'ness" of the data. ` ElemHandle::XAttributeIter pIter (eh); if (pIter.IsValid()) { pIter.GetHandlerId() == myhandler; DemoStruct pTest = (DemoStruct)pIter.PeekData(); if (0==strcmp (pTest->pString,XattrSampleString)) printf ("Success in the test %s \n",pTest->pString); else printf ("No Joy in the test \n"); } `In the context of a larger application, XAttributes provide a more flexible and efficient storage container for data connected to elements as opposed to the traditional user linkage method. The data that is stored in XAttributes should not include file positions or elementIDs as the stored data structure is not processed during operations like copy. There is a one-to-one relationship between the element and the XAttribute data, meaning that one XAttribute can only be linked to one element and one only one element can point to an XAttribute, although there can be multiple XAttributes connected to one element. XAttributes are accessible in MicroStation V8 XM Edition only, so although a DGN file created in MicroStation V8 XM Edition can be opened in previous MicroStation editions, the XAttribute will not be visible or accessible. Moving forward, applications moving forward should leverage the power of XAttributes instead of legacy user data structures. |
