0
# Text Handling
1

2
Text rendering capabilities including basic text elements, inline formatting spans, text along paths, and text area containers with comprehensive typography control.
3

4
## Capabilities
5

6
### Basic Text Elements
7

8
Core text rendering elements for displaying text content in SVG documents.
9

10
```python { .api }
11
def text(text, insert=None, x=None, y=None, dx=None, dy=None, rotate=None, **extra):
12
    """
13
    Create main text element for displaying text
14
    
15
    Args:
16
        text: Text content to display
17
        insert: Text insertion point as (x, y) tuple (default: None)
18
        x: X coordinate(s) - single value or list (default: None)
19
        y: Y coordinate(s) - single value or list (default: None) 
20
        dx: Relative X offset(s) - single value or list (default: None)
21
        dy: Relative Y offset(s) - single value or list (default: None)
22
        rotate: Rotation angle(s) - single value or list (default: None)
23
        **extra: Additional SVG attributes (font-family, font-size, fill, etc.)
24
    
25
    Returns:
26
        Text: Text element with Transform and Presentation mixins
27
    """
28

29
def tspan(text, insert=None, x=None, y=None, dx=None, dy=None, rotate=None, **extra):
30
    """
31
    Create text span for inline text formatting within text elements
32
    
33
    Args:
34
        text: Text content for the span
35
        insert: Span insertion point as (x, y) tuple (default: None)
36
        x: X coordinate(s) - single value or list (default: None)
37
        y: Y coordinate(s) - single value or list (default: None)
38
        dx: Relative X offset(s) - single value or list (default: None)
39
        dy: Relative Y offset(s) - single value or list (default: None)
40
        rotate: Rotation angle(s) - single value or list (default: None)
41
        **extra: Additional SVG attributes (font-style, fill, etc.)
42
    
43
    Returns:
44
        TSpan: Text span element with Presentation mixin
45
    """
46
```
47

48
**Usage Examples:**
49

50
```python
51
import svgwrite
52

53
dwg = svgwrite.Drawing('text.svg', size=('400px', '300px'))
54

55
# Basic text with positioning
56
title = dwg.text('SVG Text Example', insert=(50, 30), 
57
                 font_family='Arial', font_size='20px', fill='navy')
58
dwg.add(title)
59

60
# Text with multiple coordinate lists
61
multipoint = dwg.text('A B C D', x=[50, 80, 110, 140], y=[60, 70, 65, 72],
62
                      font_size='16px', fill='red')
63
dwg.add(multipoint)
64

65
# Text with relative positioning
66
offset_text = dwg.text('Offset Text', insert=(50, 100), 
67
                       dx=[0, 5, 10, 15], dy=[0, -2, -4, -6],
68
                       font_size='14px', fill='green')
69
dwg.add(offset_text)
70

71
# Text with character rotation
72
rotated_chars = dwg.text('ROTATED', insert=(50, 140),
73
                         rotate=[0, 15, 30, 45, 60, 75, 90],
74
                         font_size='18px', fill='purple')
75
dwg.add(rotated_chars)
76

77
# Styled text with spans
78
styled_text = dwg.text('', insert=(50, 180), font_family='serif', font_size='16px')
79
styled_text.add(dwg.tspan('Regular '))
80
styled_text.add(dwg.tspan('Bold ', font_weight='bold', fill='red'))
81
styled_text.add(dwg.tspan('Italic ', font_style='italic', fill='blue'))
82
styled_text.add(dwg.tspan('Underlined', text_decoration='underline', fill='green'))
83
dwg.add(styled_text)
84
```
85

86
### Text References
87

88
Elements for referencing and reusing existing text content.
89

90
```python { .api }
91
def tref(element, **extra):
92
    """
93
    Create text reference to existing text content
94
    
95
    Args:
96
        element: Element to reference (must have an ID)
97
        **extra: Additional SVG attributes
98
    
99
    Returns:
100
        TRef: Text reference element with XLink and Presentation mixins
101
    """
102
```
103

