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.

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: Union[int, str, Tuple[int, int, int], None], 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

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")