1.. _constants:
2
3******************************
4Module Functions and Constants
5******************************
6
7.. currentmodule:: cairo
8
9
10Module Functions
11================
12
13.. function:: cairo_version()
14
15   :returns: the encoded version
16   :rtype: int
17
18   Returns the version of the underlying C cairo library, encoded in a single
19   integer.
20
21.. function:: cairo_version_string()
22
23   :returns: the encoded version
24   :rtype: str
25
26   Returns the version of the underlying C cairo library as a human-readable
27   string of the form "X.Y.Z".
28
29.. function:: get_include()
30
31    :returns: a path to the directory containing the C header files
32    :rtype: str
33
34    Gives the include path which should be passed to the compiler.
35
36    .. versionadded:: 1.16.0
37
38
39Module Constants
40================
41
42.. data:: version
43
44   the pycairo version, as a string
45
46.. data:: version_info
47
48   the pycairo version, as a tuple
49
50.. data:: CAIRO_VERSION
51
52    The version of cairo available at compile-time in the same format as
53    returned by :func:`cairo_version`
54
55    .. versionadded:: 1.18.0
56
57.. data:: CAIRO_VERSION_STRING
58
59    A human-readable string literal containing the version of cairo available
60    at compile-time, in the form of "X.Y.Z".
61
62    .. versionadded:: 1.18.0
63
64.. data:: CAIRO_VERSION_MAJOR
65
66    The major component of the version of cairo available at compile-time.
67
68    .. versionadded:: 1.18.0
69
70.. data:: CAIRO_VERSION_MINOR
71
72    The minor component of the version of cairo available at compile-time.
73
74    .. versionadded:: 1.18.0
75
76.. data:: CAIRO_VERSION_MICRO
77
78    The micro component of the version of cairo available at compile-time.
79
80    .. versionadded:: 1.18.0
81
82
83.. _constants_HAS:
84
85cairo.HAS
86---------
87
881 if the feature is present in the underlying C cairo library, 0 otherwise.
89
90.. data:: HAS_ATSUI_FONT
91          HAS_FT_FONT
92          HAS_GLITZ_SURFACE
93          HAS_IMAGE_SURFACE
94          HAS_PDF_SURFACE
95          HAS_PNG_FUNCTIONS
96          HAS_PS_SURFACE
97          HAS_RECORDING_SURFACE
98          HAS_SVG_SURFACE
99          HAS_USER_FONT
100          HAS_QUARTZ_SURFACE
101          HAS_WIN32_FONT
102          HAS_WIN32_SURFACE
103          HAS_XCB_SURFACE
104          HAS_XLIB_SURFACE
105
106.. data:: HAS_MIME_SURFACE
107
108    .. versionadded:: 1.12.0
109
110.. data:: HAS_SCRIPT_SURFACE
111
112    .. versionadded:: 1.12.0
113
114.. data:: HAS_TEE_SURFACE
115
116    .. versionadded:: 1.15.3
117
118
119.. _constants_TAG:
120
121cairo.TAG
122---------
123
124.. data:: TAG_DEST
125    :annotation: = "cairo.dest"
126
127    Create a destination for a hyperlink. Destination tag attributes are
128    detailed at Destinations.
129
130    .. versionadded:: 1.18.0 Only available with cairo 1.15.10+
131
132.. data:: TAG_LINK
133    :annotation: = "Link"
134
135    Create hyperlink. Link tag attributes are detailed at Links.
136
137    .. versionadded:: 1.18.0 Only available with cairo 1.15.10+
138
139
140.. _constants_MIME_TYPE:
141
142cairo.MIME_TYPE
143---------------
144
145.. data:: MIME_TYPE_JP2
146    :annotation: = "image/jp2"
147
148    The Joint Photographic Experts Group (JPEG) 2000 image coding standard
149    (ISO/IEC 15444-1).
150
151    .. versionadded:: 1.12.0
152
153.. data:: MIME_TYPE_JPEG
154    :annotation: = "image/jpeg"
155
156    The Joint Photographic Experts Group (JPEG) image coding standard (ISO/IEC
157    10918-1).
158
159    .. versionadded:: 1.12.0
160
161.. data:: MIME_TYPE_PNG
162    :annotation: = "image/png"
163
164    The Portable Network Graphics image file format (ISO/IEC 15948).
165
166    .. versionadded:: 1.12.0
167
168.. data:: MIME_TYPE_URI
169    :annotation: = "text/x-uri"
170
171    URI for an image file (unofficial MIME type).
172
173    .. versionadded:: 1.12.0
174
175.. data:: MIME_TYPE_UNIQUE_ID
176    :annotation: = "application/x-cairo.uuid"
177
178    Unique identifier for a surface (cairo specific MIME type). All surfaces
179    with the same unique identifier will only be embedded once.
180
181    .. versionadded:: 1.12.0
182
183.. data:: MIME_TYPE_CCITT_FAX
184    :annotation: = "image/g3fax"
185
186    Group 3 or Group 4 CCITT facsimile encoding (International
187    Telecommunication Union, Recommendations T.4 and T.6.)
188
189    .. versionadded:: 1.18.0 Only available with cairo 1.15.10+
190
191.. data:: MIME_TYPE_CCITT_FAX_PARAMS
192    :annotation: = "application/x-cairo.ccitt.params"
193
194    Decode parameters for Group 3 or Group 4 CCITT facsimile encoding. See
195    `CCITT Fax Images
196    <https://cairographics.org/manual/cairo-PDF-Surfaces.html#ccitt>`__.
197
198    .. versionadded:: 1.18.0 Only available with cairo 1.15.10+
199
200.. data:: MIME_TYPE_EPS
201    :annotation: = "application/postscript"
202
203    Encapsulated PostScript file. Encapsulated PostScript File Format
204    Specification
205
206    .. versionadded:: 1.18.0 Only available with cairo 1.15.10+
207
208.. data:: MIME_TYPE_EPS_PARAMS
209    :annotation: = "application/x-cairo.eps.params"
210
211    Embedding parameters Encapsulated PostScript data. See Embedding EPS files.
212
213    .. versionadded:: 1.18.0 Only available with cairo 1.15.10+
214
215.. data:: MIME_TYPE_JBIG2
216    :annotation: = "application/x-cairo.jbig2"
217
218    Joint Bi-level Image Experts Group image coding standard (ISO/IEC 11544).
219
220    .. versionadded:: 1.18.0
221
222.. data:: MIME_TYPE_JBIG2_GLOBAL
223    :annotation: = "application/x-cairo.jbig2-global"
224
225    Joint Bi-level Image Experts Group image coding standard (ISO/IEC 11544)
226    global segment.
227
228    .. versionadded:: 1.18.0
229
230.. data:: MIME_TYPE_JBIG2_GLOBAL_ID
231    :annotation: = "application/x-cairo.jbig2-global-id"
232
233    An unique identifier shared by a JBIG2 global segment and all JBIG2 images
234    that depend on the global segment.
235
236    .. versionadded:: 1.18.0
237
238
239Other Constants
240---------------
241
242.. data:: PDF_OUTLINE_ROOT
243    :annotation: = 0
244
245    The root outline item in :meth:`PDFSurface.add_outline`
246
247    .. versionadded:: 1.18.0 Only available with cairo 1.15.10+
248
249
250Other Classes and Functions
251===========================
252
253.. class:: text()
254
255    This type only exists for documentation purposes. It represents
256    :obj:`python:str`/:obj:`python:unicode` under Python 2 and
257    :obj:`python3:str` under Python 3.
258
259
260.. class:: pathlike()
261
262    This type only exists for documentation purposes.
263
264    On Unix it is equal to what Python allows as a filesystem path. On Windows
265    with cairo <=1.15.8 only ANSI paths are supported. With cairo >=1.15.10
266    all paths are supported as long as they don't contain surrogates.
267
268    Many functions taking a path also allow passing in an already open Python
269    file object. This can be used to support all Python filesystem paths
270    independent of the underlying platform or cairo version.
271
272    .. versionadded:: 1.15.1
273        Older versions only supported a subset of :obj:`str` paths
274