104
**Usage Examples:**
105

106
```python
107
import svgwrite
108

109
dwg = svgwrite.Drawing('textref.svg', size=('400px', '200px'))
110

111
# Create reusable text definition
112
defs = dwg.defs()
113
original_text = dwg.text('Reusable Text Content', id='shared-text',
114
                         font_size='14px', font_family='Arial')
115
defs.add(original_text)
116
dwg.add(defs)
117

118
# Reference the text multiple times
119
text1 = dwg.text('', insert=(50, 50), fill='red')
120
text1.add(dwg.tref(original_text))
121
dwg.add(text1)
122

123
text2 = dwg.text('', insert=(50, 100), fill='blue', font_size='18px')
124
text2.add(dwg.tref(original_text))
125
dwg.add(text2)
126

127
text3 = dwg.text('', insert=(50, 150), fill='green', transform='rotate(15)')
128
text3.add(dwg.tref(original_text))
129
dwg.add(text3)
130
```
131

132
### Text Along Paths
133

134
Advanced text rendering that follows curved or complex path shapes.
135

136
```python { .api }
137
def textPath(path, text, startOffset=None, method='align', spacing='exact', **extra):
138
    """
139
    Create text that follows along a path shape
140
    
141
    Args:
142
        path: Path element or path reference to follow
143
        text: Text content to render along path
144
        startOffset: Distance along path to start text (default: None)
145
        method: Text alignment method 'align' or 'stretch' (default: 'align')
146
        spacing: Letter spacing method 'auto' or 'exact' (default: 'exact')
147
        **extra: Additional SVG attributes (font-size, fill, etc.)
148
    
149
    Returns:
150
        TextPath: Text path element with XLink and Presentation mixins
151
    """
152
```
153

154
**Usage Examples:**
155

156
```python
157
import svgwrite
158

159
dwg = svgwrite.Drawing('textpath.svg', size=('400px', '300px'))
160

161
# Create path definition
162
defs = dwg.defs()
163
curve_path = dwg.path(d='M 50,150 Q 200,50 350,150', id='text-curve')
164
defs.add(curve_path)
165
dwg.add(defs)
166

167
# Make path visible for reference
168
visible_path = dwg.path(d='M 50,150 Q 200,50 350,150', 
169
                        stroke='lightgray', stroke_width=1, fill='none')
170
dwg.add(visible_path)
171

172
# Text following the path
173
curved_text = dwg.text('', font_size='16px', font_family='Arial')
174
text_path = dwg.textPath(curve_path, 'This text follows the curved path!',
175
                         startOffset='10%', fill='blue')
176
curved_text.add(text_path)
177
dwg.add(curved_text)
178

179
# Multiple text paths on same curve with different offsets
180
for i, (text, color, offset) in enumerate([
181
    ('Start', 'red', '0%'),
182
    ('Middle', 'green', '50%'),
183
    ('End', 'purple', '90%')
184
]):
185
    positioned_text = dwg.text('', font_size='14px', font_weight='bold')
186
    text_path = dwg.textPath(curve_path, text, startOffset=offset, fill=color)
187
    positioned_text.add(text_path)
188
    dwg.add(positioned_text)
189

190
# Circular text path
191
circle_path = dwg.path(d='M 200,250 m -50,0 a 50,50 0 1,1 100,0 a 50,50 0 1,1 -100,0', 
192
                       id='circle-path')
193
defs.add(circle_path)
194

195
circular_text = dwg.text('', font_size='12px', font_family='sans-serif')
196
circle_textpath = dwg.textPath(circle_path, 'Circular text around a path • ',
197
                               fill='darkred')
198
circular_text.add(circle_textpath)
199
dwg.add(circular_text)
200
```
201

202
### Text Areas (SVG 1.2 Tiny)
203

204
Text container elements with automatic line wrapping for SVG 1.2 Tiny profile.
205

