Specific Multi-Line Properties

The multi-line object uses a multi-line style, scale factor, line justification, start and end caps suppression, normal, and closed status properties to define the geometry to be drawn. In the following examples, the pMLine variable stores a pointer to the multi-line object.

Multi-line Style

The property defines the multi-line style that influences the number of parallel lines and their appearance. The property stores the ID of the multi-style object which stores the multi-line settings to be drawn and with which the multi-line entity is associated. The multi-line style property is associated with the "Standard" by default (default multi-line style is defined by CMLSTYLE).

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


OdDbObjectId idStyle = pMLine->style();

if(!idStyle.isNull())
{
  OdDbMlineStylePtr pStyle = idStyle.safeOpenObject();

  OdConsoleString(L"\nMulti-line style = %x - \"%s\"", idStyle.getHandle().ascii().c_str(), 
                                                            pStyle->getName().c_str());
}

To set the multi-line style, use the setStyle() method which requires the ID of the multi-line style object as an OdDbObjectId instance and does not return a value. The specified object ID must not be OdDb::kNull. To get the multi-line style ID, use the getMLStyleDictionaryId() method of the database object to obtain the ID of the dictionary object storing multi-line styles, and then use the getAt() method to obtain the ID of the multi-line style object. For example:


OdDbDictionaryPtr pMLStyles = pText->database()->getMLStyleDictionaryId(true).safeOpenObject();

OdDbObjectId idStyle = pMLStyles->getAt(L"MyStyle");

if(!idStyle.isNull()) pMLine->setStyle( idStyle );

Note: The CMLSTYLE system variable stores the object ID associated with the multi-line style object that is assigned to new multi-line entities by default.

Justification

The property defines the alignment of lines relative to the coordinates of the multi-line as a value of the Mline::MlineJustification enumerator that can take the following values:

kTop (=0) — The line with the most positive offset out of the parallel lines coincides with definition points.
kZero (=1) — A zero offset coincides with definition points.
kBottom (=2) — The line with the most negative offset out of the parallel lines coincides with definition points.

The justification is 1 (kZero) by default (default justification is defined by CMLJUST).

Lines with a positive offset are drawn to the left of the zero line in the direction from start point to end point. Lines with a negative offset are drawn to the right of the zero line in the direction from start point to end point.

To get the justification, use the justification() method which does not have arguments and returns the MlineJustification value. For example:


switch( pMLine->justification() )
{
  case Mline::kTop:
       OdConsoleString(L"\Justification = kTop");
       break;
  case Mline::kZero:
       OdConsoleString(L"\Justification = kZero");
       break;
  case Mline::kBottom:
       OdConsoleString(L"\Justification = kBottom");
       break;
}

To set the justification, use the setJustification() method which requires an integer value as an argument and does not return a value. For example:


// Set to kTop
pMLine->setJustification( Mline::kTop );

// Set to kZero
pMLine->setJustification( Mline::kZero );

// Set to kBottom
pMLine->setJustification( Mline::kBottom );

Note: The CMLJUST system variable stores the default justification for a new multi-line entity.

Scale Factor

The property defines the factor which scales the offsets between lines in the segments of a multi-line. If the scale factor is positive, the multi-line has the offset order defined in its multi-line style. If the scale factor is negative, the multi-line flips the offset order, opposite to the order defined in its multi-line style. If the scale factor is zero, the multi-line collapses into a single line.

If the scale factor is greater than 1.0, the multi-line increases all offsets between lines relative to the offsets defined in its multi-line style that makes a multi-line wider. If the scale factor is less than 1.0, the multi-line decreases all offsets between lines relative to the offsets defined in its multi-line style that makes a multi-line narrower. If the scale factor equals 1.0, the multi-line is drawn according to its multi-line style definition. The scale factor is 1.0 by default (default factor is defined by CMLSCALE).

To get the scale factor, use the scale() method which does not have arguments and returns the scale factor as a Double value. For example:


OdConsoleString(L"\nScale factor = %g", pMLine->scale());

To set the scale factor, use the setScale() method which requires a Double value as an argument and does not return a value. For example:


// Make the multi-line narrower
pMLine->setScale(0.5);

// Make the multi-line wider
pMLine->setScale(2.5);

// Flip the multi-line and make twice wider
pMLine->setScale(-2.0);

// Make the multi-line as in multi-line style
pMLine->setScale(1.0);

