Class 12 - Deriving from AcDbObject

Introduction

I will start with Custom Objects and then proceed with custom entities on the next class. Custom objects can be used for several purposes and they are very powerful. Once your application creates and manage a custom object you will be able to construct complex application structures as well as much more intelligent and efficient data storage.

Starting with a simple example, suppose that you will need to build an ObjectARX application which implements some bars that has a length property and several types of shapes. Is possible that more than one bar has the same shape and it would be nice if you can provide a single instance of shape's information and share it among all bars using this shape.

The first impulse is to repeat the information on each bar no matter you will duplicate information. This works but will generate additional problems beyond the first problem which is the unnecessary space used to store the same information. Suppose that you need to update the shape and you would affect all bars that are using this shape. If your information is repeated in all bars you will need to open each bar and update its information. In other hand, if shape's information is stored into one single place and bars reflect this information you will need only to update this information in one place and all bars using this shape will be updated as soon as you update the shape's information.

AutoCAD use this technique on several features like layers, text styles, groups, etc. You will use exactly a custom object to store this information and share it, through its ObjectId, among all "clients" of this object.

How to begin

As discussed on previous class, you will need to derive from AcDbObject to be able to build your own custom object. This can be easily done using the ARXWizard or you can do by yourself creating the class by hand.

After create the class you need build some methods to create, store and acquire those objects instances from its container. Well, but where you should store your custom objects? AutoCAD provides a general purpose container called Named Object Dictionary (NOD). NOD is capable to store and persist any custom object derived from AcDbObject. It uses a dictionary like storage structure where you put a unique key (at the same level) and an object instance through its pointer and ObjectId. There are other custom object containers like Extension Dictionary that I will avoid due our course audience.

The NOD container could (and should) be organized by folders to make your dictionary as much organized as you can. The first node should be your application name to avoid conflict with other third-party ObjectARX applications that could use the NOD at the same time as you. The second level should contain all your business groups of objects. This will really depend on how many and the number of custom object types you have. NOD does not prohibit you to stored different classes at the same level but I really recommend you to avoid this except in case you need to stored generic objects together like on a Preferences group of objects.

You don't need to always Open and Close the NOD and go deep to find where are your desired object every time you need to access it. You can build some kind of cache of the most used Objects through its ObjectId and manage this cache to be updated for every single opened drawing. Remember that NOD is part of AcDbDatabase object and it is per document. So, you need to care about to build and fill your dictionary for every brand new drawing.

How to persist your custom objects

As I said before, the most used place to store custom objects is the NOD which is an AcDbDictionary. NOD takes care of its child objects because it is a container. So, when the AcDbDatabase object is issued to save its data by AutoCAD it also pass this message to its child objects and NOD is one of them. Once NOD receives this message it walks through its structure and call dwgOutFields() for every object stored there. The same process occurs when you open the drawing and the dwgInFields() is called by AcDbDatabase on NOD and consequently on its children. Exactly due that you will need to override the DWG filling methods to make possible to persist your custom objects among DWG open/close sessions.

Essential functions to override in your custom object class are:

virtual Acad::ErrorStatus dwgInFields(AcDbDwgFiler* filer);
virtual Acad::ErrorStatus dwgOutFields(AcDbDwgFiler* filer) const;
virtual Acad::ErrorStatus dxfInFields(AcDbDxfFiler* filer);
virtual Acad::ErrorStatus dxfOutFields(AcDbDxfFiler* filer) const;

If you don't plan to support DXF interface to your custom object you could avoid them.

Object's state management

On class 5 we have talked about object states when opening objects. Inside your custom object class you need to pay attention to call the proper assert method to make sure that all proper events and processes are fired when your object's state has changed. This is very important!

Those functions who change your object's data state must first call the assertWriteEnabled() function and then apply the required modifications. Functions who only read information from your object and does not affect its data state must call assertReadEnabled() function and also I really recommend that you make all these as const functions. This will avoid you to accidentally change the object's state when it is opened for read what will cause an assert error message. If you forget to call the proper assert method strange things may occur like call UNDO and your object stay unchanged and a lot other bizarre things.

How to create a custom object

To implement your custom object you will need to do the following:

1- Derive from AcDbObject;
2- Implement your data;
3- Implement access functions (read/write) with proper assert calls;
4- Implement the filling methods persisting and reading your data;

As a baseline, I will present a short example here:

// -------------------------------------------
// Class declaration
// -------------------------------------------

class MyClass : public AcDbObject {

public:
ACRX_DECLARE_MEMBERS(MyClass);

MyClass() {};
virtual ~MyClass() {};

Acad::ErrorStatus getVal (int& val) const;
Acad::ErrorStatus setVal (int val);

Acad::ErrorStatus getString (CString& str) const;
Acad::ErrorStatus setString (LPCTSTR str);

virtual Acad::ErrorStatus dwgInFields(AcDbDwgFiler*);
virtual Acad::ErrorStatus dwgOutFields(AcDbDwgFiler*) const;

private:
int m_Val;
CString m_Str;

};

// -------------------------------------------
// Class Definition
// -------------------------------------------

