0
# Typography and Text
1

2
Advanced text processing system providing comprehensive font management, text styling, inline elements, OpenType features, and sophisticated typography capabilities. The typography engine enables professional-quality text rendering with full control over appearance and layout.
3

4
## Capabilities
5

6
### Font System
7

8
Core font and typeface management providing access to font files, font properties, and typography features.
9

10
```python { .api }
11
class Font:
12
    """
13
    Individual font file with specific weight, width, and slant.
14
    
15
    Parameters:
16
    - typeface: Typeface this font belongs to
17
    - weight: FontWeight, font weight (THIN to HEAVY)
18
    - width: FontWidth, font width (ULTRA_CONDENSED to ULTRA_EXPANDED) 
19
    - slant: FontSlant, font slant (UPRIGHT, OBLIQUE, ITALIC)
20
    """
21
    def __init__(self, typeface, weight=MEDIUM, width=NORMAL, slant=UPRIGHT): ...
22
    
23
    @property
24
    def name(self): ...  # Font name
25
    @property
26
    def family_name(self): ...  # Font family name
27
    @property  
28
    def full_name(self): ...  # Full font name
29
    
30
    # Font metrics
31
    def get_kerning(self, left_glyph, right_glyph): ...  # Kerning between glyphs
32
    def get_ligature(self, *glyphs): ...  # Ligature for glyph sequence
33
    
34
    # Text measurement
35
    def get_glyph_metrics(self, glyph, size): ...  # Individual glyph metrics
36
    def get_text_width(self, text, size): ...  # Text width in font units
37

38
class Typeface:
39
    """
40
    Collection of related fonts (regular, bold, italic, etc.).
41
    
42
    Parameters:
43
    - name: str, typeface name
44
    - *fonts: Font objects in this typeface family
45
    """
46
    def __init__(self, name, *fonts): ...
47
    
48
    def get_font(self, weight=MEDIUM, width=NORMAL, slant=UPRIGHT): ...  # Get specific font
49
    def get_matching_font(self, pattern): ...  # Get font matching pattern
50
    
51
    @property
52
    def fonts(self): ...  # All fonts in typeface
53
```
54

55
### Text Styling
56

57
Comprehensive text styling system with support for all typography properties and advanced formatting options.
58

59
```python { .api }
60
class TextStyle(Style):
61
    """
62
    Style class specifically for text formatting properties.
63
    
64
    Supports all typography attributes including font, color, spacing,
65
    alignment, and advanced OpenType features.
66
    """
67
    
68
    # Font properties
69
    font_family = Attribute(str)  # Font family name
70
    font_size = Attribute(Dimension)  # Text size
71
    font_weight = Attribute(FontWeight)  # Weight (normal, bold, etc.)
72
    font_width = Attribute(FontWidth)  # Width (condensed, expanded, etc.)
73
    font_slant = Attribute(FontSlant)  # Slant (upright, italic, oblique)
74
    
75
    # Color and appearance
76
    text_color = Attribute(Color)  # Text color
77
    background_color = Attribute(Color)  # Background color
78
    
79
    # Spacing and positioning
80
    line_spacing = Attribute(LineSpacing)  # Line height
81
    character_spacing = Attribute(Dimension)  # Letter spacing
82
    word_spacing = Attribute(Dimension)  # Word spacing
83
    
84
    # Text effects
85
    text_decoration = Attribute(TextDecoration)  # Underline, strikethrough, etc.
86
    text_transform = Attribute(TextTransform)  # Uppercase, lowercase, capitalize
87
    
88
    # Alignment
89
    text_align = Attribute(TextAlign)  # Horizontal alignment
90
    vertical_align = Attribute(VerticalAlign)  # Vertical alignment
91

92
class InlineStyle(TextStyle):
93
    """Style class for inline text elements with additional inline-specific properties."""
94
```
95

96
### Styled Text Classes
97

98
Text content classes providing different levels of styling complexity and functionality.
99

100
```python { .api }
101
class StyledText(InlineFlowable):
102
    """
103
    Base class for text content with styling capabilities.
104
    
105
    All text in rinohtype documents is represented by StyledText
106
    or its subclasses, providing consistent styling interfaces.
107
    """
108
    
109
    def spans(self, container=None):
110
        """
111
        Generate text spans for rendering.
112
        
113
        Parameters:
114
        - container: Container for context-sensitive styling
115
        
116
        Yields:
117
        - (text_string, TextStyle) tuples for each styled span
118
        """
119
        ...
120
    
121
    def to_string(self, flowable_target): ...  # Convert to plain string
122
    
123
    @property
124
    def text_style(self): ...  # Get effective text style
125

126
class SingleStyledText(StyledText):
127
    """
128
    Text with uniform styling throughout.
129
    
130
    Most efficient text class for content with consistent formatting
131
    across the entire text string.
132
    
133
    Parameters:
134
    - text: str, the text content
135
    - style: TextStyle, styling to apply to entire text
136
    - parent: parent element
137
    """
138
    def __init__(self, text, style=None, parent=None): ...
139
    
140
    @property
141
    def text(self): ...  # Text content string
142

143
class MixedStyledText(StyledText):
144
    """
145
    Text with multiple styles applied to different parts.
146
    
147
    Supports complex formatting with different styles for different
148
    character ranges within the same text element.
149
    
150
    Parameters:
151
    - text_and_styles: list of (text, style) tuples or StyledText objects
152
    - style: TextStyle, base style for the entire element
153
    - parent: parent element
154
    """
155
    def __init__(self, text_and_styles, style=None, parent=None): ...
156
    
157
    def append(self, styled_text): ...  # Add more styled text
158
    def __add__(self, other): ...  # Concatenate with other styled text
159
    def __iadd__(self, other): ...  # In-place concatenation
160

161
class ConditionalMixedStyledText(MixedStyledText):
162
    """
163
    Mixed styled text with conditional content based on document context.
164
    
165
    Allows different text content or styling based on document properties,
166
    page context, or other conditional factors.
167
    """
168
    
169
    def __init__(self, condition, true_text, false_text, style=None, parent=None): ...
170
```
171

172
### Special Text Elements
173

174
Specialized text elements for specific typography needs and document features.
175

176
```python { .api }
177
class WarnInline(SingleStyledText):
178
    """
179
    Inline text that generates warnings during processing.
180
    
181
    Used for deprecated features, missing references, or other
182
    issues that should be flagged but not prevent document generation.
183
    
184
    Parameters:
185
    - message: str, warning message to display
186
    - style: TextStyle, styling for the warning text
187
    - parent: parent element
188
    """
189
    def __init__(self, message, style=None, parent=None): ...
190

191
class Space(SingleStyledText):
192
    """
193
    Regular breakable space character.
194
    
195
    Represents normal word-separating spaces that can be used
196
    as line break opportunities during text layout.
197
    """
198
    def __init__(self, style=None, parent=None): ...
199

200
class FixedWidthSpace(SingleStyledText):
201
    """
202
    Non-breaking space with fixed width.
203
    
204
    Space that cannot be used as a line break point and maintains
205
    consistent width regardless of justification.
206
    
207
    Parameters:
208
    - width: Dimension, fixed width for the space
209
    - style: TextStyle, styling for the space
210
    - parent: parent element
211
    """
212
    def __init__(self, width, style=None, parent=None): ...
213

214
class NoBreakSpace(SingleStyledText):
215
    """
216
    Non-breaking space that prevents line breaks.
217
    
218
    Equivalent to HTML   - keeps adjacent words together
219
    on the same line.
220
    """
221
    def __init__(self, style=None, parent=None): ...
222

223
class Spacer(SingleStyledText):
224
    """
225
    Flexible space that expands to fill available width.
226
    
227
    Used for justified text and flexible spacing within lines.
228
    Can expand or contract based on justification requirements.
229
    """
230
    def __init__(self, style=None, parent=None): ...
231

232
class Tab(SingleStyledText):
233
    """
234
    Tab character for column alignment.
235
    
236
    Moves text to next tab stop position as defined in paragraph
237
    tab stop settings.
238
    """
239
    def __init__(self, style=None, parent=None): ...
240

241
class Newline(SingleStyledText):
242
    """
243
    Manual line break within paragraph.
244
    
245
    Forces line break without ending paragraph, similar to HTML <br>.
246
    """
247
    def __init__(self, style=None, parent=None): ...
248
```
249

250
### Text Effects
251

252
Special text formatting effects for subscripts, superscripts, and other typography features.
253

254
```python { .api }
255
class Superscript(MixedStyledText):
256
    """
257
    Superscript text positioned above baseline.
258
    
259
    Automatically adjusts font size and baseline position
260
    for proper superscript appearance.
261
    
262
    Parameters:
263
    - text: str or StyledText, content for superscript
264
    - style: TextStyle, additional styling
265
    - parent: parent element
266
    """
267
    def __init__(self, text, style=None, parent=None): ...
268

269
class Subscript(MixedStyledText):
270
    """
271
    Subscript text positioned below baseline.
272
    
273
    Automatically adjusts font size and baseline position
274
    for proper subscript appearance.
275
    
276
    Parameters:
277
    - text: str or StyledText, content for subscript  
278
    - style: TextStyle, additional styling
279
    - parent: parent element
280
    """
281
    def __init__(self, text, style=None, parent=None): ...
282
```
283

284
### Inline Flowables
285

286
Base classes for inline elements that can be embedded within text flow.
287

288
```python { .api }
289
class InlineFlowable(Styled):
290
    """
291
    Base class for elements that can be embedded inline within text.
292
    
293
    Provides interface for inline elements like images, formulas,
294
    or custom inline content that flows with text.
295
    
296
    Parameters:
297
    - baseline: Dimension, baseline offset for vertical alignment
298
    - id: str, unique identifier
299
    - style: InlineStyle, styling for the inline element
300
    - parent: parent element
301
    - source: source location information
302
    """
303
    def __init__(self, baseline=None, id=None, style=None, parent=None, source=None): ...
304
    
305
    def flow_inline(self, container, last_descender, state=None):
306
        """
307
        Flow inline element within text line.
308
        
309
        Parameters:
310
        - container: Container context for flowing
311
        - last_descender: Dimension, descender from previous content
312
        - state: layout state for continuation
313
        
314
        Returns:
315
        - (width, height, baseline, state): layout result
316
        """
317
        ...
318
    
319
    def spans(self, container=None):
320
        """
321
        Generate spans for inline rendering.
322
        
323
        Yields:
324
        - text spans that represent this inline element
325
        """
326
        ...
327

328
class InlineFlowableStyle(Style):
329
    """Style class for inline flowable elements."""
330
    
331
    baseline = Attribute(Dimension)  # Baseline adjustment
332
    
333
class InlineFlowableException(Exception):
334
    """Exception raised by inline flowable processing."""
335
```
336

337
### Typography Constants
338

339
Predefined constants for font properties and text formatting options.
340

341
```python { .api }
342
# Font weights
343
THIN = <FontWeight>
344
EXTRA_LIGHT = <FontWeight>
345
LIGHT = <FontWeight> 
346
NORMAL = <FontWeight>
347
MEDIUM = <FontWeight>
348
SEMI_BOLD = <FontWeight>
349
BOLD = <FontWeight>
350
EXTRA_BOLD = <FontWeight>
351
HEAVY = <FontWeight>
352

353
# Font widths
354
ULTRA_CONDENSED = <FontWidth>
355
EXTRA_CONDENSED = <FontWidth>
356
CONDENSED = <FontWidth>
357
SEMI_CONDENSED = <FontWidth>
358
NORMAL = <FontWidth>
359
SEMI_EXPANDED = <FontWidth>
360
EXPANDED = <FontWidth>
361
EXTRA_EXPANDED = <FontWidth>
362
ULTRA_EXPANDED = <FontWidth>
363

364
# Font slants
365
UPRIGHT = <FontSlant>
366
OBLIQUE = <FontSlant>
367
ITALIC = <FontSlant>
368
```
369

370
## Usage Examples
371

372
### Basic Text Styling
373

374
```python
375
from rinohtype.text import SingleStyledText, TextStyle
376
from rinohtype.color import Color
377
from rinohtype.dimension import PT
378

379
# Create styled text
380
title_style = TextStyle(
381
    font_size=18*PT,
382
    font_weight=BOLD,
383
    text_color=Color(0, 0, 0.8),
384
    text_align='center'
385
)
386

387
title_text = SingleStyledText("Document Title", style=title_style)
388

389
# Body text with different styling
390
body_style = TextStyle(
391
    font_size=11*PT,
392
    line_spacing=1.2,
393
    text_align='justify'
394
)
395

396
body_text = SingleStyledText("This is the main content...", style=body_style)
397
```
398

399
### Mixed Styling Within Text
400

