Manipulating Multi-Line Styles in the Dictionary

The database stores multi-line styles in the multi-line style dictionary, which can be obtained using the getMLStyleDictionaryId() method. A program can create a new multi-line style, add it in the dictionary, rename any multi-line style, get a multi-line style, check whether the multi-line style exists in the dictionary, and remove and delete an existing multi-line style. In the following examples, the pMLStyles variable stores a pointer to the multi-line style dictionary which must be opened in write mode. For example:


OdDbDictionaryPtr pMLStyles = pDb->getMLStyleDictionaryId(true).safeOpenObject(OdDb::kForWrite);

Creating a multi-line style

To create a new multi-line style, declare a variable of the OdDbMlineStylePtr type and use the static pseudo-constructor, which creates a new dynamic instance of the multi-line style object and returns the smart pointer to it. For example:


OdDbMlineStylePtr pMLStyle = OdDbMlineStyle::createObject();

Naming a multi-line style

Each multi-line style object has two names: external and internal. The internal name is a non-empty string that can be up to 32 characters long (length is defined by MSTYLE_NAME_LENGTH), can contain letters, digits, blank spaces, underscores, and some special characters, but cannot contain inadmissible letters (see Naming objects). The external name is the keyword (key) that identifies the multi-line style object in the dictionary and must be unique. The multi-line style object does not store the key itself and does not have a method for getting, setting, or changing its own key. The program must use the getAt() and setAt() methods of the dictionary object for working with keys. The multi-line style object has the name() method for getting the internal name and the setName() method for setting the internal name. The external name must coincide with the internal name, otherwise errors occur. For example:


dPrintConsoleString(L"\nExternal name = \"%s\"", pMLStyles->nameAt(pMLStyle->objectId()));
dPrintConsoleString(L"\nInternal name = \"%s\"", pMLStyle->name());

Adding a multi-line style

The created instance exists independently from the database. After creation, the program must assign a unique name for the new multi-line style object using the setName() method of the multi-line style object, add it in the dictionary using the setAt() method, and pass to these methods the same unique name. The setAt() method returns the Object ID associated with the added object. For example:


OdDbObjectId idMLStyle;
try {
  pMLStyle->setName(L"myStyle");
  idMLStyle = pMLStyles->setAt(L"myStyle", pMLStyle);
}
catch(OdError& e) odPrintConsoleString(L"\nError: %d - %s\n", e.code(), e.description().c_str());

Renaming a multi-line style

The program must change the external name and internal name together. If these name are different, errors occur. To change the internal name, use the setName() method of the multi-line style object which requires a new non-empty name as an argument of the OdString type. To change the external name, that is, a key in a dictionary, use the setName() method of the dictionary object which requires the current external name as the first argument and new external name as the second argument, and returns True if the name is changed successfully or False if the name is not changed. The new external name must coincide with the internal name. The first argument must specify the existing name; the second argument must specify the non-existing name. If the new external name already exists in the dictionary, the setName() method ignores the renaming. For example:


try {
   pMLStyle->setName(L"Style1");     
   pMLStyles->setName(L"myStyle", L"Style1");
}
catch(OdError& e) odPrintConsoleString(L"\nError: %d - %s\n", e.code(), e.description().c_str());

Getting a multi-line style

To get an existing multi-line style object, use the getAt() method of the dictionary object in the first implementation; it requires two arguments — the external name as a non-empty string and open mode as an integer value (kForRead, kForWrite, or kForNotify) — and returns the smart pointer to the multi-line style object if it exists in the dictionary, or it returns NULL if the external name is not found or the object cannot be opened in the specified mode. For example:


OdDbMlineStylePtr pMLStyle1 =  pMLStyles->getAt(L"Style1", OdDb::kForRead);

odPrintConsoleString(L"\nElements(Style1) = %d", pMLStyle1->numElements());

Checking a multi-line style

To check whether the multi-line style exists in the dictionary, use the has() method of the dictionary object in the first implementation; it requires the external name as a non-empty string argument and returns True if the multi-line style object exists in the dictionary or False if the multi-line style name is not found. For example:


odPrintConsoleString(L"\nStyle1 %s the dictionary", ((pMLStyles->has(L"Style1")) ? "exists in" : "is absent from"));

Getting and checking a multi-line style ID

To get an ID of the multi-line style object, use the getAt() method in the first implementation; it requires an external name as a non-empty string argument and returns the OdDbObjectId instance associated with the multi-line style object if this object exists in the dictionary, or it returns OdDb::kNull if the name is not found. For example:


OdDbObjectId idMLStyle1 = pMLStyles->getAt(L"Style1");

To check whether the multi-line style ID exists in the dictionary, use the has() method in the second implementation; it requires an existing ID as an argument and returns True if the multi-line style object exists in the dictionary or False if the ID is not found. For example:


odPrintConsoleString(L"\nStyle1 %s the dictionary", ((pMLStyles->has(idMLStyle1)) ? "exists in" : "is absent from"));

Copying a multi-line style

To copy the properties and elements from one multi-line style object to another multi-line style object, use the set() method which requires a reference to the existing multi-line style whose properties and elements must be be copied and replaces all properties and elements of this multi-line style object. The set() method also copies the internal name from the specified multi-line style, so that the multi-line style object has in result an invalid situation, and therefore, set the internal name to the external name of the multi-line style after copying. For example:


OdDbMlineStylePtr pMLStyle1 =  pMLStyles->getAt(L"Style1", OdDb::kForRead);
OdDbMlineStylePtr pMLStyle2 =  pMLStyles->getAt(L"Style2", OdDb::kForWrite);

pMLStyle2->set( *(pMLStyle1.get()) );
pMLStyle2->setName(L"Style2");

Listing all multi-line styles

To display a list of all multi-line styles of a dictionary, use an iterator for traversing through multi-line style objects. To create the iterator, use the newIterator() method of the dictionary object. To move the iterator, use the next() method of the iterator. To check whether the traverse is completed, use the done() method of the iterator. For example:


OdDbDictionaryIteratorPtr itMLStyle = pMLStyles->newIterator();

odPrintConsoleString(L"\nList of multi-line styles");
while(!itMLStyle->done())
{
  odPrintConsoleString(L"\n%s-\"%s\"-%s", itMLStyle->objectId().getHandle().ascii(), itMLStyle->name().c_str());
  itMLStyle->next();
}

Removing a multi-line style

To remove a multi-line style object from the dictionary, use the remove() method of the dictionary object that checks whether the multi-line style object exists in the dictionary, removes the multi-line style object from the dictionary, erases the external multi-line style name, but does not delete the removed multi-line style object. The removed multi-line style object continues existing outside of the multi-line style dictionary and stores the internal multi-line style name. In the first implementation, this method requires the external name as an argument and returns the ID associated with the removed multi-line style object or OdDb::kNull if the name is not found. In the second implementation, this method requires the Object ID as an argument and does not return a value. For example:


// Remove the multi-line style object using the name
OdDbObjectId idObject = pMLStyles->remove(L"Style1");

// Remove the multi-line style object using the ID
pScales->remove(idMLStyle1);

Deleting a multi-line style

To delete the removed multi-line style object, open it in write mode, call its erase() method, and pass it a True value as an argument. The erase() method returns an error code if the multi-line style object is not deleted or zero if the multi-line style object is deleted successfully. For example:


OdDbObjectPtr pObject = idObject.safeOpenObject(OdDb::kForWrite);

OdResult result = pObject->erase(true);

if(result) 
  odPrintConsoleString(L"\nError: %d - %s", result, idObject.database()->appServices()->getErrorDescription(result));