ACRX_DXF_DEFINE_MEMBERS(MyClass,
AcDbObject, AcDb::kDHL_CURRENT,
AcDb::kMReleaseCurrent, 0, MYCLASS, MYSAMP);

// -------------------------------------------
Acad::ErrorStatus MyClass::getVal (int& val) const {

assertReadEnabled();
val = m_Val;
return Acad::eOk;

}
// -------------------------------------------
Acad::ErrorStatus MyClass::setVal (int val) {

assertWriteEnabled();
m_Val = val;
return Acad::eOk;

}
// -------------------------------------------
Acad::ErrorStatus MyClass::getString (CString& str) const {

assertReadEnabled();
str.Format(_T("%s"),m_Str);
return Acad::eOk;

}
// -------------------------------------------
Acad::ErrorStatus MyClass::setString (LPCTSTR str) {

assertWriteEnabled();
m_Str.Format(_T("%s"),str);
return Acad::eOk;

}
// -------------------------------------------
Acad::ErrorStatus MyClass::dwgInFields(AcDbDwgFiler* pFiler) {

assertWriteEnabled();
AcDbObject::dwgInFields(pFiler);

Adesk::Int16 _val = 0;
pFiler->readInt16(&_val);
m_Val = _val;
TCHAR* _temp = NULL;
pFiler->readString(&_temp);
m_Str.Format(_T("%s"),_temp);
acutDelString(_temp);

return pFiler->filerStatus();

}
// -------------------------------------------
Acad::ErrorStatus MyClass::dwgOutFields(AcDbDwgFiler* pFiler) const {

assertReadEnabled();
AcDbObject::dwgOutFields(pFiler);

pFiler->writeInt16(m_Val);
pFiler->writeString(static_cast<const TCHAR*>(m_Str));

return pFiler->filerStatus();

}
// -------------------------------------------

// -------------------------------------------
// Entry Point
// -------------------------------------------
AcRx::AppRetCode acrxEntryPoint(AcRx::AppMsgCode msg, void* appId) {
switch (msg) {
case AcRx::kInitAppMsg:

acrxDynamicLinker->unlockApplication(appId);
acrxDynamicLinker->registerAppMDIAware(appId);

MyClass::rxInit();
acrxBuildClassHierarchy();

break;

case AcRx::kUnloadAppMsg:

deleteAcRxClass(MyClass::desc());

break;
}

return AcRx::kRetOK;
}

How to create and store your custom object

The NOD container is based on AcDbDictionary class which has several methods to read, write and erase entries. Your application needs to take care of NOD entries and be responsible to create instances of your custom class and store these objects inside the NOD. Each object stored must have a key defined or a generic key using the star * as its name.

void createMyObjects() {

AcDbDictionary *pNamedobj = NULL;
acdbHostApplicationServices()->workingDatabase()->
getNamedObjectsDictionary(pNamedobj, AcDb::kForWrite);

AcDbDictionary *pDict = NULL;
if (pNamedobj->getAt(_T("MYDICT"),(AcDbObject*&) pDict,
AcDb::kForWrite) == Acad::eKeyNotFound) {

pDict = new AcDbDictionary;
AcDbObjectId DictId;
pNamedobj->setAt(_T("MYDICT"), pDict, DictId);

}

pNamedobj->close();

if (pDict) {

MyClass *pObj1 = new MyClass();

pObj1->setVal(1);
pObj1->setString(_T("String1"));

MyClass *pObj2 = new MyClass();

pObj2->setVal(2);
pObj2->setString(_T("String2"));

AcDbObjectId rId1, rId2;

pDict->setAt(_T("*M"),pObj1, rId1);
pDict->setAt(_T("*M"),pObj2, rId2);

pObj1->close();
pObj2->close();

pDict->close();

}
}

How to verify if my objects are really stored inside NOD?

You will need to iterate the NOD entries to find your dictionary and then perform an iteration over its entries. The process should be something like this:

void listMyObjects() {

AcDbDictionary *pNamedobj = NULL;
acdbHostApplicationServices()->workingDatabase()
->getNamedObjectsDictionary(pNamedobj, AcDb::kForRead);

AcDbDictionary *pDict = NULL;
pNamedobj->getAt(_T("MYDICT"), (AcDbObject*&)pDict,AcDb::kForRead);
pNamedobj->close();

if (pDict == NULL) {

acutPrintf(_T("\nThe dictionary MYDICT does not exist. Please create it first!"));
return;

}

AcDbDictionaryIterator* pDictIter= pDict->newIterator();

MyClass *pMyClass;
int _val;
CString _str;

for (; !pDictIter->done(); pDictIter->next()) {

pMyClass = NULL;
pDictIter->getObject((AcDbObject*&)pMyClass,AcDb::kForRead);

if (pMyClass != NULL) {

pMyClass->getVal(_val);
pMyClass->getString(_str);
pMyClass->close();
acutPrintf(_T("\nMyClass: val=%d, str=%s"),_val,_str);

}

}

delete pDictIter;
pDict->close();
}

Stay tuned for the next Lab which will require you to build a custom object. See you there!