Class 7 - Containers

Hello,

On this class I will present the concepts and features of ObjectARX container objects. We have talked a little bit about them before but now we will go into further details.

Introduction

The container object purpose is to store and manage objects of the same type or class. There are two types of containers: Symbol Tables and Dictionaries. Each type of container has some specific functionalities that were designed to allow easy and efficient access methods.

Symbol Tables

This type of container is designed to store the so called records. Each Symbol Table object store its records using an unique entry name. Through this entry you can obtain the record pointer and read or write information. The container may also receive new entries or even has entries removed (in case they are not used by other objects).

To walk through an object container entries you will need to use a proper iterator which will allow you to get entries and access its objects. AutoCAD has some Symbol Tables to store layers, linetypes, text styles and other objects. As these containers work almost the same way, there is a common base class for each of Symbol Tables, its records and the proper iterators.

The Symbol Table class tree is as follows:

AcDbSymbolTable

AcDbAbstractViewTable

AcDbViewportTable
AcDbViewTable

AcDbBlockTable
AcDbDimStyleTable
AcDbLayerTable
AcDbLinetypeTable
AcDbRegAppTable
AcDbTextStyleTable
AcDbUCSTable

AcDbSymbolTableRecord

AcDbAbstractViewTableRecord

AcDbViewportTableRecord
AcDbViewTableRecord

AcDbBlockTableRecord
AcDbDimStyleTableRecord
AcDbLayerTableRecord
AcDbLinetypeTableRecord
AcDbRegAppTable
AcDbTextStyleTable
AcDbUCSTable

AcDbSymbolTableIterator

AcDbAbstractViewTableIterator

AcDbViewportTableIterator
AcDbViewTableIterator

AcDbBlockTableIterator
AcDbDimStyleTableIterator
AcDbLayerTableIterator
AcDbLinetypeTableIterator
AcDbRegAppTableIterator
AcDbTextStyleTableIterator
AcDbUCSTableIterator

So, to create a layer, for instance, you will need to:

• Open current Database;
• Open AcDbLayerTable (for write);
• Create an AcDbLayerTableRecord (using new operator);
• Configure the AcDbLayerTableRecord;
• Add it to AcDbLayerTable which is its proper container;
• Close the record;
• Close the container.

void createLayer() {

AcDbLayerTable *pLayerTbl = NULL;
acdbHostApplicationServices()->workingDatabase()
->getSymbolTable(pLayerTbl, AcDb::kForWrite);

if (!pLayerTbl->has(_T("MYLAYER"))) {

AcDbLayerTableRecord *pLayerTblRcd = new AcDbLayerTableRecord;
pLayerTblRcd->setName(_T("MYLAYER"));

AcCmColor color;
color.setColorIndex(1); // red
pLayerTblRcd->setColor(color);
pLayerTbl->add(pLayerTblRcd);
pLayerTblRcd->close();

} else acutPrintf("\nLayer already exists");
pLayerTbl->close();

}

To list all existing layers:

• Open current Database;
• Open AcDbLayerTable (for read);
• Create an AcDbLayerTableIterator;
• Perform a loop through container entries;
• Get the key name for each entry;
• Close the container.
  

void iterateLayers() {

AcDbLayerTable* pLayerTbl = NULL;
acdbHostApplicationServices()->workingDatabase()
->getSymbolTable(pLayerTbl, AcDb::kForRead);

AcDbLayerTableIterator* pLayerIterator;
pLayerTbl->newIterator(pLayerIterator);

AcDbLayerTableRecord* pLayerTblRcd;
TCHAR* pLName;
for (; !pLayerIterator->done(); pLayerIterator->step()) {

pLayerIterator->getRecord(pLayerTblRcd, AcDb::kForRead);
pLayerTblRcd->getName(pLName);
pLayerTblRcd->close();
acutPrintf(_T("\nLayer name: %s"),pLName);
acutDelString(pLName);

}
delete pLayerIterator;
pLayerTbl->close();

}

Dictionaries

This type of container is designed to store generic AcDbObject derived class objects. This container is very useful because we can also store our custom objects inside it. The dictionary structure is much like a tree structure where we have nodes and entries. Inside the same node, entries can not repeat its name because they need to be unique inside the same level. These are the so called Key entries and each Key entry will map to an AcDbObject pointer which can be retrieved directly or through an interator (AcDbDictionaryIterator).

To store an object we need to create an entry using the setAt() method passing also the object pointer which we already have instantiated with the new operator. After add this object we need to close() it. AcDbDictionary container will return the given AcDbObjectId for each entry.

This container is also used by some AutoCAD features like groups and multiline styles. We will cover more about Dictionaries on the Custom Objects chapter.