Iterating through Text Styles

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

In the examples below, the pTextStyles variable stores a pointer to the text style 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 text style table object. The NewIterator() method creates the instance of the iterator, sets the new iterator to the first unerased text style record object in the text style table, and returns the typified smart pointer to it. For example:


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

// Create a new iterator in the position of the first erased or unerased text style
OdDbSymbolTableIteratorPtr itTextStyle3 = pTextStyles->newIterator(true, false);

The created iterator can be multiple used for traversing through text styles from the beginning to the end or from the end to the beginning of the text style's table.

Placing an iterator in the start position

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


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

// Set the iterator to the last unerased text style
itTextStyle2->start(false, true);

// Set the iterator to the first erased or unerased text style
itTextStyle3->start(true, false);

Moving an iterator

To move the iterator through text styles, use the step() method to traverse it to the beginning or end of the text style table. The step() method moves the iterator to the next unerased text style record object by default. For example:


itTextStyle1->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 text style record object or False when the iterator moves backward to the previous text style record object. The second argument specifies the erase status as a Boolean value which is True when the iterator skips the erased text style record objects or False when the iterator processes existing text style record objects of any status. Both arguments are optional and are set to True by default. For example:


// Move the iterator forward to the next unerased text style
// itTextStyle1->step(true, true);   or   itTextStyle1->step();

// Move the iterator backward to the previous unerased text style
itTextStyle2->step(false, true);

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

Checking an iterator

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


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

Getting a text style using the iterator

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


OdDbTextStyleTableRecordPtr pTextStyle1 = itTextStyle1->getRecord();

The getRecord() method has two optional arguments. The first argument specifies the mode for opening the text style 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 the erased text style record object or False when the iterator must open the unerased text style record object. The first argument is OdDb::kForRead by default; the second argument is False by default. For example:


// Open the unerased text style object in the read mode
// pTextStyle1 = itTextStyle1->getRecord(OdDb::kForRead, false);   or   pTextStyle1 = itTextStyle1->getRecord();

// Open the unerased text style object in the write mode
OdDbTextStyleTableRecordPtr pTextStyle2 = itTextStyle2->getRecord(OdDb::kForWrite, false);

// Open the erased text style object in the notify mode
OdDbTextStyleTableRecordPtr pTextStyle3 = itTextStyle3->getRecord(OdDb::kForNotify, true);

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


OdDbObjectId idTextStyle1 = itTextStyle1->getRecordId();

To get the smart pointer to the text style 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 text style object in the read mode
OdDbTextStyleTableRecordPtr pTextStyle1 = idTextStyle1.safeOpenObject();

// Open the unerased text style object in the write mode
OdDbTextStyleTableRecordPtr pTextStyle2 = itTextStyle2->getRecordId().safeOpenObject(OdDb::kForWrite, false);

// Open the erased text style object in the notify mode
OdDbTextStyleTableRecordPtr pTextStyle3 = itTextStyle3->getRecordId().safeOpenObject(OdDb::kForNotify, true);

Examples of iterating

The following example demonstrates iterating through unerased text styles from the beginning to the end of the text style table for printing:


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

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

The following example demonstrates iterating through unerased text styles from the end to the beginning of the text style table for modifying properties:


for(itTextStyle2->start(false, true) ; !itTextStyle2->done() ; itTextStyle2->step(false, true))
{
  pTextStyle2 = itTextStyle2->getRecord(OdDb::kForWrite);
  pTextStyle2->setTextSize(2.0);
  pTextStyle2->setIsBackwards(true);
  pTextStyle->setObliquingAngle(0.101);
}

The following example demonstrates iterating through text styles of the unerased or erased status from the beginning to the end of the text style table: