Tutorial for MText¶

The MText entity is a multi line entity with extended formatting possibilities and requires at least DXF version R2000, to use all features (e.g. background fill) DXF R2007 is required.

Prolog code:

import ezdxf

doc = ezdxf.new('R2007', setup=True)
msp = doc.modelspace()

lorem_ipsum = """
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation
ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit
esse cillum dolore eu fugiat nulla pariatur. Excepteur sint
occaecat cupidatat non proident, sunt in culpa qui officia
deserunt mollit anim id est laborum.
"""

Adding a MText entity¶

The MText entity can be added to any layout (modelspace, paperspace or block) by the add_mtext() function.

# store MText entity for additional manipulations
mtext = msp.add_mtext(lorem_ipsum, dxfattribs={'style': 'OpenSans'})

This adds a MText entity with text style 'OpenSans'. The MText content can be accessed by the text attribute, this attribute can be edited like any Python string:

mtext.text += 'Append additional text to the MText entity.'
# even shorter with __iadd__() support:
mtext += 'Append additional text to the MText entity.'

Important

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.

Text placement¶

The location of the MText entity is defined by the MText.dxf.insert and the MText.dxf.attachment_point attributes. The attachment_point defines the text alignment relative to the insert location, default value is 1.

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

The MText entity has a method for setting insert, attachment_point and rotation attributes by one call: set_location()

Character height¶

The character height is defined by the DXF attribute MText.dxf.char_height in drawing units, which has also consequences for the line spacing of the MText entity:

mtext.dxf.char_height = 0.5

The character height can be changed inline, see also MText formatting and MText Inline Codes.

Text rotation (direction)¶

The MText.dxf.rotation attribute defines the text rotation as angle between the x-axis and the horizontal direction of the text in degrees. The MText.dxf.text_direction attribute defines the horizontal direction of MText as vector in WCS or OCS, if an OCS is defined. Both attributes can be present at the same entity, in this case the MText.dxf.text_direction attribute has the higher priority.

The MText entity has two methods to get/set rotation: get_rotation() returns the rotation angle in degrees independent from definition as angle or direction, and set_rotation() set the rotation attribute and removes the text_direction attribute if present.

Defining a wrapping border¶

The wrapping border limits the text width and forces a line break for text beyond this border. Without attribute dxf.width (or setting 0) the lines are wrapped only at the regular line endings \P or \n, setting the reference column width forces additional line wrappings at the given width. The text height can not be limited, the text always occupies as much space as needed.

mtext.dxf.width = 60

MText formatting¶

MText supports inline formatting by special codes: MText Inline Codes

mtext.text = "{\\C1red text} - {\\C3green text} - {\\C5blue text}"

Stacked text¶

MText also supports stacked text:

# the space ' ' in front of 'Lower' anr the ';' behind 'Lower' are necessary
# combined with vertical center alignment
mtext.text = "\\A1\\SUpper^ Lower; - \\SUpper/ Lower;} - \\SUpper# Lower;"

Available helper function for text formatting:

set_color() - append text color change

set_font() - append text font change

add_stacked_text() - append stacked text

Background color (filling)¶

The MText entity can have a background filling:

AutoCAD Color Index (ACI)

true color value as (r, g, b) tuple

color name as string, use special name 'canvas' to use the canvas background color

Because of the complex dependencies ezdxf provides a method to set all required DXF attributes at once:

mtext.set_bg_color(2, scale=1.5)

The parameter 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.