Single-Line Text Alignment Properties

The single-line text object uses the alignment point, vertical mode, and horizontal mode properties to define the alignment of text inside a restricted area (the text area size does not change). To align text inside the restricted area, the single-line text entity defines four horizontal lines (top, middle, base, and bottom) and three vertical lines (left, center, and right).

The base line passes through the origin point from which the text starts plotting (OCS origin) along the OCS X-axis. The top line passes through the upper edge of the restricted area. The bottom line passes through the lower edge of the restricted area, including the letters drawn under the base line. The middle line passes through the midpoint between the top and base lines.

The left line passes through the origin point along the OCS Y-axis. The right line passes through the point on which the text finishes being plotted. The center line passes through the midpoint between the left and right lines.

The single-line text entity also defines the middle point as the center of the restricted area.

All of these lines form 13 points used to align the single-line text inside the restricted area.

Additionally, the single-line text entity defines two specific modes for alignment, Align and Fit, which change the text geometry within the restricted area when the area size is changed.

In the following examples, the pSText variable stores a pointer to the single-line text object.

Alignment Point

The property defines the point which is used for storing the original text position in three-dimensional world coordinates when the alignment is not set to kTextBase and kTextLeft together, that is, when the text position is shifted (recalculated) relative to the original text position (insertion point). The alignment point has the coordinates (0,0,0) by default.

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


OdGePoint3d apoint = pSText->alignmentPoint();
odPrintConsoleString(L"\nAlignment point = (%g,%g,%g)", apoint.x, apoint.y, apoint.z);

To set the alignment point, use the setAlignmentPoint() 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->setAlignmentPoint(point);

Vertical Alignment Mode

The property defines the vertical alignment mode as a value of the OdDb::TextVertMode enumerator that can take the following values:

kTextBase (=0) — Align to the base line.
kTextBottom (=1) — Align to the bottom line.
kTextVertMid (=2) — Align to the middle line.
kTextTop (=3) — Align to the top line.

The base line coincides with OCS X-axis which defines the text direction when it is drawn at the OCS origin. When the alignment is not set to the base line (≠0), the single-line text entity uses the alignment point to store the original text position and recalculates the current position to draw the text at its OCS origin relative to the base line. The vertical alignment mode is zero (kTextBase) by default.

To get the vertical alignment mode, use the verticalMode() method which does not have arguments and returns the mode number. For example:


OdDb::TextVertMode mode = pSText->verticalMode();
odPrintConsoleString(L"\nVertical mode = %d", (int) mode);

To set the vertical alignment mode, use the setVerticalMode() method which requires a value of the TextVertMode type as an argument and does not return a value. For example:


// Set to the top line
pSText->setVerticalMode( OdDb::kTextTop );

// Set to the bottom line
pSText->setVerticalMode( OdDb::kTextBottom );

// Set to the base line (default)
pSText->setVerticalMode( OdDb::kTextBase );

Horizontal Alignment Mode

The property defines the horizontal alignment mode as a value of the OdDb::TextHorzMode enumerator that can take the following values:

kTextLeft (=0) — Align to the left line.
kTextCenter (=1) — Align to the center line.
kTextRight (=2) — Align to the right line.
kTextMid (=4) — Align to the middle line.

The left line coincides with OCS Y-axis which defines the text upside when it is drawn at OCS origin. When the alignment is not set to the left line (≠0), the single-line text entity uses the alignment point to store the original text position and recalculates the current position to draw the text at its OCS origin. The horizontal alignment mode is zero (kTextLeft) by default.

To get the horizontal alignment mode, use the horizontalMode() method which does not have arguments and returns the mode number. For example:


OdDb::TextHorzMode mode = pSText->horizontalMode();
odPrintConsoleString(L"\nHorizontal mode = %d", (int) mode);

To set the horizontal alignment mode, use the setHorizontalMode() method which requires a value of the TextHorzMode type as an argument and does not return a value. For example:


// Set to the center line
pSText->setHorizontalMode( OdDb::kTextCenter );

// Set to the right line
pSText->setHorizontalMode( OdDb::kTextRight );

// Set to the left line (default)
pSText->setHorizontalMode( OdDb::kTextLeft );

Adjusting Alignment Mode

The single-line text object has Align and Fit modes for adjusting the text alignment in the restricted area. The adjusted alignment is the specific mode which automatically modifies specific text properties such as the height scale factor, width scale factor, and rotation angle. These properties influence the text geometry to provide alignment of the text within the range of the whole restricted area when the text position (insertion point) or alignment point are changed. Otherwise, when the position or alignment point is changed, the location and size of the restricted area also changes, and as a result, the text geometry is not within the changed restricted area.

To keep the text in the area, the Align mode changes the height scale factor and rotation angle together.

To set the Align mode, pass the kTextAlign (=3) value as an argument of the setHorizontalMode() method. For example:


pSText->setHorizontalMode( OdDb::kTextAlign );

To inscribe the text in the area, the Fit mode changes the width scale factor and rotation angle together (the height is constant).

To set the Fit mode, pass the kTextFit (=5) value as an argument of the setHorizontalMode() method. For example:


pSText->setHorizontalMode( OdDb::kTextFit );

The position point defines the left edge of the restricted area, the alignment point defines the right edge of the restricted area. Both points influence on the text geometry. The single-line text entity uses both points to inscribe the text in the restricted area.

Default Alignment

The default alignment is when the horizontal mode is set to kTextLeft and the vertical mode is set to kTextBase or when the horizontal mode is set to kTextMid. To check whether the current alignment is set to the default, use the isDefaultAlignment() method which returns True when the alignment is default or False when the alignment is custom. For example:


odPrintConsoleString(L"\nAlignment is = %s", ((pSText->isDefaultAlignment()) ? L"Default" : L"Custom"));

Recalculating Text Geometry

The single-line text entity does not modify the coordinates of the insertion point and alignment point after setting the vertical mode or horizontal mode. The program must recalculate the geometry after changing the alignment. To recalculate the geometry that corresponds to the current vertical and horizontal modes relative to the original position, use the adjustAlignment() method. For example:


pSText->setVerticalMode( OdDb::kTextVertMid );
pSText->setHorizontalMode( OdDb::kTextMid );
pSText->adjustAlignment();

Example for adjusting alignment: