Iterating through UCSs

To traverse through the UCS table, use the OdDbSymbolTableIterator class which implements the bidirectional iterator in the table of named records. The iterator refers to the UCS of the UCS table for which it can return various information. The iterator has the start() method for setting the start position to the first or last UCS, step() method for traversing to the next or previous UCS, done() method for checking the result, seek() method for finding of the specified UCS, and getRecordId() and getRecord() methods for getting an existing UCS to which the iterator refers. In the examples below, the pUCSs variable stores a pointer to the UCS 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 UCS table object. The NewIterator() method creates the instance of the iterator, sets the new iterator to the first unerased UCS record object in the UCS table, and returns the typified smart pointer to it. For example:


OdDbSymbolTableIteratorPtr itUCS1 = pUCSs->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 takes a True value when the start position is the first UCS record object in the table, or a False value when the start position is the last UCS record object in the table. The second argument specifies the erase status as a Boolean value which takes a True value when the first or last UCS record object must have the unerased status (that is, the UCS cannot be erased), or a False value when the first or last UCS record object can have any status (that is, the UCS either is 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 UCS
OdDbSymbolTableIteratorPtr itUCS2 = pUCSs->newIterator(false, true);

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

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

Placing an iterator in the start position

Using an iterator multiple times requires the start position to be set for new traversing. To set the start position of an existing iterator, use the start() method to move the iterator to the first or last UCS in the UCS table and reinitialize the traversing. For example:


itUCS1->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 UCS record object is the start position for traversing forward or False when the last UCS 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 UCS record object must have only an unerased status or False when the UCS record object can have erased or unerased status. Both arguments are optional and are set to True by default. For example:


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

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

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

Moving an iterator

To move the iterator through a UCS, use the step() method to traverse it forward or backward in the UCS table. The step() method moves the iterator to the next unerased UCS record object by default. For example:


itUCS1->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 UCS record object or False when the iterator moves backward to the previous UCS record object. The second argument specifies the erase status as a Boolean value which is True when the iterator skips erased UCS record objects or False when the iterator processes each existing UCS 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 UCS
// itUCS1->step(true, true);   or   itUCS1->step();

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

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

Checking an iterator

To check whether the traversing of the iterator is complete, use the done() method which 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(!itUCS1->done()) itUCS1->step();

Getting a UCS using the iterator

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


OdDbUCSTableRecordPtr pUCS1 = itUCS1->getRecord();

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


// Open the unerased UCS object in the read mode
// pUCS1 = itUCS1->getRecord(OdDb::kForRead, false);   or   pUCS1 = itUCS1->getRecord();

// Open the unerased UCS object in the write mode
OdDbUCSTableRecordPtr pUCS2 = itUCS2->getRecord(OdDb::kForWrite, false);

// Open the erased UCS object in the notify mode
OdDbUCSTableRecordPtr pUCS3 = itUCS3->getRecord(OdDb::kForNotify, true);

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


OdDbObjectId idUCS1 = itUCS1->getRecordId();

To get the smart pointer to a UCS 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, and the second argument is False by default. For example:


// Open the unerased UCS object in the read mode
OdDbUCSTableRecordPtr pUCS1 = idUCS1.safeOpenObject();

// Open the unerased UCS object in the write mode
OdDbUCSTableRecordPtr pUCS2 = itUCS2->getRecordId().safeOpenObject(OdDb::kForWrite, false);

// Open the erased UCS object in the notify mode
OdDbUCSTableRecordPtr pUCS3 = itUCS3->getRecordId().safeOpenObject(OdDb::kForNotify, true);

Examples of iterating

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


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

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

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


OdGePoint3d point(10,10,10);
for(itUCS2->start(false, true) ; !itUCS2->done() ; itUCS2->step(false, true))
{
  pUCS2 = itUCS2->getRecord(OdDb::kForWrite);
  pUCS2->setOrigin(point);
}

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