0
# Utilities
1

2
Collection of utility functions for size conversion, color handling, coordinate calculation, text processing, and other common operations used throughout the xhtml2pdf conversion pipeline.
3

4
## Capabilities
5

6
### Color and Style Utilities
7

8
Functions for handling color values, border styles, and other visual styling attributes.
9

10
```python { .api }
11
def getColor(value, default=None):
12
    """
13
    Convert color string/value to ReportLab color object.
14
    
15
    Args:
16
        value: Color specification (name, hex, rgb, etc.)
17
        default: Default color if conversion fails
18
    
19
    Returns:
20
        Color object or default value
21
    """
22

23
def getBorderStyle(value, default=None):
24
    """
25
    Get border style from CSS value.
26
    
27
    Args:
28
        value (str): CSS border style value
29
        default: Default style if not recognized
30
    
31
    Returns:
32
        Border style constant
33
    """
34
```
35

36
### Size and Dimension Conversion
37

38
Functions for converting various size units (px, pt, %, em, etc.) to numeric values.
39

40
```python { .api }
41
def getSize(value, relative=0, base=None, default=0.0):
42
    """
43
    Convert size strings to numeric values.
44
    
45
    Args:
46
        value: Size specification (e.g., '12px', '1.5em', '100%')
47
        relative (float): Relative size base
48
        base: Base size for relative calculations
49
        default (float): Default value if conversion fails
50
    
51
    Returns:
52
        float: Numeric size value
53
    """
54

55
def getCoords(x, y, w, h, pagesize):
56
    """
57
    Calculate coordinates for page positioning.
58
    
59
    Args:
60
        x, y, w, h: Position and dimension values
61
        pagesize: Page size tuple (width, height)
62
    
63
    Returns:
64
        tuple: Calculated coordinates
65
    """
66

67
def getBox(box, pagesize):
68
    """
69
    Parse CSS box dimensions.
70
    
71
    Args:
72
        box: Box specification
73
        pagesize: Page size for calculations
74
    
75
    Returns:
76
        Box dimensions object
77
    """
78
```
79

80
### Text and Language Processing
81

82
Utilities for text alignment, language detection, and RTL text processing.
83

84
```python { .api }
85
def getAlign(value, default=TA_LEFT):
86
    """
87
    Get text alignment from CSS value.
88
    
89
    Args:
90
        value (str): CSS text-align value
91
        default: Default alignment
92
    
93
    Returns:
94
        Alignment constant
95
    """
96

97
def arabic_format(text, language):
98
    """
99
    Format Arabic/RTL text properly.
100
    
101
    Args:
102
        text (str): Input text
103
        language (str): Language code
104
    
105
    Returns:
106
        str: Formatted text for RTL display
107
    """
108

109
def detect_language(name):
110
    """
111
    Detect language from text/font name.
112
    
113
    Args:
114
        name (str): Text or font name
115
    
116
    Returns:
117
        str: Detected language code
118
    """
119
```
120

121
### Data Conversion Utilities
122

123
Basic data type conversion functions.
124

125
```python { .api }
126
def getBool(s):
127
    """
128
    Convert string to boolean value.
129
    
130
    Args:
131
        s: Input value to convert
132
    
133
    Returns:
134
        bool: Boolean value
135
    """
136

137
def getFloat(s):
138
    """
139
    Convert string to float value.
140
    
141
    Args:
142
        s: Input value to convert
143
    
144
    Returns:
145
        float: Float value
146
    """
147

148
def toList(value, *, cast_tuple=True):
149
    """
150
    Convert value to list format.
151
    
152
    Args:
153
        value: Input value to convert to list
154
        cast_tuple (bool): Whether to cast tuples to lists
155
    
156
    Returns:
157
        list: Value converted to list format
158
    """
159
```
160

161
### Advanced Attribute and Object Utilities
162

163
Functions for manipulating object attributes and applying transformations.
164

165
```python { .api }
166
def transform_attrs(obj, keys, container, func, extras=None):
167
    """
168
    Apply function to set of object attributes with container checking.
169
    
170
    Args:
171
        obj: Target object to modify
172
        keys: List of attribute names to process
173
        container: Container to check for key existence
174
        func: Function to apply to attribute values
175
        extras: Additional parameters for function
176
    """
177

178
def copy_attrs(obj1, obj2, attrs):
179
    """
180
    Copy list of attributes from one object to another.
181
    
182
    Args:
183
        obj1: Destination object
184
        obj2: Source object
185
        attrs: List of attribute names to copy
186
    """
187

188
def set_value(obj, attrs, value, *, do_copy=False):
189
    """
190
    Set same value to multiple object attributes.
191
    
192
    Args:
193
        obj: Target object
194
        attrs: List of attribute names to set
195
        value: Value to assign
196
        do_copy (bool): Whether to copy the value
197
    """
198
```
199

200
### Frame and Position Utilities
201

202
Advanced positioning and frame dimension calculations.
203

204
```python { .api }
205
def getFrameDimensions(data, page_width, page_height):
206
    """
207
    Calculate frame dimensions for page layout.
208
    
209
    Args:
210
        data: Frame specification data
211
        page_width (float): Page width in points
212
        page_height (float): Page height in points
213
    
214
    Returns:
215
        tuple: Frame dimensions (x, y, width, height)
216
    """
217

218
def getPos(position, pagesize):
219
    """
220
    Parse position coordinates from string specification.
221
    
222
    Args:
223
        position: Position specification string
224
        pagesize: Page size tuple (width, height)
225
    
226
    Returns:
227
        tuple: Parsed coordinates (x, y)
228
    """
229
```
230

231
### Asian Font Support
232

233
Utilities for handling Asian fonts and language detection.
234

235
```python { .api }
236
def get_default_asian_font():
237
    """
238
    Get default Asian font configuration.
239
    
240
    Returns:
241
        str: Default Asian font name
242
    """
243

244
def set_asian_fonts(fontname):
245
    """
246
    Configure Asian font mappings.
247
    
248
    Args:
249
        fontname (str): Asian font name to configure
250
    """
251

252
def frag_text_language_check(context, frag_text):
253
    """
254
    Check and format text fragment based on language context.
255
    
256
    Args:
257
        context: Processing context with language settings
258
        frag_text: Text fragment to check
259
    
260
    Returns:
261
        str: Language-appropriate formatted text
262
    """
263
```
264

265
## Constants
266

267
```python { .api }
268
# Size conversion constants
269
MM = 72.0 / 25.4  # Millimeters to points
270
DPI96 = 72.0 / 96.0  # 96 DPI to points
271

272
# Font size tables
273
ABSOLUTE_SIZE_TABLE = {  # CSS absolute font sizes
274
    'xx-small': 6.0,
275
    'x-small': 7.5,
276
    'small': 8.9,
277
    'medium': 10.0,
278
    'large': 12.0,
279
    'x-large': 15.0,
280
    'xx-large': 20.0
281
}
282

283
RELATIVE_SIZE_TABLE = {  # CSS relative font sizes
284
    'smaller': 0.8,
285
    'larger': 1.2
286
}
287

288
# Text alignments
289
ALIGNMENTS = {
290
    'left': TA_LEFT,
291
    'center': TA_CENTER,
292
    'right': TA_RIGHT,
293
    'justify': TA_JUSTIFY
294
}
295

296
# Color name mappings
297
COLOR_BY_NAME = {
298
    'black': (0, 0, 0),
299
    'white': (1, 1, 1),
300
    'red': (1, 0, 0),
301
    # ... extensive color name mappings
302
}
303
```