Specific Single-Line Text Properties

The single-line text object uses the position, normal, thickness, height factor, width factor, oblique angle, rotation angle, text direction and text side properties to define the geometry to be drawn. In the following examples, the pSText variable stores a pointer to the single-line text object.

Content

The property defines the content of the single-line text as a string of letters. The single-line text entity does not support format codes. The content is an empty string by default.

To get the content, use the textString() method which does not have arguments and returns an instance of the OdString type. For example:


OdString sContent = pSText->textString();
odPrintConsoleString(L"\nContent = \"%s\"", sContent.c_str());

To set the content, use the setTextString() method which requires an argument of the OdString type and does not return a value. For example:


pSText->setTextString(L"Single-line text");

Position

The property defines the position in which the single-line text entity is inserted in three-dimensional world coordinates. The position coincides with the origin from which the text geometry is drawn. The position (insertion point) has the coordinates (0,0,0) by default.

To get the position, use the position() method which does not have arguments and returns the three-dimensional point as an instance of the OdGePoint3d type. For example:


OdGePoint3d position = pSText->position();
odPrintConsoleString(L"\nPosition = (%g,%g,%g)", position.x, position.y, position.z);

To set the position, use the setPosition() method which requires the three-dimensional point as an argument of the OdGePoint3d type and does not return a value. For example:


OdGePoint3d point(3.2, 1.5, 0.8);
pSText->setPosition(point);

Normal

The property defines the normal to the plane in which the single-line text is placed. The normal defines the orientation of the text plane 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 vector as an instance of the OdGeVector3d type. For example:


OdGeVector3d normal = pSText->normal();
odPrintConsoleString(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.606, 0.101, 0.303);
pSText->setNormal(vector);

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


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

Plane

Single-line text 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 text 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 = pSText->getPlane(plane, planarity);

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

Note: The isPlanar() method returns True for the single-line text entity.

Thickness

The property defines the thickness of single-line text as a Double value in drawing units. A positive value defines the thickness to be drawn along the normal direction. A negative value defines the thickness to be drawn in the opposite direction from the normal. A zero value defines a text without thickness. The thickness is zero by default.

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


odPrintConsoleString(L"\nThickness = %g", pSText->thickness());

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


pSText->setThickness(1.5);

Rotation Angle

The property defines the rotation angle in radians on which single-line text is rotated relative to the OCS X-axis around the text position in the range ±2PI radians. A positive angle is measured and rotates the text counterclockwise (to the left). A negative angle is measured and rotates the text clockwise (to the right). A zero angle indicates that the text is not rotated and is drawn in the direction of the OCS X-axis. The single-line text entity stores the rotation angle value together with its sign and does not convert to an equivalent angle. The rotation angle is zero by default.

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


odPrintConsoleString(L"\nRotation angle = %g", pSText->rotation());

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


pSText->setRotation(0.303);

Note: The setRotation() method does not convert to an equivalent angle and sets the specified value.

Oblique Angle

The property defines the oblique angle in radians on which single-line text is sloped relative to the OCS Y-axis in the range ±2PI radians. The effective angle range is ±1.4827 radians (±85 degrees). A positive angle is measured and slopes the text clockwise (to the right). A negative angle is measured and slopes the text counterclockwise (to the left). A zero angle indicates that the text is not sloped. The single-line text entity stores the oblique angle value together with its sign and does not convert to an equivalent angle. The oblique angle is zero by default.

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


odPrintConsoleString(L"\nOblique angle = %g", pSText->oblique());

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


pSText->setOblique(0.202);

Note: The setOblique() method does not convert to an equivalent angle and sets the specified value.

Height Scale Factor

The property defines the height scale factor which scales the text size. This factor influences the width and height together and is used for proportional scaling of the text boundary. If the factor value is less than 1.0, the text size decreases. If the factor value is greater than 1.0, the text size increases. If the factor value is 1.0, the text has an original size. The single-line text entity stores the specified factor value without converting it, but the effective factor value must be a positive non-zero double value. The height scale factor is 1.0 by default.

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


odPrintConsoleString(L"\nHeight scale factor = %g", pSText->height());

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


pSText->setHeight(0.8);

Width Scale Factor

The property defines the width scale factor which scales the text width when the height is constant. This factor influences only the width. If the factor value is less than 1.0, the text is condensed. If the factor value is greater than 1.0, the text is expanded. If the factor value is 1.0, the text has its original size. The single-line text entity stores the specified factor value without conversion, but the effective factor value must be a positive non-zero double value. The width scale factor is 1.0 by default.

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


odPrintConsoleString(L"\nWidth scale factor = %g", pSText->widthFactor());

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


pSText->setWidthFactor(1.5);

Text Direction (Mirror in OCS X)

The property defines whether text is drawn backward or forward from the text position, that is, it defines the OCS X-direction as a Boolean value. When the value is True, the text is backward. When the value is False, the text is forward. This property changes the X-direction in the object coordinate system of the single-line text entity taking into account the rotation and oblique angles. The initial value is False (Forward) by default.

To check the text direction, use the isMirroredInX() method which does not have arguments and returns the direction as a Boolean value. For example:


odPrintConsoleString(L"\nText is drawn %s", ((pSText->isMirroredInX()) ? L"backward" : L"forward"));

To switch the text direction, use the mirrorInX() method which requires a Boolean value and does not return a value. For example:


// Set the backward text
pSText->mirrorInX(true);

// Set the forward text
pSText->mirrorInX(false);

Text Side (Mirror in OCS Y)

The property defines whether text is drawn downside or upside relative to the baseline, that is, it defines the OCS Y-direction as a Boolean value. When the value is True, the text is downside. When the value is False, the text is upside. This property changes the Y-direction in the object coordinate system of the single-line text entity taking into account the rotation and oblique angles. The initial value is False (Upside) by default.

To check the text side, use the isMirroredInY() method which does not have arguments and returns the side as a Boolean value. For example:


odPrintConsoleString(L"\nText is drawn %s", ((pSText->isMirroredInY()) ? L"downside" : L"upside"));

To switch the text side, use the mirrorInY() method which requires a Boolean value and does not return a value. For example:


// Set the downside text
pSText->mirrorInY(true);

// Set the upside text
pSText->mirrorInY(false);

Restricted Area (Bounding Points)

The single-line text entity stores the coordinates of the rectangular area that restricts the text content. When the single-line text entity changes the content, position, normal, size, factor, or rotation, its restricted rectangular area changes coordinates. The restricted area is planar and independent from thickness.

To get the restricted area, use the getBoundingPoints() method which requires a reference to an array of three-dimensional points of the OdGePoint3d type in which this method must save the bounding points, and returns the array containing four points through the argument. For example:


OdGePoint3dArray points;

pSText->getBoundingPoints(points);

odPrintConsoleString(L"\n Text restricted area:");
odPrintConsoleString(L"\n Top-Left point = (%g,%g,%g)", points[0].x, points[0].y, points[0].z);
odPrintConsoleString(L"\n Top-Right point = (%g,%g,%g)", points[1].x, points[1].y, points[1].z);
odPrintConsoleString(L"\n Bottom-Right point = (%g,%g,%g)", points[2].x, points[2].y, points[2].z);
odPrintConsoleString(L"\n Bottom-Left point = (%g,%g,%g)", points[3].x, points[3].y, points[3].z);