0
# Text Formatting and Basic Elements
1

2
Text formatting commands and environments for controlling font sizes, colors, spacing, and basic document elements. These classes provide the building blocks for document layout and text appearance.
3

4
## Capabilities
5

6
### Text Size Environments
7

8
Environments that modify text size using LaTeX's standard size commands.
9

10
```python { .api }
11
class HugeText(Environment):
12
    def __init__(self, data=None):
13
        """
14
        Environment for 'Huge' text size.
15
        
16
        Parameters:
17
        - data: str or LatexObject, content to format
18
        """
19

20
class LargeText(Environment):
21
    def __init__(self, data=None):
22
        """
23
        Environment for 'Large' text size.
24
        
25
        Parameters:
26
        - data: str or LatexObject, content to format
27
        """
28

29
class MediumText(Environment):
30
    def __init__(self, data=None):
31
        """
32
        Environment for 'large' text size.
33
        
34
        Parameters:
35
        - data: str or LatexObject, content to format
36
        """
37

38
class SmallText(Environment):
39
    def __init__(self, data=None):
40
        """
41
        Environment for 'small' text size.
42
        
43
        Parameters:
44
        - data: str or LatexObject, content to format
45
        """
46

47
class FootnoteText(Environment):
48
    def __init__(self, data=None):
49
        """
50
        Environment for 'footnotesize' text size.
51
        
52
        Parameters:
53
        - data: str or LatexObject, content to format
54
        """
55
```
56

57
Usage example:
58

59
```python
60
from pylatex import Document, Section
61
from pylatex import HugeText, LargeText, SmallText
62

63
doc = Document()
64

65
with doc.create(Section('Text Sizes')):
66
    doc.append(HugeText('This is huge text'))
67
    doc.append(LargeText('This is large text'))
68
    doc.append('This is normal text')
69
    doc.append(SmallText('This is small text'))
70
    doc.append(FootnoteText('This is footnote-sized text'))
71
```
72

73
### Color Text
74

75
Text coloring using the xcolor package with support for standard and custom colors.
76

77
```python { .api }
78
class TextColor(ContainerCommand):
79
    def __init__(self, color, data):
80
        """
81
        Environment for colored text.
82
        
83
        Parameters:
84
        - color: str, color name or specification
85
        - data: str or LatexObject, content to color
86
        
87
        Requires:
88
        - xcolor package
89
        """
90
```
91

92
Usage example:
93

94
```python
95
from pylatex import Document, TextColor
96

97
doc = Document()
98

99
# Standard colors
100
doc.append(TextColor('red', 'This text is red'))
101
doc.append(TextColor('blue', 'This text is blue'))
102

103
# Custom colors (define in document first)
104
doc.add_color('mygreen', 'RGB', '0,128,0')
105
doc.append(TextColor('mygreen', 'This text is custom green'))
106

107
# HTML-style colors
108
doc.append(TextColor('HTML', 'FF5733', 'This text uses HTML color'))
109
```
110

111
### Page and Line Control Commands
112

113
Basic commands for controlling page breaks, line breaks, and spacing.
114

115
```python { .api }
116
class NewPage(CommandBase):
117
    """Command that adds a new page (\\newpage)."""
118

119
class LineBreak(CommandBase):
120
    """Command that adds a line break (\\linebreak)."""
121

122
class NewLine(CommandBase):
123
    """Command that adds a new line (\\newline)."""
124

125
class HFill(CommandBase):
126
    """Command that fills horizontal space (\\hfill)."""
127
```
128

129
Usage example:
130

131
```python
132
from pylatex import Document, NewPage, LineBreak, NewLine, HFill
133

134
doc = Document()
135

136
doc.append('First paragraph.')
137
doc.append(NewLine())
138
doc.append('Second line of same paragraph.')
139
doc.append(LineBreak())
140
doc.append('Third line after line break.')
141

142
# Horizontal spacing
143
doc.append('Left text')
144
doc.append(HFill())
145
doc.append('Right text')
146

147
# Page break
148
doc.append('Content on first page.')
149
doc.append(NewPage())
150
doc.append('Content on second page.')
151
```
152

153
## Text Formatting Patterns
154

155
### Combining Size and Color
156

157
Text size and color can be combined for complex formatting:
158

159
```python
160
from pylatex import Document, TextColor, LargeText
161

162
doc = Document()
163

164
# Nested formatting
165
with doc.create(LargeText()) as large:
166
    large.append(TextColor('red', 'Large red text'))
167

168
# Or create complex structures
169
colored_large = TextColor('blue', LargeText('Large blue text'))
170
doc.append(colored_large)
171
```
172

173
### Multiple Text Elements
174

175
Create documents with varied text formatting:
176

177
```python
178
from pylatex import Document, Section
179
from pylatex import HugeText, TextColor, NewLine
180

181
doc = Document()
182

183
with doc.create(Section('Formatted Text Example')):
184
    doc.append(HugeText('Main Title'))
185
    doc.append(NewLine())
186
    doc.append(TextColor('gray', 'Subtitle in gray'))
187
    doc.append(NewLine())
188
    doc.append('Regular paragraph text with ')
189
    doc.append(TextColor('red', 'red highlighted'))
190
    doc.append(' words.')
191
```
192

193
### Document-wide Color Definitions
194

195
Define colors once and use throughout the document:
196

197
```python
198
from pylatex import Document, TextColor
199

200
doc = Document()
201

202
# Define custom colors
203
doc.add_color('primaryblue', 'RGB', '0,102,204')
204
doc.add_color('secondarygreen', 'RGB', '34,139,34')
205
doc.add_color('accent', 'CMYK', '0,0.5,1,0')
206

207
# Use throughout document
208
doc.append(TextColor('primaryblue', 'Primary color text'))
209
doc.append(TextColor('secondarygreen', 'Secondary color text'))
210
doc.append(TextColor('accent', 'Accent color text'))
211
```
212

213
## LaTeX Size Hierarchy
214

215
The text size classes correspond to LaTeX's standard size commands:
216

217
- **HugeText**: `\\Huge` (largest)
218
- **LargeText**: `\\Large`
219
- **MediumText**: `\\large`
220
- Normal text size (default)
221
- **SmallText**: `\\small`
222
- **FootnoteText**: `\\footnotesize` (smallest)
223

224
Additional LaTeX sizes not directly implemented as classes can be used with generic commands:
225

226
```python
227
from pylatex.base_classes import Command
228

229
# Other LaTeX sizes
230
tiny_text = Command('tiny')
231
scriptsize_text = Command('scriptsize')
232
normalsize_text = Command('normalsize')
233
```
234

235
## Color Models
236

237
The xcolor package supports various color models:
238

239
- **RGB**: `TextColor('red!50!blue', 'Mixed color')`
240
- **HTML**: Define colors with HTML hex codes
241
- **Named colors**: 'red', 'blue', 'green', 'black', 'white', etc.
242
- **dvipsnames**: Extended color names when using `Package('xcolor', options=['dvipsnames'])`
243

244
```python
245
from pylatex import Document, Package, TextColor
246

247
doc = Document()
248
doc.packages.append(Package('xcolor', options=['dvipsnames']))
249

250
# Extended color names
251
doc.append(TextColor('ForestGreen', 'Forest green text'))
252
doc.append(TextColor('RoyalBlue', 'Royal blue text'))
253
doc.append(TextColor('Maroon', 'Maroon text'))
254
```