206
```python { .api }
207
def textArea(text=None, insert=None, size=None, **extra):
208
    """
209
    Create text area container with automatic line wrapping
210
    Available only in SVG 1.2 Tiny profile
211
    
212
    Args:
213
        text: Initial text content (default: None)
214
        insert: Top-left corner as (x, y) tuple (default: None)
215
        size: Area dimensions as (width, height) tuple (default: None)
216
        **extra: Additional SVG attributes (font-family, font-size, etc.)
217
    
218
    Returns:
219
        TextArea: Text area element with Transform and Presentation mixins
220
    """
221

222
def line_increment(value):
223
    """
224
    Set line spacing for text area
225
    
226
    Args:
227
        value: Line height value
228
    """
229

230
def write(text, **extra):
231
    """
232
    Add text with automatic line breaks
233
    
234
    Args:
235
        text: Text content to add
236
        **extra: Additional formatting attributes
237
    """
238

239
def tbreak(**extra):
240
    """
241
    Create explicit line break element for TextArea
242
    Available only in SVG 1.2 Tiny profile
243
    
244
    Args:
245
        **extra: Additional SVG attributes
246
    
247
    Returns:
248
        TBreak: Line break element
249
    """
250
```
251

252
**Usage Examples:**
253

254
```python
255
import svgwrite
256

257
# Note: TextArea only works with SVG 1.2 Tiny profile
258
dwg = svgwrite.Drawing('textarea.svg', profile='tiny', size=('300px', '200px'))
259

260
# Basic text area with wrapping
261
text_area = dwg.textArea(
262
    insert=(20, 20), 
263
    size=(250, 150),
264
    font_family='Arial',
265
    font_size='12px',
266
    fill='black'
267
)
268

269
# Add text content with line spacing
270
text_area.line_increment('16px')
271
text_area.write('This is a text area that supports automatic line wrapping. ')
272
text_area.write('Text will wrap to fit within the specified width. ')
273

274
# Add explicit line break
275
text_area.add(dwg.tbreak())
276
text_area.write('This text appears on a new line after the break.')
277

278
dwg.add(text_area)
279

280
# Text area with border for visualization
281
border = dwg.rect(insert=(20, 20), size=(250, 150), 
282
                  fill='none', stroke='gray', stroke_width=1)
283
dwg.add(border)
284
```
285

286
### Typography and Styling
287

288
Comprehensive typography control through presentation attributes and CSS styling.
289

290
```python { .api }
291
# Font presentation attributes
292
font_family='family-name'     # Font family name
293
font_size='length'           # Font size
294
font_weight='weight'         # normal, bold, bolder, lighter, 100-900
295
font_style='style'           # normal, italic, oblique
296
text_decoration='decoration' # none, underline, overline, line-through
297

298
# Text layout attributes  
299
text_anchor='anchor'         # start, middle, end
300
dominant_baseline='baseline' # auto, middle, central, hanging, etc.
301
direction='ltr|rtl'          # Text direction
302
writing_mode='mode'          # lr-tb, rl-tb, tb-rl, tb-lr
303

304
# Letter and word spacing
305
letter_spacing='length'      # Space between characters
306
word_spacing='length'        # Space between words
307
```
308

309
**Usage Examples:**
310

