Adding and Naming Layers

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


OdDbLayerTableRecordPtr pLayer = OdDbLayerTableRecord::createObject();

The created instance exists independently from the database. Many properties of the layer record object are invalid initially, and the layer instance does not get an ID until the layer is added in the database. The layer table object cannot manipulate the new layer without the OdDbObjectId instance associated with the created layer record object. The new layer instance gets an empty name by default. The layer table object cannot identify a layer without a name. Therefore, after creation, the program must assign a name for the new layer, and then the program must add it in the layer table of the database.

The layer 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 database contains two predefined layers with fixed names: "0" and "Defpoints" and two layers that do not exist initially but have reserved, fixed names: "*ADSK_CONSTRAINTS" and "*ADSK_SYSTEM_LIGHTS". The layer record object has the getName() method for getting the name and the setName() method for setting the name.

To get the name, use the getName() method of the layer record object; it does not have arguments and returns the layer name as an OdString value. For example:


OdString sName = pLayer->getName();
odPrintConsoleString(L"\nLayer has the name: %ls", sName.c_str());

To set the name, use the setName() method of the layer record object; it requires the name as a nonempty OdString value and does not return a value. For example:


pLayer->setName("NewLayerX");

If the layer name contains inadmissible letters, the setName() method generates the exception: «37 - Invalid Symbol Table name». If the layer name is an empty string, the setName() method generates the exception: «106 - Empty Record name».

To add a layer in the layer table, use the add() method of the layer table object which requires one argument — the pointer to the layer instance to be added — and returns the OdDbObjectId instance associated with the added layer record object. In the examples below, the pLayers variable stores a pointer to the layer table object. For example:


OdDbObjectId idLayer = pLayers->add(pLayer);

If the layer table already contains a layer with a name that coincides with the new name, the add() and setName() methods generate the exception: «104 - Duplicate Record name object [10]». The exception message contains a handle of the duplicate layer in the square brackets. To check whether the layer table contains a layer with the specified name, use the has() method of the layer table object.

To catch exceptions, use the try … catch statement when the program adds the layer record object in the table. The following example demonstrates the procedure:


void NewLayer(OdString sLayerName, OdDbLayerTablePtr pLayers)
{
  if(sLayerName.isEmpty())

    odPrintConsoleString(L"\nThe layer name is undefined\n");

  else if(sLayerName.findOneOf("<>/\\\":;?,|=`") != -1)

    odPrintConsoleString(L"\nThe layer name contains inadmissible letters\n");

  else if(pLayers->has(sLayerName))

    odPrintConsoleString(L"\nThe layer with name \"%s\" already exists\n", sLayerName.c_str());

  else
  {
    OdDbLayerTableRecordPtr pLayer = OdDbLayerTableRecord::createObject();

    try {
      pLayer->setName(sLayerName);
      pLayers->add(pLayer);
    }
    catch(OdError& e)
    {
      odPrintConsoleString(L"\nError: %d - %ls\n", e.code(), e.description());
      pLayer->erase();
    }
  }
}

See Also