Working with the Linetype Pattern

The pattern of a linetype consists of dashes that are repeated in the direction of the plotted line. A dash is a segment of a straight line that has length and visibility. Each dash begins from the end of the previous dash in the direction of the plotted line. The sequence of dash lengths defines the characteristics of a linetype. If the pattern does not contain dashes, the linetype is a solid line. A pattern cannot contain only one dash; if a pattern contains dashes, it must have at least two. The linetype repeats a sequence of dashes when an entity is drawn. A pattern can define up to 12 dash-length specifications per linetype.

A dash can include arbitrary text or shapes, in which case the dash length must be sufficient to place the text or shape inside it. The text length or shape size must be less than the length of the dash in which it is included. If the included text or shape is longer than the dash, it will plot over the next dash. As a rule, a dash with an inclusion has a negative length to plot inside the text or shape only.

Each inclusion is associated with a text style that defines the parameters of the text or shape. In additional, the inclusion can be rotated by an angle, scaled by a factor, shifted by an offset inside a dash, and oriented relative to the current UCS or line. In the examples, the pLinetype variable stores a pointer to the linetype record object; the idx variable is used for counting dashes.


OdInt16 idx, sig;

Number of dashes

The property defines the number of dashes that form the linetype pattern. If the number of dashes is set to zero, the linetype defines a solid line. The linetype object automatically resizes the sequence of dashes, adding new dashes or deleting existing dashes when the number of dashes increases or decreases. New dashes are initialized with default parameters. If the linetype pattern contains dashes, it must contain at least two of them. Dashes are numerated at zero. The number of dashes is zero by default.

To get the number of dashes, use the numDashes() method that does not have arguments and returns the number of dashes as a positive Integer value. For example:


odPrintConsoleString(L"\nLinetype consists of %d dashes", pLinetype->numDashes());

To set the number of dashes, use the setNumDashes() method that requires one argument — the number of dashes as a positive Integer value — and does not return a value. A zero value creates a solid line. For example:


pLinetype->setNumDashes(8);

Note: The maximum number of dashes in a linetype is 127 (at run-time and in .dwg files). Loading from .dxf files restricts the number of dashes to 12.

Dash length

The property defines the length of a dash inside the linetype pattern. If a length value is positive, the dash is drawn. If a length value is negative, the dash is not drawn (appears as a space). If the length value is zero, a point is drawn (appears as a dot). The combination of positive and negative values of dash lengths defines broken lines. The length is zero by default.

To get the dash length, use the dashLengthAt() method that requires one argument — the index of a dash as an Integer value — and returns the length as a Double value. For example:


for(idx = pLinetype->numDashes()-1 ; idx >= 0 ; idx--)
  odPrintConsoleString(L"\nDash (%d) has length = %f", idx, pLinetype->dashLengthAt(idx));

To set the dash length, use the setDashLengthAt() method that requires two arguments — the index of a dash as an Integer value and the length value as a Double value — and does not return a value. For example, to specify the dashed line:


for(idx = pLinetype->numDashes()-1, sig = +1 ; idx >= 0 ; idx--, sig *= (-1))
  pLinetype->setDashLengthAt(idx, sig * 0.5);

Text inclusions

The property defines a non-empty string that is included in a dash inside the linetype pattern. When the text is an empty string, the dash does not contain text as an inclusion. Applying a text inclusion requires the availability of a text style that defines the appearance and parameters of the text inside a dash. The text is an empty string by default.

To get the text inclusion, use the textAt() method which requires one argument — the index of a dash as an Integer value — and returns the text as an OdString value. For example:


for(idx = pLinetype->numDashes()-1 ; idx >= 0 ; idx--)
  odPrintConsoleString(L"\nDash (%d) has text = %s", idx, pLinetype->textAt(idx).c_str());

To set text as an inclusion, use the setTextAt() method which requires two arguments — the index of a dash as an Integer value and the text value as an OdString value — and does not return a value. For example, to specify the "GAS" string for invisible dashes:


OdString sText = L"GAS";
for(idx = pLinetype->numDashes()-1 ; idx >= 0 ; idx--)
  if(pLinetype->dashLengthAt(idx) < 0)
    pLinetype->setTextAt(idx, sText);

Note: The setTextAt() method cancels usage of the shape code, which gets a zero value.

Note: Total length of all text in a linetype should be less than 256 characters.

Shape inclusions

The property defines a shape that is included in a dash inside the linetype pattern. The definition requires a shape code as a non-zero positive Integer value. When the shape code is zero, the dash does not contain a shape as an inclusion. Applying a shape inclusion requires the availability of the .shx file which must be previously loaded and the anonymous text style that defines the shape parameters. The code is zero by default.

To get the shape inclusion, use the shapeNumberAt() method which requires one argument — the index of a dash as an Integer value — and returns the number of a shape as an Integer value. For example:


