Iterating through Layers

To traverse through the layer table, use the OdDbSymbolTableIterator class that implements the bidirectional iterator in the table of named records. The iterator refers to the layer of the layer table for which it can return various information. The iterator has the start() method for setting the start position to the first or last layer, the step() method for traversing to the next or previous layer, the done() method for checking the result, the seek() method for finding the specified layer, and the getRecordId() method and the getRecord() method for getting an existing layer to which the iterator refers. In the following examples, the pLayers variable stores a pointer to the layer table object.

Creating an iterator

The iterator must be created before traversing. To create a new iterator, declare a variable of the OdDbSymbolTableIteratorPtr type and call the NewIterator() method of the layer table object. The NewIterator() method creates the instance of the iterator, sets the new iterator to the first unerased layer record object in the layer table, and returns the typified smart pointer to it. For example:


OdDbSymbolTableIteratorPtr itLayer1 = pLayers->newIterator();

To set the default position of the new iterator, use the first and second arguments of the NewIterator() method. The first argument specifies the start position as a Boolean value which is True when the start position is the first layer record object in the table or False when the start position is the last layer record object in the table. The second argument specifies the erase status as a Boolean value which is True when the first or last layer record object must have the unerased status (that is, the layer cannot be erased) or False when the first or last layer record object can have any status (that is, the layer is either erased or unerased). Both arguments are optional and are set to True by default. For example:


// Create a new iterator in the position of the last unerased layer
OdDbSymbolTableIteratorPtr itLayer2 = pLayers->newIterator(false, true);

// Create a new iterator in the position of the first erased or unerased layer
OdDbSymbolTableIteratorPtr itLayer3 = pLayers->newIterator(true, false);

The created iterator can be used multiple times for traversing through layers from the beginning to the end or from the end to the beginning of the layer table.

Placing an iterator in the start position

Multiple use of the iterator requires setting the start position for new traversing. To set the start position of an existing iterator, use the start() method to move it to the first or last layer in the layer table and reinitialize the traversing. For example:


itLayer1->start();

The start() method has two arguments and does not return a value. The first argument specifies the start position as a Boolean value which is True when the first layer record object is the start position for traversing forward or False when the last layer record object is the start position for traversing backward. The second argument specifies the erase status as a Boolean value which is True when the layer record object must have the unerased status or False when the layer record object can have the erased or unerased status. Both arguments are optional and are set to True by default. For example:


// Set the iterator to the first unerased layer
// itLayer1->start(true, true);   or   itLayer1->start()

// Set the iterator to the last unerased layer
itLayer2->start(false, true);

// Set the iterator to the first erased or unerased layer
itLayer3->start(true, false);

Moving an iterator

To move the iterator through layers, use the step() method which traverses it to the beginning or end of the layer table. The step() method moves the iterator to the next unerased layer record object by default. For example:


itLayer1->step();

The step() method has two arguments and does not return a value. The first argument specifies the traverse direction as a Boolean value which is True when the iterator moves forward to the next layer record object or False when the iterator moves backward to the previous layer record object. The second argument specifies the erase status as a Boolean value which is True when the iterator skips erased layer record objects or False when the iterator processes each existing layer record object of any status. Both arguments are optional and are set to True by default. For example:


// Move the iterator forward to the next unerased layer
// itLayer1->step(true, true);   or   itLayer1->step();

// Move the iterator backward to the previous unerased layer
itLayer2->step(false, true);

// Move the iterator forward to the next layer of the erased or unerased status
itLayer3->step(true, false);

Checking an iterator

To check whether traversing of the iterator is completed, use the done() method that returns True when the iterator is out of the traverse scope or False when the iterator is placed within the traverse scope. For example:


while(!itLayer1->done()) itLayer1->step();

Getting a layer using the iterator

To get the layer, declare a variable of the OdDbLayerTableRecordPtr type and use the getRecord() method which returns the smart pointer to the referenced layer record object to which the iterator refers. The getRecord() method opens the unerased layer record object in read mode by default. For example:


OdDbLayerTableRecordPtr pLayer1 = itLayer1->getRecord();

The getRecord() method can have two optional arguments: The first argument specifies the mode for opening the layer record object as a value of the OdDb::OpenMode enumerator (kForRead, kForWrite, or kForNotify). The value is OdDb::kForRead by default. The second argument specifies the erase status as a Boolean value which is True when the iterator must open an erased layer record object or False when the iterator must open the unerased layer record object. The value is False by default. For example:


// Open the unerased layer object in the read mode
// pLayer1 = itLayer1->getRecord(OdDb::kForRead, false);   or   pLayer1 = itLayer1->getRecord();

// Open the unerased layer object in the write mode
OdDbLayerTableRecordPtr pLayer2 = itLayer2->getRecord(OdDb::kForWrite, false);

// Open the erased layer object in the notify mode
OdDbLayerTableRecordPtr pLayer3 = itLayer3->getRecord(OdDb::kForNotify, true);

Alternatively, the iterator can open the layer using the getRecordId() method; it does not have arguments and returns the OdDbObjectId instance associated with the layer record object to which the iterator refers. For example:


OdDbObjectId idLayer1 = itLayer1->getRecordId();

To get the smart pointer to the layer record object using its object ID, use the safeOpenObject() method of the OdDbObjectId object and pass to it the open mode as a value of the OdDb::OpenMode enumerator and the erase status as a Boolean value. The first argument is OdDb::kForRead by default; the second argument is False by default. For example:


// Open the unerased layer object in the read mode
OdDbLayerTableRecordPtr pLayer1 = idLayer1.safeOpenObject();

// Open the unerased layer object in the write mode
OdDbLayerTableRecordPtr pLayer2 = itLayer2->getRecordId().safeOpenObject(OdDb::kForWrite, false);

// Open the erased layer object in the notify mode
OdDbLayerTableRecordPtr pLayer3 = itLayer3->getRecordId().safeOpenObject(OdDb::kForNotify, true);

Examples of iterating

The following example demonstrates iterating through unerased layers from the beginning to the end of the layer table for printing:


odPrintConsoleString(L"\nThe list of the accessible layers:");

for(itLayer1->start() ; !itLayer1->done() ; itLayer1->step())
{
  pLayer1 = itLayer1->getRecord();
  odPrintConsoleString(L"\n[%ls] Layer: \"%ls\"", pLayer1->handle().ascii(), pLayer1->getName().c_str());
}

The following example demonstrates iterating through unerased layers from the end to the beginning of the layer table for modifying properties:


for(itLayer2->start(false, true) ; !itLayer2->done() ; itLayer2->step(false, true))
{
  pLayer2 = itLayer2->getRecord(OdDb::kForWrite);
  pLayer2->setIsFrozen(false);
  pLayer2->setIsOff(true);
  pLayer2->setIsLocked(false);
  pLayer2->setIsPlottable(true);
}

The following example demonstrates iterating through layers of the unerased or erased status from the beginning to the end of the layer table:


odPrintConsoleString(L"\nThe list of layers:");

for(itLayer3->start(true, false) ; !itLayer3->done() ; itLayer3->step(true, false))
{
  pLayer3 = itLayer3->getRecordId().safeOpenObject(OdDb::kForRead, true);
  odPrintConsoleString(L"\nLayer: \"%ls\" is %ls", pLayer3->getName().c_str(), 
                       ((pLayer3->isErased()) ? L"erased" : L"unerased"));
}