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 changeset_font()
- append text font changeadd_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.
