A dictionary object has methods for adding, naming, and removing of objects. A dictionary object does not create objects or delete objects.

To create a new object, declare a smart pointer to the object and use the pseudo-constructor of the object. The pseudo-constructor creates a new dynamic instance of the object and returns the smart pointer to it. For example, to create an instance of the color object:

OdDbColorPtr pObject = OdDbColor::createObject();

To delete an existing object, get a pointer to it, open the object in write mode, call the erase() method of it, and pass to it a True value as an argument. The erase() method deletes the object permanently. For example:

pObject->erase(true);

In the following examples, the pDict variable stores a pointer to the dictionary object.

Getting the number of objects

To get the number of objects in the dictionary, use the numEntries() method which does not have arguments and returns the number of items as an integer value. When an object is added, the number is increased. When an object is removed, the number is decreased. For example:

OdUInt32 count = pDict->numEntries();
odPrintConsoleString(L"\nThe dictionary contains %d objects", count);

Adding an object

To add an existing object of the database in the dictionary and associate it with a specified name, use the setAt() method which requires two arguments — the name of the object as the first argument of the OdString type and a pointer to the created object as the second argument of the OdDbObject type or cast type — and returns the OdDbObjectId instance associated with the added object. The dictionary sets the Owner ID property of the added object to its own Object ID. The object must be created before adding it in the dictionary using own pseudo-constructor. If the specified name already exists in the dictionary, the setAt() method overwrites the object associated with this name in the dictionary. If the object is not added, the setAt() method returns OdDb::kNull. For example:

OdDbColorPtr pObjectA = OdDbColor::createObject();
OdDbObjectId idObjectA = pDict->setAt(L"key_A", pObjectA);

OdDbColorPtr pObjectB = OdDbColor::createObject();
OdDbObjectId idObjectB = pDict->setAt(L"key_B", pObjectB);

odPrintConsoleString(L"\nThe dictionary contains %d objects", pDict->numEntries());

The setAt() method decreases the reference counter of the existing instance and increases the reference counter of the new associated instance.

Renaming an object

To change the name of an existing object, use the setName() method which requires two arguments — the current name of an object as a non-empty OdString value and the new 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 name; the second argument must specify the non-existing name. If the new name already exists in the dictionary, the setName() method ignores the renaming. For example:

pDict->setName(L"key_B", L"key_X");

Generating a name

To generate a name that can be used as a dictionary key, use the suggestName() method. This method requires a reference to the OdString variable containing a valid file path as the first required argument and the maximum length of the generated name as the second optional argument (Integer type). The suggestName() method generates a unique non-empty string from the specified path which is as close to the file name as possible. For example:

OdString sKey = pDict->suggestName(L"C:\CAD\Test\Object\colors.dwg");
pDict->setName(L"key_A", sKey);

Removing an object

To remove an object from the dictionary, use the remove() method which checks whether the object or name exists in the dictionary, removes the object from the dictionary, erases the keyword (name), but does not delete the removed object. This method has two implementations.

The first implementation of the remove() method requires the name as an argument of the OdString type and returns the OdDbObjectId instance associated with the removed object if the object with the specified name exits in the dictionary or returns OdDb::kNull if the name is not found. For example:

OdDbObjectId idObjA = pDict->remove(L"key_A");

The second implementation of the remove() method requires the ID of an existing object as an argument of the OdDbObjectId type and does not return a value. If the object ID is not found, the method ignores the removal. For example:

pDict->remove(idObjectB);

The removed object continues existing outside of the dictionary. To delete the object, open the removed object in write mode, call its erase() method, and pass to it a True value as an argument.

See Also

Working with Dictionaries of Objects

Creating the Database Dictionary

Getting and Checking Objects and Names

Examples of Using the Record–Table and Dictionary Interfaces