401
```python
402
from rinohtype.text import MixedStyledText, SingleStyledText
403
from rinohtype.color import RED
404

405
# Create text with mixed formatting
406
bold_style = TextStyle(font_weight=BOLD)
407
italic_style = TextStyle(font_slant=ITALIC)
408
emphasis_style = TextStyle(text_color=RED, font_weight=BOLD)
409

410
mixed_text = MixedStyledText([
411
    SingleStyledText("This is "),
412
    SingleStyledText("bold", style=bold_style),
413
    SingleStyledText(" and this is "),
414
    SingleStyledText("italic", style=italic_style),
415
    SingleStyledText(" and this is "),
416
    SingleStyledText("emphasized", style=emphasis_style),
417
    SingleStyledText(".")
418
])
419
```
420

421
### Font and Typeface Management
422

423
```python
424
from rinohtype.font import Typeface, Font
425
from rinohtype.fonts import find_font
426

427
# Load system font
428
times_typeface = Typeface('Times', 
429
    Font('Times-Roman', weight=NORMAL, slant=UPRIGHT),
430
    Font('Times-Bold', weight=BOLD, slant=UPRIGHT), 
431
    Font('Times-Italic', weight=NORMAL, slant=ITALIC),
432
    Font('Times-BoldItalic', weight=BOLD, slant=ITALIC)
433
)
434

435
# Use specific font
436
regular_font = times_typeface.get_font(weight=NORMAL, slant=UPRIGHT)
437
bold_font = times_typeface.get_font(weight=BOLD, slant=UPRIGHT)
438

439
# Apply font in style
440
font_style = TextStyle(
441
    typeface=times_typeface,
442
    font_weight=BOLD,
443
    font_size=12*PT
444
)
445
```
446

447
### Special Text Elements
448

449
```python
450
from rinohtype.text import Superscript, Subscript, NoBreakSpace
451

452
# Mathematical notation with super/subscripts
453
formula = MixedStyledText([
454
    SingleStyledText("E = mc"),
455
    Superscript("2"),
456
    SingleStyledText(" where c = 3×10"),
457
    Superscript("8"),
458
    SingleStyledText(" m/s")
459
])
460

461
# Chemical formula
462
chemical = MixedStyledText([
463
    SingleStyledText("H"),
464
    Subscript("2"),
465
    SingleStyledText("SO"),
466
    Subscript("4")
467
])
468

469
# Non-breaking spaces for proper formatting
470
formatted_text = MixedStyledText([
471
    SingleStyledText("Dr."),
472
    NoBreakSpace(),
473
    SingleStyledText("John"),
474
    NoBreakSpace(), 
475
    SingleStyledText("Smith")
476
])
477
```
478

479
### Advanced Typography Features
480

481
```python
482
from rinohtype.text import TextStyle
483
from rinohtype.dimension import PT
484

485
# Advanced text styling with OpenType features
486
advanced_style = TextStyle(
487
    font_size=12*PT,
488
    character_spacing=0.05*PT,  # Letter spacing
489
    word_spacing=0.25*PT,       # Word spacing
490
    line_spacing=1.4,           # Line height multiplier
491
    text_decoration='underline',  # Text decoration
492
    text_transform='capitalize'   # Text transformation
493
)
494

495
# Paragraph with tab stops for columns
496
from rinohtype.paragraph import TabStop, LEFT, RIGHT, CENTER
497

498
tabbed_style = TextStyle(
499
    tab_stops=[
500
        TabStop(50*PT, LEFT),
501
        TabStop(100*PT, CENTER),
502
        TabStop(150*PT, RIGHT)
503
    ]
504
)
505
```
506

507
### Custom Inline Elements
508

509
```python
510
from rinohtype.text import InlineFlowable, InlineFlowableStyle
511

512
class CustomInline(InlineFlowable):
513
    """Custom inline element."""
514
    
515
    def __init__(self, content, **kwargs):
516
        super().__init__(**kwargs)
517
        self.content = content
518
    
519
    def flow_inline(self, container, last_descender, state=None):
520
        # Custom inline layout logic
521
        width = self.calculate_width()
522
        height = self.calculate_height()
523
        baseline = self.calculate_baseline()
524
        return (width, height, baseline, None)
525
    
526
    def spans(self, container=None):
527
        # Generate spans for rendering
528
        yield (str(self.content), self.get_style('text'))
529

530
# Use custom inline element
531
custom_element = CustomInline("Special Content")
532
text_with_custom = MixedStyledText([
533
    SingleStyledText("Before "),
534
    custom_element,
535
    SingleStyledText(" after")
536
])
537
```