311
```python
312
import svgwrite
313

314
dwg = svgwrite.Drawing('typography.svg', size=('500px', '400px'))
315

316
# Font family variations
317
fonts = ['Arial', 'serif', 'monospace', 'fantasy', 'cursive']
318
for i, font in enumerate(fonts):
319
    text = dwg.text(f'{font} Font Family', insert=(20, 30 + i*25),
320
                    font_family=font, font_size='16px')
321
    dwg.add(text)
322

323
# Font weights
324
weights = ['normal', 'bold', '300', '600', '900']
325
for i, weight in enumerate(weights):
326
    text = dwg.text(f'Weight: {weight}', insert=(20, 170 + i*20),
327
                    font_family='Arial', font_size='14px', font_weight=weight)
328
    dwg.add(text)
329

330
# Font styles and decorations
331
text = dwg.text('Normal text', insert=(250, 50), font_size='14px')
332
dwg.add(text)
333

334
italic = dwg.text('Italic text', insert=(250, 75), 
335
                  font_size='14px', font_style='italic')
336
dwg.add(italic)
337

338
underlined = dwg.text('Underlined text', insert=(250, 100),
339
                      font_size='14px', text_decoration='underline')
340
dwg.add(underlined)
341

342
# Text anchoring
343
anchor_line = dwg.line((350, 130), (350, 200), stroke='lightgray')
344
dwg.add(anchor_line)
345

346
start_text = dwg.text('Start anchor', insert=(350, 150),
347
                      text_anchor='start', font_size='12px', fill='red')
348
dwg.add(start_text)
349

350
middle_text = dwg.text('Middle anchor', insert=(350, 170),
351
                       text_anchor='middle', font_size='12px', fill='green')
352
dwg.add(middle_text)
353

354
end_text = dwg.text('End anchor', insert=(350, 190),
355
                    text_anchor='end', font_size='12px', fill='blue')
356
dwg.add(end_text)
357

358
# Letter and word spacing
359
spaced_text = dwg.text('L e t t e r   S p a c i n g', insert=(20, 320),
360
                       font_size='16px', letter_spacing='3px')
361
dwg.add(spaced_text)
362

363
word_spaced = dwg.text('Word Spacing Example', insert=(20, 350),
364
                       font_size='16px', word_spacing='10px')
365
dwg.add(word_spaced)
366
```
367

368
### Advanced Text Features
369

370
Complex text layout and formatting capabilities for sophisticated typography.
371

372
```python { .api }
373
# Text with transformations
374
def text(..., transform='transform-list'):
375
    """Text with transform attribute for rotation, scaling, etc."""
376

377
# Multi-language support
378
def text(..., direction='ltr|rtl', xml:lang='language'):
379
    """Text with language and direction attributes"""
380

381
# Accessibility features
382
def text(..., xml:space='preserve|default'):
383
    """Control whitespace handling in text content"""
384
```
385

386
**Usage Examples:**
387

388
```python
389
import svgwrite
390

391
dwg = svgwrite.Drawing('advanced-text.svg', size=('400px', '300px'))
392

393
# Transformed text
394
rotated = dwg.text('Rotated Text', insert=(100, 50),
395
                   font_size='18px', fill='red',
396
                   transform='rotate(30 100,50)')
397
dwg.add(rotated)
398

399
scaled = dwg.text('Scaled Text', insert=(50, 100),
400
                  font_size='14px', fill='blue',
401
                  transform='scale(1.5,0.8)')
402
dwg.add(scaled)
403

404
# Multi-line text with preserved spacing
405
multiline = dwg.text('', insert=(50, 150), font_family='monospace', 
406
                     font_size='12px', xml_space='preserve')
407
lines = ['Line 1: Code example', 'Line 2:   Indented', 'Line 3: Normal']
408
for i, line in enumerate(lines):
409
    tspan = dwg.tspan(line, x=[50], dy=['1.2em'] if i > 0 else [0])
410
    multiline.add(tspan)
411
dwg.add(multiline)
412

413
# Right-to-left text (for demonstration)
414
rtl_text = dwg.text('Right to Left Text', insert=(300, 200),
415
                    font_size='14px', direction='rtl', text_anchor='end')
416
dwg.add(rtl_text)
417

418
# Text with gradient fill (requires gradient definition)
419
defs = dwg.defs()
420
gradient = dwg.linearGradient(start=(0, 0), end=(100, 0), id='text-gradient')
421
gradient.add_stop_color(0, 'red')
422
gradient.add_stop_color(1, 'blue')
423
defs.add(gradient)
424
dwg.add(defs)
425

426
gradient_text = dwg.text('Gradient Text', insert=(50, 250),
427
                         font_size='24px', font_weight='bold',
428
                         fill=gradient.get_paint_server())
429
dwg.add(gradient_text)
430
```