Specific Arc-Aligned Text Properties

The arc-aligned text object uses the alignment, font, underline, text string, text position, text size, text direction, text style, alignment, font, offset, character spacing, character order, center, radius, start angle, and end angle properties to define the geometry to be drawn. In the following examples, the pArcText variable stores a pointer to the arc-aligned object.

Arc entity

After creating and adding the new arc-aligned text instance to the database, it must be connected with an arc entity that was created and added to the database previously. To do this, use the setArcId() method which requires the Object ID of the arc entity. In the following example, the pArc variable stores a pointer to the arc instance. For example:


pArcText->setArcId(pArc->objectId());

Properties such as center, radius, start angle, and end angle are set from the arc entity. Also these properties can be changed by using the setCenter(), setRadius(), setStartAngle() and setEndAngle() methods later. Note that changing properties of the associated arc entity also change these properties in an arc-aligned text instance automatically.

Center

The Center property defines the center of the arc-aligned text object in three-dimensional coordinates. By default the center has the same center coordinates as the arc entity.

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


OdGePoint3d center = pArcText->center();
odPrintConsoleString(L"\nArc text center = (%g,%g,%g)", center.x, center.y, center.z);

To set the center, use the setCenter() method which requires the three-dimensional point as an argument of the OdGePoint3d type and does not return a value. This method sets the WCS center of the arc-aligned text entity. For example:


OdGePoint3d point(1.5, 3.7, 2.6);
pArcText->setCenter(point);

Radius

The Radius property defines the radius of the arc-aligned text entity as a positive Double value in drawing units.

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


odPrintConsoleString(L"\nArc-Aligned Text radius = %g", pArcText->radius());

To set the radius of the arc-aligned text entity, use the setRadius() method which requires a positive Double value as an argument and does not return a value. For example:


pArcText->setRadius(3.5);

Start Angle and End Angle

The Start and End Angle properties define the angle from which, and to which, the arc-aligned text entity is drawn, both as Double values in radians. A positive angle is measured from the OCS X-axis counterclockwise. A negative angle is measured from the OCS X-axis clockwise and is automatically converted to its positive equivalent. If an angle value is more than 2PI, it is automatically converted to the range 0 to 2PI. The start and end angles are zero by default.

To get the start angle, use the startAngle() method which does not have arguments and returns the start angle of the arc-aligned text object, as a Double value. For example:


odPrintConsoleString(L"\nStart angle = %g", pArcText->startAngle());

To set the start angle of the arc-aligned text object, use the setStartAngle() method which requires a Double value as an argument and does not return a value. For example:


pArcText->setStartAngle(1.2);

To get the end angle, use the endAngle() method which does not have arguments and returns the end angle of the arc-aligned text object, as a Double value. For example:


odPrintConsoleString(L"\nEnd angle = %g", pArcText->endAngle());

To set the end angle of the arc-aligned text object, use the setEndAngle() method which requires a Double value as an argument and does not return a value. For example:


pArcText->setEndAngle(4.15);

Text Style

This property defines the text style characteristics of an arc-aligned text object. The property stores the ID of the text style record object which is associated with the arc-aligned text entity. By default, the text style property is associated with the "Standard" text style.

To get the text style, use the textStyle() 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 idStyle = pArcText->textStyle();
if(!idStyle.isNull())
{
  OdDbTextStyleTableRecordPtr pStyle = idStyle.safeOpenObject();
  odPrintConsoleString(L"\nText style = %s ", pStyle->getName().c_str());
}

To set the text style of the arc-aligned text entity, use one of the two setTextStyle() methods. The first method requires an 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 text style ID, use the getTextStyleTableId() method of the database object to obtain the ID of the text style table object, and then use the getAt() method to obtain the ID of the text style record object. For example:


OdDbTextStyleTablePtr pTextStyles = pArcText->database()->getTextStyleTableId().safeOpenObject();
OdDbObjectId idStyle = pTextStyles->getAt(L"OdaTtfStyle");
if(!idStyle.isNull()) 
	pArcText->setTextStyle( idStyle );

The second variant of the setTextStyle() method requires an OdString parameter with the name of the text style object specified and added to the database previously. For example:


pArcText->setTextStyle(L"OdaTtfStyle");

Text String

To change the text string of an arc-aligned text object, use the setTextString() method. This method requires one String parameter and does not return a value. For example:


pArcText->setTextString("Arc text");

To get the text string of an arc-aligned text entity, use textString() method which does not have input parameters and returns an OdString value. For example:


OdString textString = pArcText->textString();
odPrintConsoleString(L"\nArc Text string = %s", textString.c_str());

xScale

To change the X-scale (width) factor of the arc-aligned text entity, use the setXScale() method. It takes one Double parameter and does not return a value. For example:


pArcText->setXScale(2);

To get the X-scale factor, use xScale() method which has no input parameters and returns the text width of the arc-aligned text as a Double value. By default the width is 1. For example:


double xScale = pArcText->xScale();
odPrintConsoleString(L"\n\nxScale = %g", xScale);

Text Position

To set the text position of arc-aligned text, use the setTextPosition() method which requires the text position as an Integer value. The textPosition must be one of the following enum values:


