0
# Advanced Rendering Control
1
2
Fine-grained control over ASCII art text rendering including direction, justification, width constraints, and font management. The Figlet class provides the primary interface for advanced rendering scenarios.
3
4
## Capabilities
5
6
### Figlet Class
7
8
Main rendering class that provides comprehensive control over ASCII art generation with persistent configuration.
9
10
```python { .api }
11
class Figlet:
12
def __init__(self, font: str = "standard", direction: str = "auto", justify: str = "auto", width: int = 80):
13
"""
14
Initialize Figlet renderer with rendering options.
15
16
Parameters:
17
- font (str): Font name to use for rendering (default: "standard")
18
- direction (str): Text direction - "auto", "left-to-right", "right-to-left"
19
- justify (str): Text justification - "auto", "left", "center", "right"
20
- width (int): Maximum output width in characters (default: 80)
21
22
Raises:
23
FontNotFound: If the specified font cannot be located
24
FontError: If there is a problem parsing the font file
25
"""
26
```
27
28
### Text Rendering
29
30
Primary method for converting text to ASCII art using the configured settings.
31
32
```python { .api }
33
def renderText(self, text: str) -> FigletString:
34
"""
35
Render text as ASCII art using current font and settings.
36
37
Parameters:
38
- text (str): Text to convert to ASCII art
39
40
Returns:
41
FigletString: ASCII art representation with manipulation methods
42
43
Raises:
44
CharNotPrinted: If width is insufficient to print a character
45
FontError: If font rendering encounters an error
46
"""
47
```
48
49
### Font Management
50
51
Change the active font while preserving other rendering settings.
52
53
```python { .api }
54
def setFont(self, **kwargs: str) -> None:
55
"""
56
Change the active font and reload font data.
57
58
Parameters:
59
- font (str): New font name to load
60
61
Raises:
62
FontNotFound: If the specified font cannot be located
63
FontError: If there is a problem parsing the font file
64
"""
65
```
66
67
### Font Discovery
68
69
Retrieve available fonts using the current Figlet instance.
70
71
```python { .api }
72
def getFonts(self) -> list[str]:
73
"""
74
Get list of all available font names.
75
76
Returns:
77
list[str]: Sorted list of available font names
78
"""
79
```
80
81
## Usage Examples
82
83
### Basic Usage
84
85
```python
86
from pyfiglet import Figlet
87
88
# Create renderer with default settings
89
fig = Figlet()
90
result = fig.renderText("Hello World")
91
print(result)
92
93
# Create renderer with custom settings
94
fig = Figlet(font="slant", width=120, justify="center")
95
result = fig.renderText("Centered Text")
96
print(result)
97
```
98
99
### Dynamic Font Switching
100
101
```python
102
from pyfiglet import Figlet
103
104
fig = Figlet(width=100)
105
106
# Try different fonts for the same text
107
fonts = ["standard", "big", "slant", "shadow"]
108
text = "PyFiglet"
109
110
for font_name in fonts:
111
try:
112
fig.setFont(font=font_name)
113
result = fig.renderText(text)
114
print(f"\n--- {font_name.upper()} ---")
115
print(result)
116
except Exception as e:
117
print(f"Error with {font_name}: {e}")
118
```
119
120
### Advanced Rendering Configuration
121
122
```python
123
from pyfiglet import Figlet
124
125
# Right-to-left text with right justification
126
fig = Figlet(
127
font="standard",
128
direction="right-to-left",
129
justify="right",
130
width=60
131
)
132
133
# Render multiple lines
134
texts = ["Line 1", "Line 2", "Line 3"]
135
for text in texts:
136
result = fig.renderText(text)
137
print(result)
138
```
139
140
### Font Information and Selection
141
142
```python
143
from pyfiglet import Figlet
144
145
fig = Figlet()
146
147
# Get available fonts
148
fonts = fig.getFonts()
149
print(f"Total fonts available: {len(fonts)}")
150
151
# Test fonts with sample text
152
sample_text = "Test"
153
for font in fonts[:5]: # Test first 5 fonts
154
try:
155
fig.setFont(font=font)
156
result = fig.renderText(sample_text)
157
print(f"\n{font}:")
158
print(result.strip())
159
except Exception as e:
160
print(f"{font}: {e}")
161
```
162
163
## Configuration Options
164
165
### Text Direction
166
167
- **"auto"**: Uses font's default direction setting
168
- **"left-to-right"**: Standard left-to-right text flow
169
- **"right-to-left"**: Right-to-left text flow (for certain fonts)
170
171
### Text Justification
172
173
- **"auto"**: Automatic based on text direction (left for LTR, right for RTL)
174
- **"left"**: Left-aligned text
175
- **"center"**: Center-aligned text
176
- **"right"**: Right-aligned text
177
178
### Width Constraints
179
180
- Controls maximum output width for line wrapping
181
- Affects justification calculations
182
- Minimum width required varies by font and characters
183
184
## Property Access
185
186
The Figlet class provides computed properties for accessing current settings:
187
188
```python
189
fig = Figlet(direction="auto", justify="auto")
190
191
# These properties compute actual values based on font and settings
192
actual_direction = fig.direction # e.g., "left-to-right"
193
actual_justify = fig.justify # e.g., "left"
194
```
195
196
## Error Handling
197
198
Advanced rendering can encounter several error conditions:
199
200
- **FontNotFound**: Specified font doesn't exist
201
- **FontError**: Font file is corrupted or invalid
202
- **CharNotPrinted**: Output width too narrow for character rendering
203
204
Handle these appropriately for robust applications:
205
206
```python
207
from pyfiglet import Figlet, FontNotFound, CharNotPrinted
208
209
try:
210
fig = Figlet(font="nonexistent", width=20)
211
result = fig.renderText("Wide Text That Won't Fit")
212
except FontNotFound:
213
print("Font not available, using default")
214
fig = Figlet(width=20)
215
result = fig.renderText("Text")
216
except CharNotPrinted:
217
print("Text too wide, increasing width")
218
fig = Figlet(width=80)
219
result = fig.renderText("Text")
220
```