Manipulating Objects of the Scale Dictionary

The database stores scales in the scale dictionary, which can be obtained using the getScaleListDictionaryId() method. The program can create a new scale, add it in the dictionary, rename any scale, get a scale of the dictionary, check whether the scale exists in the dictionary, and remove and delete an existing scale. In examples, the pDb variable stores a pointer to the database object, the pScales variable stores a pointer to the scale dictionary which must be opened in write mode. For example:


OdDbDictionaryPtr pScales = pDb->getScaleListDictionaryId(true).safeOpenObject(OdDb::kForWrite);

Creating a scale object

To create a new scale, declare a variable of the OdDbScalePtr type and use the pseudo-constructor of the scale object. This pseudo-constructor is the static method that creates a new dynamic instance of the scale object and returns the smart pointer to it. For example:


OdDbScalePtr pScale = OdDbScale::createObject();

Naming a scale object

The scale object has two names: external and internal. The external scale name is an arbitrary nonempty string that can be up to 255 characters long and can contain letters, digits, blank spaces, underscores, and some special characters, but cannot contain inadmissible letters (see Naming objects). The external scale name is the keyword (key) that identifies the scale object in the dictionary and must be unique. The scale object does not store the key itself and does not have a method for getting, setting, or changing a key. The program must use the methods of the scale dictionary for working with scale keys.

The internal scale name is an arbitrary string that can contain any letters, including inadmissible letters, and can be empty. The internal scale name (name) is the comment for displaying of the scale factor in a list. The scale factor is the ratio of the paper units to the drawing units which are denoted in the scale name, for example "3:8", "4ft:5in". The internal scale name does not have to be unique. The scale object stores the name itself and has the scaleName() method for getting and setScaleName() method for setting the name.

Adding a scale object

The created instance exists independently from the database. Many properties of the scale object are invalid initially, and the scale instance does not get an ID until the scale is added in the database. The database cannot identify a scale object in its own container and cannot manipulate it without a key and ID. Therefore, after creation, the program must assign a unique external scale name for the new scale object and add it in the scale dictionary of the database.

To add the scale in the dictionary, use the setAt() method and pass to it the external scale name as the first argument and a pointer to the scale instance as the second argument. The setAt() method returns the Object ID of the added scale object. For example:


try {
  OdDbObjectId idScale = pScales->setAt(L"Z0", pScale);
}
catch(OdError& e) { odPrintConsoleString(L"\nError: %d - %s\n", e.code(), e.description().c_str()); }

Renaming a scale object

To change the external scale name of an existing scale object, use the setName() method of the dictionary object which requires two arguments — the current external name as a non-empty OdString value and the new external name as a non-empty OdString value — and returns True if the name is changed successfully or False if the name is not changed. The first argument must specify the existing external scale name; the second argument must specify the non-existing external scale name. If the new external name already exists in the dictionary, the setName() method ignores the renaming. For example:


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

To change the internal scale name of an existing scale object, use the setScaleName() method of the scale object which requires one argument — the new name as a OdString value — and does not return a value. For example:


pScales->setScaleName(L"4ft:5in");

Getting a scale object

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


OdDbScalePtr pScaleSC1 =  pScales->getAt(L"SC1", OdDb::kForRead);

odPrintConsoleString(L"\nSC1 is \"%s\" = %g", pScaleSC1->scaleName(), pScaleSC1->scale());

Checking a scale object

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


odPrintConsoleString(L"\nSC1 %s in the dictionary", ((pScales->has(L"SC1")) ? "exists" : "is absent"));

Getting and checking a scale ID

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


OdDbObjectId idScaleSC1 = pScales->getAt(L"SC1");

To check whether the ID of the scale object 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 scale object exists in the dictionary or False if the ID is not found. For example:


odPrintConsoleString(L"\nSC1 %s in the dictionary", ((pScales->has(idScaleSC1)) ? "exists" : "is absent"));

Listing all scale objects

To display a list of all scales of the dictionary, use an iterator for traversing through scale 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 itScale = pScales->newIterator();

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

Removing a scale object

To remove a scale object from the dictionary, use the remove() method of the dictionary object that checks whether the scale object exists in the dictionary, removes the scale object from the dictionary, erases the external scale name, but does not delete the removed scale object. The removed scale object continues existing outside of the scale dictionary and stores the internal scale name. In the first implementation, this method requires the external scale name as an argument and returns the ID associated with the removed scale 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 scale object using the external scale name
OdDbObjectId idObject = pScales->remove(L"SC1");

// Remove the scale object using the ID
pScales->remove(idScaleSC1);

Deleting a scale object

To delete the removed scale 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 scale object is not deleted or zero if the scale 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));