Note: The CMLSCALE system variable stores the default scale factor for new multi-line entities.

Start caps suppression

The property defines whether the multi-line start cap is suppressed as a Boolean value, that is, the first segment does not have a cap even if the associated multi-line style has start caps. If the value is True, the start cap is not drawn on the multi-line. If the value is False, the start cap is drawn only if it is defined in the multi-line style. The initial value is False by default.

To check the start caps suppression, use the supressStartCaps() method which does not have arguments and returns the status as a Boolean value. For example:


OdConsoleString(L"\nStart caps suppression is %s", ((pMLine->supressStartCaps()) ? L"ON" : L"OFF"));

To switch the start caps suppression, use the setSupressStartCaps() method which requires a Boolean value and does not return a value. For example:


// Multi-line does not have the start caps
pMLine->setSupressStartCaps(true);

// Multi-line has the start caps
pMLine->setSupressStartCaps(false);

End caps suppression

The property defines whether the multi-line end cap is suppressed as a Boolean value, that is, the last segment does not have a cap even if the associated multi-line style has end caps. If the value is True, the end cap is not drawn on the multi-line. If the value is False, the end cap is drawn only if it is defined in the multi-line style. The initial value is False by default.

To check the end caps suppression, use the supressEndCaps() method which does not have arguments and returns the status as a Boolean value. For example:


OdConsoleString(L"\nEnd caps suppression is %s", ((pMLine->supressEndCaps()) ? L"ON" : L"OFF"));

To switch the end caps suppression, use the setSupressEndCaps() method which requires a Boolean value and does not return a value. For example:


// Multi-line does not have the end caps
pMLine->setSupressEndCaps(true);

// Multi-line has the end caps
pMLine->setSupressEndCaps(false);

Closed Status

The property defines whether the multi-line is closed as a Boolean value, that is, the last segment connects with the first segment. If the value is True, the multi-line is closed. If the value is False, the multi-line is opened. The initial value is False (opened) by default.

To check the closed status, use the closedMline() method which does not have arguments and returns the status as a Boolean value. For example:


OdConsoleString(L"\nMulti-line is %s", ((pMLine->closedMline()) ? L"closed" : L"opened"));

To switch the closed status, use the setClosedMline() method which requires a Boolean value and does not return a value. For example:


// Make the closed multi-line
pMLine->setClosedMline(true);

// Make the closed multi-line
pMLine->setClosedMline(false);

Note: When a multi-line is closed, the start and end caps are suppressed.

Normal

The property defines the normal to the plane in which the multi-line is placed. The normal defines the orientation of the multi-line in world space. The normal has the coordinates (0,0,1) by default.

To get the normal, use the normal() method which does not have arguments and returns the three-dimensional unit vector as an instance of the OdGeVector3d type. For example:


OdGeVector3d normal = pMLine->normal();
OdConsoleString(L"\nNormal = (%g,%g,%g)", normal.x, normal.y, normal.z);

To set the normal, use the setNormal() method which requires the three-dimensional vector as an argument of the OdGeVector3d type and does not return a value. For example:


OdGeVector3d vector(0.303, 0.303, 0.707);
pMLine->setNormal(vector);

The setNormal() method automatically converts the specified coordinates to a unit vector. For example:


pMLine->setNormal( OdGeVector3d(2.5, 1.2, 3.4) );
OdGeVector3d result = pMLine->normal();
OdConsoleString(L"\n(%g, %g, %g)", result.x, result.y, result.z);
// (0.569803, 0.273505, 0.774932)

Plane

A multi-line is a planar entity. The planarity is kPlanar. The plane is oriented to (0⋅X + 0⋅Y + 1⋅Z + 0) by default.

To get the multi-line plane, use the getPlane() method which requires a reference to a variable of the OdGePlane type in which the plane instance must be saved as the first argument, a reference to a variable of the OdDb::Planarity type in which the plane type must be saved as the second argument, and returns the plane properties through arguments and the resulting code. For example:


OdGePlane plane;
double a, b, c, d;
OdDb::Planarity planarity;

OdResult eRes = pMLine->getPlane(plane, planarity);

if(eRes == eOk && planarity != OdDb::kNonPlanar)
{
  plane.getCoefficients(a, b, c, d);
  OdConsoleString(L"Multi-line plane is (%g * X + %g * Y + %g * Z + %g)", a, b, c, d);
}

Note: The isPlanar() method returns True for a multi-line entity.