Iterating through Registered Applications

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


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

// Create a new iterator in the position of the first erased or unerased registered application
OdDbSymbolTableIteratorPtr itRegApp3 = pRegApps->newIterator(true, false);

The created iterator can be used multiple times for traversing through registered applications from the beginning to the end or from the end to the beginning of the registered application 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 registered application in the registered application table and reinitialize the traversing. For example:


itRegApp1->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 registered application record object is the start position for traversing forward or False when the last registered application 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 registered application record object must have the unerased status or False when the registered application 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 registered application
// itRegApp1->start(true, true);   or   itRegApp1->start()

// Set the iterator to the last unerased registered application
itRegApp2->start(false, true);

// Set the iterator to the first erased or unerased registered application
itRegApp3->start(true, false);

Moving an iterator

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


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

// Move the iterator backward to the previous unerased registered application
itRegApp2->step(false, true);

// Move the iterator forward to the next registered application of the erased or unerased status
itRegApp3->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(!itRegApp1->done()) itRegApp1->step();

Getting a registered application using the iterator

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


OdDbRegAppTableRecordPtr pRegApp1 = itRegApp1->getRecord();

The getRecord() method can have two optional arguments: The first argument specifies the mode for opening the registered application 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 registered application record object or False when the iterator must open the unerased registered application record object. The value is False by default. For example:


// Open the unerased registered application object in the read mode
// pRegApp1 = itRegApp1->getRecord(OdDb::kForRead, false);   or   pRegApp1 = itRegApp1->getRecord();

// Open the unerased registered applicationobject in the write mode
OdDbRegAppTableRecordPtr pRegApp2 = itRegApp2->getRecord(OdDb::kForWrite, false);

// Open the erased registered application object in the notify mode
OdDbRegAppTableRecordPtr pRegApp3 = itRegApp3->getRecord(OdDb::kForNotify, true);

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


OdDbObjectId idRegApp1 = itRegApp1->getRecordId();

To get the smart pointer to the registered application 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 registered application object in the read mode
OdDbRegAppTableRecordPtr pRegApp1 = idRegApp1.safeOpenObject();

// Open the unerased registered application object in the write mode
OdDbRegAppTableRecordPtr pRegApp2 = itRegApp2->getRecordId().safeOpenObject(OdDb::kForWrite, false);

// Open the erased registered application object in the notify mode
OdDbRegAppTableRecordPtr pRegApp3 = itRegApp3->getRecordId().safeOpenObject(OdDb::kForNotify, true);

Examples of iterating

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


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

for(itRegApp1->start(false) ; !itRegApp1->done() ; itRegApp1->step(false))
{
  pRegApp1 = itRegApp1->getRecord();
  odPrintConsoleString(L"\n[%s] RegApp: \"%s\"", pRegApp1->handle().ascii().c_str(), pRegApp1->getName().c_str());
}

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


odPrintConsoleString(L"\nThe list of registered applications:");

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