for(idx = pLinetype->numDashes()-1 ; idx >= 0 ; idx--)
  odPrintConsoleString(L"\nDash (%d) has shape = %d", idx, pLinetype->shapeNumberAt(idx));

To set the shape as an inclusion, use the setShapeNumberAt() method which requires two arguments — the index of a dash as an Integer value and the shape code as an Integer value — and does not return a value. For example, to specify the code 133 for invisible dashes:


for(idx = pLinetype->numDashes()-1 ; idx >= 0 ; idx--)
  if(pLinetype->dashLengthAt(idx) < 0)
    pLinetype->setShapeNumberAt(idx, 133);

Note: The setShapeNumberAt() method cancels usage of the text inclusion.

Rotating inclusions

The property defines the rotation angle on which the inclusion is rotated inside the dash counterclockwise relative to the direction vector of the plotted linetype in the range -2PI to 2PI radians. It is an angle between the direction of the plotted linetype and the direction of the plotted text. A positive angle rotates the inclusion counterclockwise. A negative angle rotates the inclusion clockwise. A zero angle indicates that the direction of the linetype and text are the same. If an absolute angle value is greater than 2PI, it converts to 2PI. The rotation angle is zero by default.

To get the rotation angle, use the shapeRotationAt() method which requires one argument — the index of a dash as an Integer value — and returns the angle value as a Double value. For example:


for(idx = pLinetype->numDashes()-1 ; idx >= 0 ; idx--)
  odPrintConsoleString(L"\nDash (%d) has rotation = %f", idx, pLinetype->shapeRotationAt(idx));

To set the rotation angle, use the setShapeRotationAt() method which requires two arguments — the index of a dash as an Integer value and the angle value as a Double value — and does not return a value. For example, to rotate all text inclusions by 45°:


for(idx = pLinetype->numDashes()-1 ; idx >= 0 ; idx--)
  if(!pLinetype->textAt(idx).isEmpty())
    pLinetype->setShapeRotationAt(idx, 0.785);

Offsetting inclusions

The offset defines the two-dimensional displacement to the insertion point of an inclusion relative to the end of the current dash that contains the text or shape. If the x,y-displacements are simultaneously equal to zero, the inclusion is drawn from the end of the current dash, which can reduce the overlap with the next dash. The placement of the insertion point in the inclusion depends on its properties and the associated text style. The x-displacement controls the distance between an inclusion and the next dash or between an inclusion and the previous dash. The y-displacement controls the alignment of an inclusion relative to the line. The offset places and aligns an inclusion inside a dash. The offset is (0,0) by default.

To get the offset, use the shapeOffsetAt() method which requires one argument — the index of a dash as an Integer value — and returns the offset as a two-dimensional vector of the OdGeVector2d type. For example:


OdGeVector2d offset;
for(idx = pLinetype->numDashes()-1 ; idx >= 0 ; idx--)
{
  offset = pLinetype->shapeOffsetAt(idx)
  odPrintConsoleString(L"\nDash (%d) has offset = ( %f , %f )", idx, offset.x, offset.y);
}

To set the offset, use the setShapeOffsetAt() method which requires two arguments — the index of a dash as an Integer value and the offset as a two-dimensional vector — and does not return a value. For example, to offset all shapes:


OdGeVector2d offset(0.06, 0.04);
for(idx = pLinetype->numDashes()-1 ; idx >= 0 ; idx--)
  if(pLinetype->shapeNumberAt(idx) != 0)
    pLinetype->setShapeOffsetAt(idx, offset);

Scaling inclusions

The property defines the factor by which the text or shape scales. The scale factor is a positive non-zero double value that defines the size of an inclusion inside a dash. The scale factor specifies the coefficient by which the height of the associated text style is multiplied relative to the linetype scale. If the scale factor is less than 1.0, the inclusion is condensed. If the scale factor is greater than 1.0, the inclusion is expanded. If the scale factor equals 1.0, the height of the associated text style defines the inclusion size. The scale factor does not modify the (x,y)-displacements of the offset. The scale factor is zero by default.

To get the scale, use the shapeScaleAt() method which requires one argument — the index of a dash as an Integer value — and returns the scale factor as a Double value. For example:


for(idx = pLinetype->numDashes()-1 ; idx >= 0 ; idx--)
  odPrintConsoleString(L"\nDash (%d) has scale = %f", idx, pLinetype->shapeScaleAt(idx));

To set the scale, use the setShapeScaleAt() method which requires two arguments — the index of a dash as an Integer value and the scale factor as a Double value — and does not return a value. For example, to expand all dashes:


for(idx = pLinetype->numDashes()-1 ; idx >= 0 ; idx--)
  pLinetype->setShapeScaleAt(idx, 1.25);

