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

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.

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

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.

Parameters

color – color as AutoCAD Color Index (ACI), string or RGB tuple
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.

__iadd__(text: str) → MText¶: Append text to existing content (text attribute).

append(text: str) → MText¶: Append text to existing content (text attribute).

set_font(name: str, bold: bool = False, italic: bool = False, codepage: int = 1252, pitch: int = 0) → None¶

Append font change (e.g. '\Fkroeger|b0|i0|c238|p10' ) to existing content (text attribute).

Parameters

name – font name
bold – flag
italic – flag
codepage – character codepage
pitch – font size

set_color(color_name: str) → None¶: Append text color change to existing content, color_name as red, yellow, green, cyan, blue, magenta or white.

add_stacked_text(upr: str, lwr: str, t: str = '^') → None¶

Add stacked text upr over lwr, t defines the kind of stacking:

"^": 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

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

Returns text content without formatting codes.

Parameters: split – returns list of strings splitted at line breaks if True else returns a single string.

New in version 0.11.1.

transform(m: Matrix44) → MText¶: Transform MTEXT entity by transformation matrix m inplace.

New in version 0.13.

MText Inline Codes¶

Code	Description
\L	Start underline
\l	Stop underline
\O	Start overstrike
\o	Stop overstrike
\K	Start strike-through
\k	Stop strike-through
\P	New paragraph (new line)
\pxi	Control codes for bullets, numbered paragraphs and columns
\X	Paragraph wrap on the dimension line (only in dimensions)
\Q	Slanting (obliquing) text by angle - e.g. \Q30;
\H	Text height - e.g. \H3x;
\W	Text width - e.g. \W0.8x;
\F	Font selection e.g. \Fgdt;o - GDT-tolerance
\S	Stacking, fractions e.g. \SA^B or \SX/Y or \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
\T	Tracking, char.spacing - e.g. \T2;
\~	Non-wrapping space, hard 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 MText:¶

Constant	Description
UNDERLINE_START	start underline text (`b += b.UNDERLINE_START`)
UNDERLINE_STOP	stop underline text (`b += b.UNDERLINE_STOP`)
UNDERLINE	underline text (`b += b.UNDERLINE % "Text"`)
OVERSTRIKE_START	start overstrike
OVERSTRIKE_STOP	stop overstrike
OVERSTRIKE	overstrike text
STRIKE_START	start strike trough
STRIKE_STOP	stop strike trough
STRIKE	strike trough text
GROUP_START	start of group
GROUP_END	end of group
GROUP	group text
NEW_LINE	start in new line (`b += "Text" + b.NEW_LINE`)
NBSP	none breaking space (`b += "Python" + b.NBSP + "3.4"`)