enum OdArcTextPosition
{
	kOnConvexSide = 1,
	kOnConcaveSide = 2
}

For example:


pArcText->setTextPosition(OdArcTextPosition::kOnConcaveSide);

Text Direction

The direction of arc-aligned text can be one of two variants: inward to the center or outward from the center. Both parameters are members of the OdArcTextDirection enumeration:


enum OdArcTextDirection
{
	kOutwardFromCenter = 1,
	kInwardToTheCenter = 2
}

To get the direction of arc-aligned text, use the textDirection() method which does not have input parameters and returns one of the following constants: kOutwardFromCenter = 1 or kInwardToTheCenter = 2. For example:


int direction = pArcText->textDirection();
if(direction == OdArcTextDirection::kInwardToTheCenter)
	odPrintConsoleString(L"\n\nText direction is to the center");
else
	odPrintConsoleString(L"\nText direction is from center");

To set the direction of arc-aligned text, use setTextDirection() method which does not return a value and has one input parameter. For example:


pArcText->setTextDirection(OdArcTextDirection:: kOutwardFromCenter);

If the direction is kInwardToTheCenter, the arc-aligned text is changed as in the figure below:

Character Order

To check the character order of the arc-aligned text entity, use the isReversedCharOrder() method. It has no input parameter and returns true if the character order is reversed. For example:


if(pArcText->isReversedCharOrder())
	odPrintConsoleString(L"\nArc Text has reverse char order");

To set the reverse character order mode of the arc-aligned text entity, use the reversedCharOrder() method with a true value for the input parameter. This method does not return a value. For example:


pArcText->reverseCharOrder(true);

Offset from the Arc Entity

Arc-aligned text can be located on or under the circular arc. To set the offset from the arc entity, use the setOffsetFromArc() method. It has one input parameter which requires a Double value as an argument and does not return a value. If the parameter value is positive and the position of arc-aligned text is kOnConvexSide, arc text is located on the circular arc. If the parameter value is negative and the position of arc-aligned text is kOnConvexSide, arc text is located under the circular arc. To set the negative offset for arc-aligned text which is located on the arc entity, use this code:


pArcText->setOffsetFromArc(-1.5);

To get the offset from the arc entity:


double offset = pArcText->offsetFromArc();
odPrintConsoleString(L"\nArc Text size = %g", offset);

Underlined

To underline the arc-aligned text entity, use the setUnderlined() method. It has one Boolean argument and does not return a value. If the value of the argument is true, arc text becomes underlined; if the value of the argument is false, the underline is canceled. For example:


pArcText->setUnderlined(true);

To check the underline mode, use the isUnderlined() method which returns the Boolean value true if the arc-aligned text is underlined or false if the arc-aligned text is not underlined. For example:


if(pArcText->isUnderlined())
	odPrintConsoleString(L"\nArc Text is underlined");

Font

To change the font of the arc-aligned text, use the setfont() method which requires five parameters: name of the font (typeface), Boolean values for bold and italic modes, Windows character set identifier (charset) and Windows pitch, and character family identifier (pitchAndFamily). This method does not return a value. For example:


pArcText->setFont("Times New Roman", true, true, 1251, 0);

If typeface is null, the Windows font information is removed from this text style.

Alignment

The Align property defines how the arc text is aligned relative to the circular arc entity. Alignment mode must be one of the following:


enum OdArcTextAlignment
{
	kFit    = 1,
	kLeft   = 2,
	kRight  = 3,
	kCenter = 4
}

By default, the Align property is kFit.

To set alignment of the arc-aligned text to Right mode:


pArcText->setAlignment(OdArcTextAlignment::kRight);

To get the alignment mode of the arc-aligned text, use the alignment() method which returns an Integer constant from the OdArcTextAlignment enumeration. For example:


int alignment = pArcText->alignment();
if(alignment == OdArcTextAlignment::kRight)
	odPrintConsoleString(L"\nText alignment = Right");

Left and Right Offset

The arc-aligned text offset can be changed by using the setRightOffset() and setLeftOffset() methods. These methods have one input parameter: a Double value of the offset. For example:


pArcText->setRightOffset(6.5);


pArcText->setLeftOffset(5.2);

If the setRightOffset() method is used, the arc-aligned text is moved to the end point of the arc entity. If setLeftOffset() method is used, the arc-aligned text is moved to the start point of the arc entity.

To get the left offset of the arc-aligned text:


double leftOffset = pArcText->leftOffset();
odPrintConsoleString(L"\n\nLeft offset = %g", leftOffset);

To get the right offset of the arc-aligned text:


double rightOffset = pArcText-> rightOffset();
odPrintConsoleString(L"\n\nLeft offset = %g", rightOffset);

Character Spacing

To get character spacing, use the charSpacing() method which does not have input parameters and returns a Double value. By default the character spacing is 0. For example:


double charSpacing = pArcText->charSpacing();
odPrintConsoleString(L"\n\nChar Spacing = %g", charSpacing);

To set character spacing, use the setCharSpacing() method which has one input parameter, a Double value of spacing, and does not return a value. For example:


pArcText->setCharSpacing(2);

If the input parameter has a negative value (for example, -2) and the property reversedCharOrder is set to the false value, arc-aligned text reverses its direction as in the figure below.