QGIS API Documentation  3.37.0-Master (a5b4d9743e8)
qgis_sip.h
Go to the documentation of this file.
1 /***************************************************************************
2  qgis_sip - QGIS SIP Macros
3 
4  ---------------------
5  begin : 4.5.2017
6  copyright : (C) 2017 by Denis Rouzaud
7  email : [email protected]
8  ***************************************************************************
9  * *
10  * This program is free software; you can redistribute it and/or modify *
11  * it under the terms of the GNU General Public License as published by *
12  * the Free Software Foundation; either version 2 of the License, or *
13  * (at your option) any later version. *
14  * *
15  ***************************************************************************/
16 #ifndef QGIS_SIP_H
17 #define QGIS_SIP_H
18 
19 /*
20  * if written, the SIP file will not be generated automatically
21  * or can be also defined directly in the file (to avoid including this)
22  */
23 #define SIP_NO_FILE
24 
25 /*
26  * the module will be included if the condition is met
27  */
28 #define SIP_IF_MODULE(condition)
29 
30 
31 /*
32  * https://www.riverbankcomputing.com/static/Docs/sip/annotations.html?highlight=keepreference#function-annotation-Transfer
33  *
34  * Example QgsVectorLayer::setDiagramRenderer
35  */
36 #define SIP_TRANSFER
37 
38 
39 /*
40  * https://www.riverbankcomputing.com/static/Docs/sip/annotations.html#argument-annotation-GetWrapper
41  *
42  */
43 #define SIP_GETWRAPPER
44 
45 /*
46  * https://www.riverbankcomputing.com/static/Docs/sip/annotations.html?highlight=keepreference#function-annotation-TransferBack
47  */
48 #define SIP_TRANSFERBACK
49 
50 /*
51  * https://www.riverbankcomputing.com/static/Docs/sip/annotations.html?highlight=keepreference#function-annotation-TransferThis
52  */
53 #define SIP_TRANSFERTHIS
54 
55 /*
56  * https://www.riverbankcomputing.com/static/Docs/sip/annotations.html#argument-annotation-Out
57  */
58 #define SIP_OUT
59 
60 /*
61  * https://www.riverbankcomputing.com/static/Docs/sip/annotations.html#argument-annotation-In
62  */
63 #define SIP_IN
64 
65 /*
66  * Combination of
67  * https://www.riverbankcomputing.com/static/Docs/sip/annotations.html#argument-annotation-In
68  * and
69  * https://www.riverbankcomputing.com/static/Docs/sip/annotations.html#argument-annotation-Out
70  */
71 #define SIP_INOUT
72 
73 /*
74  * https://www.riverbankcomputing.com/static/Docs/sip/annotations.html#function-annotation-Factory
75  */
76 #define SIP_FACTORY
77 
78 /*
79  * https://www.riverbankcomputing.com/static/Docs/sip/annotations.html#class-annotation-PyName
80  */
81 #define SIP_PYNAME(name)
82 
83 /*
84  * https://www.riverbankcomputing.com/static/Docs/sip/annotations.html#argument-annotation-KeepReference
85  */
86 #define SIP_KEEPREFERENCE
87 
88 /*
89  * https://www.riverbankcomputing.com/static/Docs/sip/annotations.html#argument-annotation-Array
90  */
91 #define SIP_ARRAY
92 
93 /*
94  * https://www.riverbankcomputing.com/static/Docs/sip/annotations.html#argument-annotation-ArraySize
95  */
96 #define SIP_ARRAYSIZE
97 
98 /*
99  * https://www.riverbankcomputing.com/static/Docs/sip/annotations.html#class-annotation-NoDefaultCtors
100  */
101 #define SIP_NODEFAULTCTORS
102 
103 /*
104  * https://www.riverbankcomputing.com/static/Docs/sip/annotations.html?highlight=deprecated#function-annotation-Deprecated
105  */
106 #define SIP_DEPRECATED
107 
108 /*
109  * https://www.riverbankcomputing.com/static/Docs/sip/annotations.html?highlight=constrained#argument-annotation-Constrained
110  */
111 #define SIP_CONSTRAINED
112 
113 /*
114  * https://www.riverbankcomputing.com/static/Docs/sip/annotations.html?highlight=external#class-annotation-External
115  */
116 #define SIP_EXTERNAL
117 
118 /*
119  * https://www.riverbankcomputing.com/static/Docs/sip/annotations.html?highlight=allownone
120  */
121 #define SIP_ALLOWNONE
122 
123 /*
124  * discard line
125  */
126 #define SIP_SKIP
127 
128 /*
129  * force a private line to be written
130  */
131 #define SIP_FORCE
132 
133 /*
134  * change the method access to private
135  */
136 #define SIP_MAKE_PRIVATE
137 
138 /*
139  * specify an alternative type for SIP argument or return value
140  */
141 #define SIP_PYALTERNATIVETYPE(type)
142 
143 /*
144  * specify an alternative default value for SIP argument
145  */
146 #define SIP_PYARGDEFAULT(value)
147 
148 /*
149  * remove argument in SIP method
150  */
151 #define SIP_PYARGREMOVE
152 
153 /*
154  * remove argument in SIP method only for Qt version >= 6
155  */
156 #define SIP_PYARGREMOVE6
157 
158 /*
159  * rename argument in SIP method
160  */
161 #define SIP_PYARGRENAME(pyname)
162 
163 /*
164  * https://www.riverbankcomputing.com/static/Docs/sip/annotations.html?highlight=keepreference#function-annotation-ReleaseGIL
165  */
166 #define SIP_RELEASEGIL
167 
168 /*
169  * https://www.riverbankcomputing.com/static/Docs/sip/annotations.html?highlight=keepreference#function-annotation-HoldGIL
170  */
171 #define SIP_HOLDGIL
172 
173 /*
174  * Will insert a `%Feature feature` directive in sip files
175  */
176 #define SIP_FEATURE(feature)
177 
178 /*
179  * Will insert a `%If feature` directive in sip files
180  */
181 #define SIP_IF_FEATURE(feature)
182 
183 /*
184  * Will place the current line with an `%If feature` directive in sip file
185  */
186 #define SIP_WHEN_FEATURE(feature)
187 
188 /*
189  * Convert to subclass code
190  */
191 #define SIP_CONVERT_TO_SUBCLASS_CODE(code)
192 
193 /*
194  * Virtual error handler (/VirtualErrorHandler/)
195  */
196 #define SIP_VIRTUALERRORHANDLER(name)
197 
198 /*
199  * Throw - adds deprecated c++ throw calls for sip. Required for sip to add appropriate
200  * try/catch blocks around call and catch the correct exception, otherwise only
201  * unknown generic exceptions are available for Python code.
202  */
203 #define SIP_THROW(name, ...)
204 
205 /*
206  * Will insert a `%End` directive in sip files
207  */
208 #define SIP_END
209 
210 /*
211  * Class level annotation for abstract classes
212  */
213 #define SIP_ABSTRACT
214 
215 /*
216  * Virtual catcher code
217  */
218 #define SIP_VIRTUAL_CATCHER_CODE(code)
219 
220 /*
221  * Force documentation of templates
222  * Available for SIP 4.19.7+
223  */
224 #define SIP_DOC_TEMPLATE
225 
226 /*
227  * Specifies the type of the value returned by the function as it will appear in any
228  * generated docstrings and PEP 484 type hints. It is usually used with results of type
229  * SIP_PYOBJECT to provide a more specific type.
230  * Available for SIP 4.18+
231  */
232 #define SIP_TYPEHINT(type)
233 
234 /*
235  * Sip supports the final keyword since version 4.19.0, earlier than that
236  * we will have build issues because it tries to override final methods.
237  */
238 #if SIP_VERSION < 0x041300
239 #if defined FINAL
240 #undef FINAL
241 #endif
242 #define FINAL override
243 #endif
244 
245 /*
246  * Define Python special method (bool, repr, etc.) using the given method or code
247  * sipify.pl will create a dedicated python file named according to the class
248  * and located in python/{module}/auto_additions/{classname}.py
249  * a simple method name can be provided (e.g. isValid) and sipify will create the proper code
250  * or some Python code can be provided:
251  *
252  * SIP_PYTHON_SPECIAL_BOOL( isValid )
253  * => sipify => MyClass.__bool__ = lambda self: self.isValid()
254  *
255  * SIP_PYTHON_SPECIAL_REPR( "'<MyClass {}>'format(self.toString())'" )
256  * => sipify => MyClass.__repr__ = lambda self: '<MyClass {}>'format(self.toString())'
257  */
258 #define SIP_PYTHON_SPECIAL_BOOL(method_or_code)
259 #define SIP_PYTHON_SPECIAL_REPR(method_or_code)
260 
261 /*
262  * If one reformat an enum to a scope based enum
263  * sipify will take care of monkey patching to keep
264  * API compatibility.
265  * If OUTSIDE_CLASS is defined, the enum has been unnested
266  * from the class, and it will be used for monkey patching
267  * e.g. QgsMapLayer.VectorLayer = QgsMapLayerType.VectorLayer
268  * These macros should be removed in QGIS 4
269  */
270 #define SIP_MONKEYPATCH_SCOPEENUM
271 #define SIP_MONKEYPATCH_SCOPEENUM_UNNEST(OUTSIDE_CLASS,FORMERNAME)
272 #define SIP_MONKEYPATCH_FLAGS_UNNEST(OUTSIDE_CLASS,FORMERNAME)
273 #define SIP_MONKEYPATCH_COMPAT_NAME(FORMERNAME)
274 
275 /*
276  * Directive to define the base type for a enum
277  */
278 #define SIP_ENUM_BASETYPE(type)
279 
280 /*
281  * Directive to define a Python property;
282  */
283 #define SIP_PROPERTY(name,getter,setter)
284 
285 /*
286  * Directive to indicate that following code is only available with Qt 5 version
287  */
288 #define SIP_PYQT5_RUN
289 
290 
291 #endif // QGIS_SIP_H