MText

The MTEXT entity (DXF Reference) fits a multiline text in a specified width but can extend vertically to an indefinite length. You can format individual words or characters within the MText.

See also

Tutorial for MText and MTextEditor

Subclass of	ezdxf.entities.DXFGraphic
DXF type	'MTEXT'
Factory function	ezdxf.layouts.BaseLayout.add_mtext()
Inherited DXF attributes	Common graphical DXF attributes
Required DXF version	DXF R2000 ('AC1015')

class ezdxf.entities.MText

dxf.insert

Insertion point (3D Point in OCS)

dxf.char_height

Initial text height (float); default=1.0

dxf.width

Reference text width (float), forces text wrapping at given width.

dxf.attachment_point

Constants defined in ezdxf.lldxf.const:

MText.dxf.attachment_point	Value
MTEXT_TOP_LEFT	1
MTEXT_TOP_CENTER	2
MTEXT_TOP_RIGHT	3
MTEXT_MIDDLE_LEFT	4
MTEXT_MIDDLE_CENTER	5
MTEXT_MIDDLE_RIGHT	6
MTEXT_BOTTOM_LEFT	7
MTEXT_BOTTOM_CENTER	8
MTEXT_BOTTOM_RIGHT	9

dxf.flow_direction

Constants defined in ezdxf.const:

MText.dxf.flow_direction	Value	Description
MTEXT_LEFT_TO_RIGHT	1	left to right
MTEXT_TOP_TO_BOTTOM	3	top to bottom
MTEXT_BY_STYLE	5	by style (the flow direction is inherited from the associated text style)

dxf.style

Text style (string); default = 'STANDARD'

dxf.text_direction

X-axis direction vector in WCS (3D Point); default value is (1, 0, 0); if dxf.rotation and dxf.text_direction are present, dxf.text_direction wins.

dxf.rotation

Text rotation in degrees (float); default = 0

dxf.line_spacing_style

Line spacing style (int), see table below

dxf.line_spacing_factor

Percentage of default (3-on-5) line spacing to be applied. Valid values range from 0.25 to 4.00 (float).

Constants defined in ezdxf.lldxf.const:

MText.dxf.line_spacing_style	Value	Description
MTEXT_AT_LEAST	1	taller characters will override
MTEXT_EXACT	2	taller characters will not override

dxf.bg_fill

Defines the background fill type. (DXF R2007)

MText.dxf.bg_fill	Value	Description
MTEXT_BG_OFF	0	no background color
MTEXT_BG_COLOR	1	use specified color
MTEXT_BG_WINDOW_COLOR	2	use window color (?)
MTEXT_BG_CANVAS_COLOR	3	use canvas background color

dxf.box_fill_scale

Determines how much border there is around the text. (DXF R2007)

Requires: bg_fill, bg_fill_color else AutoCAD complains

Better use set_bg_color()

dxf.bg_fill_color

Background fill color as AutoCAD Color Index (ACI) (DXF R2007)

Better use set_bg_color()

dxf.bg_fill_true_color

Background fill color as true color value (DXF R2007), also dxf.bg_fill_color must be present, else AutoCAD complains.

Better use set_bg_color()

dxf.bg_fill_color_name

Background fill color as name string (?) (DXF R2007), also dxf.bg_fill_color must be present, else AutoCAD complains.

Better use set_bg_color()

dxf.transparency

Transparency of background fill color (DXF R2007), not supported by AutoCAD or BricsCAD.

text

MTEXT content as string (read/write).

Line endings \n will be replaced by the MTEXT line endings \P at DXF export, but not vice versa \P by \n at DXF file loading.

set_location(insert: Vertex, rotation: float = None, attachment_point: int = None) → MText

Set attributes dxf.insert, dxf.rotation and dxf.attachment_point, None for dxf.rotation or dxf.attachment_point preserves the existing value.

get_rotation() → float

Get text rotation in degrees, independent if it is defined by dxf.rotation or dxf.text_direction.

set_rotation(angle: float) → ezdxf.entities.mtext.MText

Set attribute rotation to angle (in degrees) and deletes dxf.text_direction if present.

get_text_direction() → ezdxf.math._vector.Vec3

Returns the horizontal text direction as Vec3 object, even if only the text rotation is defined.

set_bg_color(color: Optional[Union[int, str, Tuple[int, int, int]]], scale: float = 1.5, text_frame=False)

Set background color as AutoCAD Color Index (ACI) value or as name string or as RGB tuple (r, g, b).

Use special color name canvas, to set background color to canvas background color.

Use color = None to remove the background filling.

Setting only a text border is supported (color`=``None`), but in this case the scaling is always 1.5.

Parameters

• color – color as AutoCAD Color Index (ACI), string, RGB tuple or None

• scale – determines how much border there is around the text, the value is based on the text height, and should be in the range of [1, 5], where 1 fits exact the MText entity.

• text_frame – draw a text frame in text color if True

__iadd__(text: str) → MText

Append text to existing content (text attribute).

append(text: str) → MText

Append text to existing content (text attribute).

plain_text(split=False, fast=True) → Union[List[str], str]

Returns the text content without inline formatting codes.

The “fast” mode is accurate if the DXF content was created by reliable (and newer) CAD applications like AutoCAD or BricsCAD. The “accurate” mode is for some rare cases where the content was created by older CAD applications or unreliable DXF libraries and CAD applications.

Parameters

• split – split content text at line breaks if True and returns a list of strings without line endings

• fast – uses the “fast” mode to extract the plain MTEXT content if True or the “accurate” mode if set to False

New in version 0.16.6: fast argument

all_columns_plain_text(split=False) → Union[List[str], str]

Returns the text content of all columns without inline formatting codes.

Parameters

split – split content text at line breaks if True and returns a list of strings without line endings

New in version 0.17.

all_columns_raw_content() → str

Returns the text content of all columns as a single string including the inline formatting codes.

New in version 0.17.

transform(m: Matrix44) → MText

Transform the MTEXT entity by transformation matrix m inplace.

ucs(m: Matrix44) → UCS

Returns the UCS of the MText entity, defined by the insert location (origin), the text direction or rotation (x-axis) and the extrusion vector (z-axis).

MText Inline Codes

Code	Description
\L	Start underline
\l	Stop underline
\O	Start overline
\o	Stop overline
\K	Start strike-through
\k	Stop strike-through
\P	New paragraph (new line)
\p	Paragraphs properties: indentation, alignment, tabulator stops
\X	Paragraph wrap on the dimension line (only in dimensions)
\Q	Slanting (oblique) text by angle - e.g. \Q30;
\H	Text height - e.g. relative \H3x; absolut \H3;
\W	Text width - e.g. relative \W0.8x; absolut \W0.8;
\T	Tracking, character spacing - e.g. relative \T0.5x; absolut \T2;
\F	Font selection e.g. \Fgdt;o - GDT-tolerance
\S	Stacking, fractions e.g. \SA^ B; space after “^” is required to avoid caret decoding, \SX/Y; \S1#4;
\A	Alignment \A0; = bottom \A1; = center \A2; = top
\C	Color change \C1; = red \C2; = yellow \C3; = green \C4; = cyan \C5; = blue \C6; = magenta \C7; = white
\~	Non breaking space
{}	Braces - define the text area influenced by the code, codes and braces can be nested up to 8 levels deep
\	Escape character - e.g. \{ = “{“

Convenient constants defined in MTextEditor:

Constant	Description
UNDERLINE_START	start underline text
UNDERLINE_STOP	stop underline text
OVERSTRIKE_START	start overline
OVERSTRIKE_STOP	stop overline
STRIKE_START	start strike trough
STRIKE_STOP	stop strike trough
GROUP_START	start of group
GROUP_END	end of group
NEW_LINE	start in new line
NBSP	none breaking space