Text style of inclusions

The property defines the text style that is associated with the text or shape inclusion of a dash and influences the appearance of the inclusion in the linetype pattern. The dash stores the ID of the text style object with which the inclusion is associated. When a dash does not have an inclusion, the text style property is not applicable. When the shape code is zero and the text string is an empty, the dash does not contain an inclusion and a text style is not used. When either the shape code is non-zero or the text string is non-empty, the text style property is applicable and must store the ID of a text style object. The text style is OdDb::kNull by default.

To get the text style, use the shapeStyleAt() method which requires one argument — the index of a dash as an Integer value — and returns the OdDbObjectId instance associated with the text style object. Then, use the safeOpenObject() method to return a smart pointer to the text style object. For example:


OdDbObjectId idTextStyle;
OdDbTextStyleTableRecordPtr pTextStyle;

for(idx = pLinetype->numDashes()-1 ; idx >= 0 ; idx--)
{
  idTextStyle = pLinetype->shapeStyleAt();
  
  pTextStyle = idTextStyle.safeOpenObject();

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

To set the text style, use the setShapeStyleAt() method which requires two arguments — the index of a dash as an Integer value and the ID of the text style object as the OdDbObjectId instance — and does not return a value. The specified object ID must not be OdDb::kNull. The database stores all text styles in a table. To get the ID of a text style, use the getTextStyleTableId() method of the database object to return the ID of the text style table and the getAt() method of the text style table object to return the ID of the text style using its name. For example:


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

OdDbObjectId idTextStyle = pTextStyles->getAt("Standard");

if(!idTextStyle.isNull())
{
  for(idx = pLinetype->numDashes()-1 ; idx >= 0 ; idx--)
    if(!pLinetype->textAt(idx).isEmpty())
      pLinetype->setShapeStyleAt(index, idTextStyle);
}

UCS orientation of inclusions

The property determines how the text or shape is oriented inside a dash. The linetype object defines the UCS orientation as a Boolean value which is True when the inclusion is oriented relative to the current coordinate system along which UCS is oriented independent from the line direction (absolute) or False when the inclusion is oriented relative to the line direction within which it is embedded (relative). The UCS orientation is False (relative) by default.

To check the UCS orientation, use the shapeIsUcsOrientedAt() method which requires one argument — the index of a dash as an Integer value — and returns the UCS flag as a Boolean value. For example:


for(idx = pLinetype->numDashes()-1 ; idx >= 0 ; idx--)
  odPrintConsoleString(L"\nDash (%d) is %s-oriented", idx, 
                       (pLinetype->shapeIsUcsOrientedAt(idx)) ? L"absolute" : L"relative");

To switch the UCS orientation, use the setShapeIsUcsOrientedAt() method which requires two arguments — the index of a dash as an Integer value and the UCS flag as a Boolean value — and does not return a value. For example, to set the UCS flag for even dashes and to clear the UCS flag for odd dashes:


for(idx = pLinetype->numDashes()-1 ; idx >= 0 ; idx--)
  pLinetype->setShapeIsUcsOrientedAt(idx, ((idx % 2) ? false : true));

Upright orientation of inclusions

The property determines how the text letters or shape forms are oriented inside an inclusion when it is relative-oriented. The linetype object defines the Upright orientation as a Boolean value which is True when the text letters or shape forms are always oriented upside and forward inside an inclusion, independent from the line direction (upright) or False when text letters or shape forms are oriented along the line direction inside an inclusion (inline). When the linetype object draws a dash in upright mode, it checks the direction of the OCS inclusion and direction of the line, and if the situation requires the text letters or shape forms to be drawn downside or backward inside of inclusions, it rotates the OCS inclusion to be upside and forward. The Upright flag is used only with relative orientation, that is, the UCS flag must be False. The Upright flag does not influence the absolute orientation, that is, the UCS flag is True. The Upright orientation is False (inline) by default.

To check the Upright orientation, use the shapeIsUprightAt() method which requires one argument — the index of a dash as an Integer value — and returns the Upright flag as a Boolean value. For example:


for(idx = pLinetype->numDashes()-1 ; idx >= 0 ; idx--)
  odPrintConsoleString(L"\nDash (%d) is %s-oriented", idx, 
                       (pLinetype->shapeIsUprightAt(idx)) ? L"upright" : L"inline");

To switch the Upright orientation, use the setShapeIsUprightAt() method which requires two arguments — the index of a dash as an Integer value and the Upright flag as a Boolean value — and does not return a value. For example, to set the Upright flag for odd dashes and to clear the Upright flag for even dashes:


for(idx = pLinetype->numDashes()-1 ; idx >= 0 ; idx--)
  pLinetype->setShapeIsUprightAt(idx, ((idx % 2) ? true : false));