Shapes are stored in .shx files. Each shape in a .shx file has a definition which describes its geometry as a sequence of linear and circular segments that defines the shape's appearance. The definition encodes these segments in a binary format using relative coordinates for each shape. A shape is drawn using a displacement method in the object coordinate system for each shape.

The binary format associates each shape definition with an 8-bit or 16-bit integer value which uniquely identifies the shape in the .shx file and is the shape code (or shape number). This number is similar to the letter code for text. Additionally, each shape can be associated with a unique string value which is the shape name. This name is used as an alternative identifier of the shape in the .shx file for finding. Thus, the .shx file defines the set of elements <definition, code, name> for stored shapes, and the program either can use a code (number), or a name for identifying a shape.

The set of shapes from a .shx file is not immediately available. To access the shapes, the program must create a text style record object and then associate it with the .shx file that contains the shapes to be used. The shape status of this text style must be set to True in order to be interpreted as a set of shapes. To plot a shape, the shape entity must be associated with a text style record object which must be associated with the corresponding .shx file. Only then, the program can assign shape codes for shape entities. Each shape entity has the TextStyle property to associate it with a text style.

If a shape entity is not associated with a text style or a text style is not associated with an .shx file, the shape codes and shape names are ignored and the geometry is not drawn. The shape entity exists in the database and stores its code, but it has no appearance.

A shape object uses the text style, shape code, and shape name properties to identify the shape appearance in a drawing. In the following examples, the pShape variable stores a pointer to the shape object.

Shape Code

The property defines the code (number) of a shape which must correspond to one of the numbers declared in the associated .shx file. A zero value determines that the shape appearance is identified by name. The code is zero by default.

To get the shape code, use the shapeNumber() method which does not have arguments and returns the code as an Integer value. For example:

odPrintConsoleString(L"\nShape code = %d", pShape->shapeNumber());

To set the shape code, use the setShapeNumber() method which requires an Integer value corresponding to the shape code (number) of the associated .shx file as an argument and does not return a value. For example:

pShape->setShapeNumber(132);

Note: The setShapeNumber() method sets the shape name to an empty string value when the specified code is not found in the .shx file. If the specified code exists, this method sets the shape name associated with the code.

Shape Name

The property defines the name of a shape which must correspond to one of the names declared in the associated .shx file. Shape names must be uppercase to be recognized. Names with lowercase characters are ignored. An empty string determines that the shape appearance is identified by code (number). The name is an empty string by default.

To get the shape name, use the name() method which does not have arguments and returns the shape name as a String value. For example:

odPrintConsoleString(L"\nShape name = \"%s\"", pShape->name());

To set the shape name, use the setName() method which requires a non-empty uppercase String value corresponding to the shape name of the associated .shx file as an argument and does not return a value. For example:

pShape->setName(L"CE");

Note: The setName() method sets the shape code to a zero value when the specified name is not found in the .shx file. If the specified name exists, this method sets the shape code associated with the name.

Text Style

The property defines the text style associated with the .shx file that stores the definitions used to define the appearances of shapes. The property stores the ID of the text style record object with which the shape entity is associated. If the shape code is zero and the shape name is an empty string, the text style is not used. If either the shape code is non-zero or the shape name is non-empty, the text style property is applicable and must store the ID of an existing text style record object. If this property stores OdDb::kNull, the shape entity does not have an appearance. The text style property is OdDb::kNull by default.

To get the text style, use the styleId() method which does not have arguments and returns the OdDbObjectId instance associated with the text style record object. Then, use the safeOpenObject() method to obtain a smart pointer to this text style. For example:

OdDbObjectId idTextStyle = pShape->styleId();

if(!idTextStyle.isNull())
{
  OdDbTextStyleTableRecordPtr pTextStyle = idTextStyle.safeOpenObject();

  odPrintConsoleString(L"\nText style = %x - \"%s\"", idTextStyle.getHandle().ascii().c_str(), 
                                                      pTextStyle->getName().c_str());
}

To set the text style, use the setStyleId() method which requires the ID of the text style record object as the OdDbObjectId instance and does not return a value. The specified object ID must not be OdDb::kNull. To get the ID of a text style, use the getTextStyleTableId() method of the database object to obtain the ID of the text style table object and then its getAt() method to obtain the ID of the text style record object. For example:

OdDbTextStyleTablePtr pTextStyles = pShape->database()->getTextStyleTableId().safeOpenObject();

OdDbObjectId idTextStyle = pTextStyles->getAt(L"MyShapeStyle");

if(!idTextStyle.isNull()) pShape->setStyleId( idTextStyle );

To associate the text style with a .shx file, get the text style table object using the getTextStyleTableId() method and safeOpenObject() method for write mode and save the returned smart pointer to it in the declared variable. Next, create the text style record object using its static pseudo-constructor — createObject() method — and save the returned smart pointer to it in the declared variable. Next, assign the name for the new text style using the setName() method, set its shape status to True using the setIsShapeFile() method, and specify the .shx file name without a path. Next, add the text style record object to the text style table object using the add() method. Afterwards, the ID of the new text style can be set for the shape entity using the setStyleId() method. For example:

OdDbTextStyleTablePtr pTextStyles = pShape->database()->getTextStyleTableId().safeOpenObject(OdDb::kForWrite);

OdDbTextStyleTableRecordPtr pTextStyle = OdDbTextStyleTableRecord::createObject();

try {
  pTextStyle->setName(L"MyShapeStyle");     
  pTextStyle->setIsShapeFile(true);
  pTextStyle->setFileName(L"my.shx");

  pTextStyles->add(pTextStyle);
  
  pShape->setStyleId( pTextStyle->objectId() );
}
catch(OdError& e) 
{
  odPrintConsoleString(L"\nError: %d -- %s\n", e.code(), e.description());
}

Note: If the program changes the text style of a shape entity or its shape code (or name) becomes associated with another .shx file, the appearance of the shape changes.

See Also

Working with Shapes

Specific Shape Properties

Example of Working with the Shape Object