Text Tools¶

MTextEditor¶

class ezdxf.tools.text.MTextEditor(text: str = '')¶

The MTextEditor is a helper class to build MTEXT content strings with support for inline codes to change color, font or paragraph properties. The result is always accessible by the text attribute or the magic __str__() function as str(MTextEditor("text")).

All text building methods return self to implement a floating interface:

e = MTextEditor("This example ").color("red").append("switches color to red.")
mtext = msp.add_mtext(str(e))

The initial text height, color, text style and so on is determined by the DXF attributes of the MText entity.

Warning

The MTextEditor assembles just the inline code, which has to be parsed and rendered by the target CAD application, ezdxf has no influence to that result.

Keep inline formatting as simple as possible, don’t test the limits of its capabilities, this will not work across different CAD applications and keep the formatting in a logic manner like, do not change paragraph properties in the middle of a paragraph.

There is no official documentation for the inline codes!

Parameters:: text – init value of the MTEXT content string.

text¶: The MTEXT content as a simple string.

append(text: str) → MTextEditor¶: Append text.

__iadd__(text: str) → MTextEditor¶

Append text:

e = MTextEditor("First paragraph.\P")
e += "Second paragraph.\P")

__str__() → str¶: Returns the MTEXT content attribute text.

clear()¶: Reset the content to an empty string.

font(name: str, bold: bool = False, italic: bool = False) → MTextEditor¶

Set the text font by the font family name. Changing the font height should be done by the height() or the scale_height() method. The font family name is the name shown in font selection widgets in desktop applications: “Arial”, “Times New Roman”, “Comic Sans MS”. Switching the codepage is not supported.

Parameters:

name – font family name
bold – flag
italic – flag

height(height: float) → MTextEditor¶: Set the absolute text height in drawing units.

scale_height(factor: float) → MTextEditor¶: Scale the text height by a factor. This scaling will accumulate, which means starting at height 2.5 and scaling by 2 and again by 3 will set the text height to 2.5 x 2 x 3 = 15. The current text height is not stored in the MTextEditor, you have to track the text height by yourself! The initial text height is stored in the MText entity as DXF attribute char_height.

width_factor(factor: float) → MTextEditor¶: Set the absolute text width factor.

char_tracking_factor(factor: float) → MTextEditor¶: Set the absolute character tracking factor.

oblique(angle: int) → MTextEditor¶: Set the text oblique angle in degrees, vertical is 0, a value of 15 will lean the text 15 degree to the right.

color(name: str) → MTextEditor¶: Set the text color by color name: “red”, “yellow”, “green”, “cyan”, “blue”, “magenta” or “white”.

aci(aci: int) → MTextEditor¶: Set the text color by AutoCAD Color Index (ACI) in range [0, 256].

rgb(rgb: RGB) → MTextEditor¶: Set the text color as RGB value.

underline(text: str) → MTextEditor¶: Append text with a line below the text.

overline(text: str) → MTextEditor¶: Append text with a line above the text.

strike_through(text: str) → MTextEditor¶: Append text with a line through the text.

group(text: str) → MTextEditor¶: Group text, all properties changed inside a group are reverted at the end of the group. AutoCAD supports grouping up to 8 levels.

stack(upr: str, lwr: str, t: str = '^') → MTextEditor¶

Append stacked text upr over lwr, argument t defines the kind of stacking, the space ” ” after the “^” will be added automatically to avoid caret decoding:

"^": vertical stacked without divider line, e.g. \SA^ B:
     A
     B

"/": vertical stacked with divider line,  e.g. \SX/Y:
     X
     -
     Y

"#": diagonal stacked, with slanting divider line, e.g. \S1#4:
     1/4

paragraph(props: ParagraphProperties) → MTextEditor¶: Set paragraph properties by a ParagraphProperties object.

bullet_list(indent: float, bullets: Iterable[str], content: Iterable[str]) → MTextEditor¶

Build bulleted lists by utilizing paragraph indentation and a tabulator stop. Any string can be used as bullet. Indentation is a multiple of the initial MTEXT char height (see also docs about ParagraphProperties), which means indentation in drawing units is MText.dxf.char_height x indent.

Useful UTF bullets:

“bull” U+2022 = • (Alt Numpad 7)
“circle” U+25CB = ○ (Alt Numpad 9)

For numbered lists just use numbers as bullets:

MTextEditor.bullet_list(
    indent=2,
    bullets=["1.", "2."],
    content=["first", "second"],
)

Parameters:

indent – content indentation as multiple of the initial MTEXT char height
bullets – iterable of bullet strings, e.g. ["-"] * 3, for 3 dashes as bullet strings
content – iterable of list item strings, one string per list item, list items should not contain new line or new paragraph commands.

Constants stored in the MTextEditor class:

NEW_LINE	`'\P'`
NEW_PARAGRAPH	`'\P'`
NEW_COLUMN	`'\N`
UNDERLINE_START	`'\L'`
UNDERLINE_STOP	`'\l'`
OVERSTRIKE_START	`'\O'`
OVERSTRIKE_STOP	`'\o'`
STRIKE_START	`'\K'`
STRIKE_STOP	`'\k'`
ALIGN_BOTTOM	`'\A0;'`
ALIGN_MIDDLE	`'\A1;'`
ALIGN_TOP	`'\A2;'`
NBSP	`'\~'`
TAB	`'^I'`

class ezdxf.tools.text.ParagraphProperties(indent=0, left=0, right=0, align=DEFAULT, tab_stops=[])¶

Stores all known MTEXT paragraph properties in a NamedTuple. Indentations and tab stops are multiples of the default text height MText.dxf.char_height. E.g. char_height is 0.25 and indent is 4, the real indentation is 4 x 0.25 = 1 drawing unit. The default tabulator stops are 4, 8, 12, … if no tabulator stops are explicit defined.

Parameters:

indent (float) – left indentation of the first line, relative to left, which means an indent of 0 has always the same indentation as left
left (float) – left indentation of the paragraph except for the first line
right (float) – left indentation of the paragraph
align – MTextParagraphAlignment enum
tab_stops – tuple of tabulator stops, as float or as str, float values are left aligned tab stops, strings with prefix "c" are center aligned tab stops and strings with prefix "r" are right aligned tab stops

tostring() → str¶: Returns the MTEXT paragraph properties as MTEXT inline code e.g. "\pxi-2,l2;".

class ezdxf.lldxf.const.MTextParagraphAlignment¶

DEFAULT¶

LEFT¶

RIGHT¶

CENTER¶

JUSTIFIED¶

DISTRIBUTED¶

Single Line Text¶

class ezdxf.tools.text.TextLine(text: str, font: fonts.AbstractFont)¶

Helper class which represents a single line text entity (e.g. Text).

Parameters:

text – content string
font – ezdxf font definition like MonospaceFont or TrueTypeFont

property width: float¶: Returns the final (stretched) text width.

property height: float¶: Returns the final (stretched) text height.

stretch(alignment: TextEntityAlignment, p1: Vec3, p2: Vec3) → None¶: Set stretch factors for FIT and ALIGNED alignments to fit the text between p1 and p2, only the distance between these points is important. Other given alignment values are ignore.

font_measurements() → fonts.FontMeasurements¶: Returns the scaled font measurements.

baseline_vertices(insert: UVec, halign: int = 0, valign: int = 0, angle: float = 0, scale: tuple[float, float] = (1, 1)) → list[Vec3]¶

Returns the left and the right baseline vertex of the text line.

Parameters:

insert – insertion location
halign – horizontal alignment left=0, center=1, right=2
valign – vertical alignment baseline=0, bottom=1, middle=2, top=3
angle – text rotation in radians
scale – scale in x- and y-axis as 2-tuple of float

corner_vertices(insert: UVec, halign: int = 0, valign: int = 0, angle: float = 0, scale: tuple[float, float] = (1, 1), oblique: float = 0) → list[Vec3]¶

Returns the corner vertices of the text line in the order bottom left, bottom right, top right, top left.

Parameters:

insert – insertion location
halign – horizontal alignment left=0, center=1, right=2
valign – vertical alignment baseline=0, bottom=1, middle=2, top=3
angle – text rotation in radians
scale – scale in x- and y-axis as 2-tuple of float
oblique – shear angle (slanting) in x-direction in radians

static transform_2d(vertices: Iterable[UVec], insert: UVec = Vec3(0, 0, 0), shift: tuple[float, float] = (0, 0), rotation: float = 0, scale: tuple[float, float] = (1, 1), oblique: float = 0) → list[Vec3]¶

Transform any vertices from the text line located at the base location at (0, 0) and alignment LEFT.

Parameters:

vertices – iterable of vertices
insert – insertion location
shift – (shift-x, shift-y) as 2-tuple of float
rotation – text rotation in radians
scale – (scale-x, scale-y) as 2-tuple of float
oblique – shear angle (slanting) in x-direction in radians

Functions¶

ezdxf.tools.text.caret_decode(text: str) → str¶

DXF stores some special characters using caret notation. This function decodes this notation to normalize the representation of special characters in the string.

see: https://en.wikipedia.org/wiki/Caret_notation

ezdxf.tools.text.estimate_mtext_content_extents(content: str, font: fonts.AbstractFont, column_width: float = 0.0, line_spacing_factor: float = 1.0) → tuple[float, float]¶

Estimate the width and height of the MText content string. The result is very inaccurate if inline codes are used or line wrapping at the column border is involved! Column breaks \N will be ignored.

Parameters:

content – the MText content string
font – font abstraction based on ezdxf.tools.fonts.AbstractFont
column_width – MText.dxf.width or 0.0 for an unrestricted column width
line_spacing_factor – MText.dxf.line_spacing_factor

Returns:

tuple[width, height]

ezdxf.tools.text.estimate_mtext_extents(mtext: MText) → tuple[float, float]¶

Estimate the width and height of a single column MText entity.

This function is faster than the mtext_size() function, but the result is very inaccurate if inline codes are used or line wrapping at the column border is involved!

Returns:: Tuple[width, height]

ezdxf.tools.text.fast_plain_mtext(text: str, split=False) → list[str] | str¶

Returns the plain MTEXT content as a single string or a list of strings if split is True. Replaces \P by \n and removes other controls chars and inline codes.

This function is more than 4x faster than plain_mtext(), but does not remove single letter inline commands with arguments without a terminating semicolon like this "\C1red text".

Note

Well behaved CAD applications and libraries always create inline codes for commands with arguments with a terminating semicolon like this "\C1;red text"!

Parameters:

text – MTEXT content string
split – split content at line endings \P

ezdxf.tools.text.is_text_vertical_stacked(text: DXFEntity) → bool¶: Returns True if the associated text Textstyle is vertical stacked.

ezdxf.tools.text.is_upside_down_text_angle(angle: float, tol: float = 3.0) → bool¶

Returns True if the given text angle in degrees causes an upside down text in the WCS. The strict flip range is 90° < angle < 270°, the tolerance angle tol extends this range to: 90+tol < angle < 270-tol. The angle is normalized to [0, 360).

Parameters:

angle – text angle in degrees
tol – tolerance range in which text flipping will be avoided

ezdxf.tools.text.leading(cap_height: float, line_spacing: float = 1.0) → float¶

Returns the distance from baseline to baseline.

Parameters:

cap_height – cap height of the line
line_spacing – line spacing factor as percentage of 3-on-5 spacing

ezdxf.tools.text.plain_mtext(text: str, split=False, tabsize: int = 4) → list[str] | str¶

Returns the plain MTEXT content as a single string or a list of strings if split is True. Replaces \P by \n and removes other controls chars and inline codes.

This function is much slower than fast_plain_mtext(), but removes all inline codes.

Parameters:

text – MTEXT content string
split – split content at line endings \P
tabsize – count of replacement spaces for tabulators ^I

ezdxf.tools.text.plain_text(text: str) → str¶: Returns the plain text for Text, Attrib and Attdef content.

ezdxf.tools.text.safe_string(s: str | None, max_len: int = MAX_STR_LEN) → str¶: Returns a string with line breaks \n replaced by \P and the length limited to max_len.

ezdxf.tools.text.text_wrap(text: str, box_width: float | None, get_text_width: Callable[[str], float]) → list[str]¶

Wrap text at \n and given box_width. This tool was developed for usage with the MTEXT entity. This isn’t the most straightforward word wrapping algorithm, but it aims to match the behavior of AutoCAD.

Parameters:

text – text to wrap, included \n are handled as manual line breaks
box_width – wrapping length, None to just wrap at \n
get_text_width – callable which returns the width of the given string

ezdxf.tools.text.upright_text_angle(angle: float, tol: float = 3.0) → float¶

Returns a readable (upright) text angle in the range angle <= 90+tol or angle >= 270-tol. The angle is normalized to [0, 360).

Parameters:

angle – text angle in degrees
tol – tolerance range in which text flipping will be avoided